Revamp CONTRIBUTING.md

tinkerbell · Nov 29, 2022 · 197f890 · 197f890
1 parent 9e289d6
commit 197f890
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 53 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,48 +1,58 @@
-## Hello Contributors!
+## Contributing
 
-Thanks for your interest!
-We're so glad you're here.
+### Contents
 
-### Important Resources
+### Expectations
 
-#### bugs: [https://github.com/tinkerbell/hegel/issues](https://github.com/tinkerbell/hegel/issues)
+When contributing you must adhere to the [Code of Conduct](coc). All contributions must be signed 
+off in accordance with the [Developer Certificate of Origin](dco).
 
-### Code of Conduct
+### Developing
 
-Please read and understand the code of conduct found [here](https://github.com/tinkerbell/.github/blob/main/CODE_OF_CONDUCT.md).
+#### Pre-requisits
 
-### DCO Sign Off
+- Make
+- [Docker](https://www.docker.com/)
+- [Go](https://go.dev/) installed at the version specified in the [CI workflow](ci-workflow)
+- [Python 3](https://www.python.org/) installed and available on the path as `python3`
+- [Pip](https://pypi.org/project/pip/) for Python 3
+- [cURL](https://curl.se/)
 
-Please read and understand the DCO found [here](docs/DCO.md).
+#### Developer workflow
 
-### Environment Details
+All builds happen via the Makefile at the root of the project. `make help` provides the set of
+most commonly used targets with short descriptions.
 
-#### Nix
+When developing, ensure you write unit tests and leverage the various `test` Makefile targets
+to validate your code.
 
-This repo's build environment can be reproduced using `nix`.
+The CI invokes little more than a Makefile target for each job. The one exception is image building
+as we optimize for cross-platform builds. In brief, we cross compile using the Go toolchain before
+constructing the image by copying the appropriate binary for the target platform.
 
-##### Install Nix
 
-Follow the [Nix installation](https://nixos.org/download.html) guide to setup Nix on your box.
+#### Package structure
 
-##### Load Dependencies
+Given Hegel is not a library of reusable components most of its code lives in `/internal`.
+Appropriate justification will be required to create packages outside `/internal`.
 
-Loading build dependencies is as simple as running `nix-shell` or using [lorri](https://github.com/nix-community/lorri).
-If you have `direnv` installed the included `.envrc` will make that step automatic.
+The `main()` func for Hegel is located in `/cmd/hegel`. It is extremely short with the core command
+logic residing in `/internal/cmd`.
 
-### How to Submit Change Requests
+Hegel is split into frontends and backends. The frontends are the core domain logic while the 
+backends are clients into a particular kind of backend. Frontends declare the models they require 
+and the backends are responsible for retrieving and supplying the data in the required format. 
+See the [frontend-backend][frontend-backend] Plant UML for a depiction.
 
-Please submit change requests and / or features via [Issues](https://github.com/tinkerbell/hegel/issues).
-There's no guarantee it'll be changed, but you never know until you try.
-We'll try to add comments as soon as possible, though.
+### How to submit change requests
 
-### How to Report a Bug
+Please submit change requests and features via [Issues].
 
-Bugs are problems in code, in the functionality of an application or in its UI design; you can submit them through [Issues](https://github.com/tinkerbell/hegel/issues).
+### How to report bugs
 
-## Code Style Guides
+Please submit bugs via [Issues].
 
-#### Protobuf
-
-Please ensure protobuf related files are generated along with _any_ change to a protobuf file.
-In the future CI will enforce this, but for the time being does not.
+[issues]: https://github.com/tinkerbell/hegel/issues
+[coc]: https://github.com/tinkerbell/.github/blob/main/CODE_OF_CONDUCT.md
+[dco]: /docs/DCO.md
+[ci-workflow}]: /.github/workflows/ci.yaml
diff --git a/README.md b/README.md
@@ -35,37 +35,19 @@ For information on how to create a release, see [RELEASING.md][releasing].
 THe project is currently v0 meaning compatibility is best effort. If you have any specific concerns 
 do not hesitate to raise an issue.
 
-## Development
-
-All builds happen via the Makefile at the root of the project. `make help` provides the set of
-most commonly used targets with short descriptions.
-
-When developing, ensure you write unit tests and leverage the various `test` Makefile targets
-to validate your code.
-
-The CI invokes little more than a Makefile target for each job. The one exception is image building
-as we optimize for cross-platform builds. In brief, we cross compile using the Go toolchain before
-constructing the image by copying the appropriate binary for the target platform.
-
-##### Quick start
+## Quick Start
 
 ```sh
 # Build a Docker image for the host platform.
-make image
-```
-
-### Package Structure
+$ make image
 
-Given Hegel is not a library of reusable components most of its code lives in `/internal`.
-Appropriate justification will be required to create packages outside `/internal`.
+# See the "How to impersonate an instance?" FAQ to launch Hegel. Ensure you use `hegel:latest`
+# as the image name to use the newly built image.
+```
 
-The `main()` func for Hegel is located in `/cmd/hegel`. It is extremely brief with the core command
-logic residing in `/internal/cmd`.
+## Contributing
 
-Hegel is split into frontends and backends. The frontends can be thought of as the core domain
-while the backends are clients into a particular kind of backend. Frontends declare the models
-they require and the backends are responsible for retrieving and supplying the data in the required
-format. See the [frontend-backend][frontend-backend] Plant UML for a depiction.
+See [CONTRIBUTING.md](/CONTRIBUTING.md).
 
 ## FAQ