From 197f890b7b287c1a4aee075537b7eaa468220e6c Mon Sep 17 00:00:00 2001 From: Chris Doherty <chris.doherty4@gmail.com> Date: Tue, 29 Nov 2022 08:27:18 -0600 Subject: [PATCH] Revamp CONTRIBUTING.md --- CONTRIBUTING.md | 66 ++++++++++++++++++++++++++++--------------------- README.md | 32 ++++++------------------ 2 files changed, 45 insertions(+), 53 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f177b2ea..46ab5af0 100644 --- 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 \ No newline at end of file diff --git a/README.md b/README.md index 046ad1b2..6236c213 100644 --- 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