Revamp CONTRIBUTING.md

CONTRIBUTING.md

@@ -1,48 +1,57 @@
-## Hello Contributors!
+## Contributing
 
-Thanks for your interest!
-We're so glad you're here.
 
-### 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

README.md

@@ -28,11 +28,27 @@ Hegel releases with semantic versioning. Each release produces 3 image tags usin
 minor (m) and patch (p) numbers: `v[M].[m].[p]`, `v[M].[m]` and `v[M]`. The `v[M]` will always point
 to the latest minor release. `v[M].[m]` will always point to the latest patch release.
 
+For information on how to create a release, see [RELEASING.md][releasing].
+
 ### Version Compatibility
 
 THe project is currently v0 meaning compatibility is best effort. If you have any specific concerns 
 do not hesitate to raise an issue.
 
+## Quick Start
+
+```sh
+# Build a Docker image for the host platform.
+$ make image
+
+# 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.
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](/CONTRIBUTING.md).
+
 ## FAQ
 
 ### How do I impersonate an instance?
@@ -70,4 +86,6 @@ curl -H "X-Forwarded-For: 10.10.10.10" http://localhost:50061/2009-04-04/meta-da
 ```
 
 [cloud-init]: https://cloudinit.readthedocs.io/en/latest/
-[ignition]: https://coreos.github.io/ignition/
+[ignition]: https://coreos.github.io/ignition/
+[releasing]: /RELEASING.md
+[frontend-backend]: /docs/design/frontend-backend.puml