Mirroristas/etcd
2
0
Fork 0
mirror of https://github.com/etcd-io/etcd.git synced 2024-09-27 06:25:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

documentation: improve CONTRIBUTING.md

Browse Source 
Signed-off-by: Chun-Hung Tseng <henrybear327@gmail.com>
This commit is contained in:
Chun-Hung Tseng 2024-04-09 15:29:06 +02:00
parent 6e0a4c7f82
commit 39ccdb0b91
No known key found for this signature in database
GPG Key ID: EF93C20F55FB48BB
1 changed files with 33 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
CONTRIBUTING.md
View File

@ -1,42 +1,42 @@
# How to contribute
etcd is Apache 2.0 licensed and accepts contributions via GitHub pull requests.
This document outlines basics of contributing to etcd.
This document outlines the basics of contributing to etcd.
This is a rough outline of what a contributor's workflow looks like:
* [Find something to work on](#Find-something-to-work-on)
* [Check for flaky tests](#Check-for-flaky-tests)
* [Setup development environment](#Setup-development-environment)
* [Set up development environment](#Set-up-development-environment)
* [Implement your change](#Implement-your-change)
* [Commit your change](#Commit-your-change)
* [Create a pull request](#Create-a-pull-request)
* [Get your pull request reviewed](#Get-your-pull-request-reviewed)
If you have any questions about, please reach out using one of the methods listed in [contact].
If you have any questions, please reach out using one of the methods listed in [contact].
[contact]: ./README.md#Contact
## Learn more about etcd
Before making a change please look through resources below to learn more about etcd and tools used for development.
Before making a change please look through the resources below to learn more about etcd and tools used for development.
* Please learn about [Git](https://github.com/git-guides) version control system used in etcd.
* Read the [etcd learning resources](https://etcd.io/docs/v3.5/learning/)
* Read the [etcd community membership](/Documentation/contributor-guide/community-membership.md)
* Watch [etcd deep dive](https://www.youtube.com/watch?v=D2pm6ufIt98&t=927s)
* Watch [etcd code walk through](https://www.youtube.com/watch?v=H3XaSF6wF7w)
* Watch [etcd code walkthrough](https://www.youtube.com/watch?v=H3XaSF6wF7w)
## Find something to work on
All the work in etcd project is tracked in [github issue tracker].
All the work in the etcd project is tracked in [GitHub issue tracker].
Issues should be properly labeled making it easy to find something for you.
Depending on your interest and experience you should check different labels:
* If you are just starting, check issues labeled with [good first issue].
* When you feel more comfortable in your contributions, checkout [help wanted].
* Advanced contributors can try to help with issues labeled [priority/important] covering most relevant work at the time.
* When you feel more comfortable in your contributions, check out [help wanted].
* Advanced contributors can try to help with issues labeled [priority/important] covering the most relevant work at the time.
If any of aforementioned labels don't have unassigned issues, please [contact] one of the [maintainers] asking to triage more issues.
If any of the aforementioned labels don't have unassigned issues, please [contact] one of the [maintainers] asking to triage more issues.
[github issue tracker]: https://github.com/etcd-io/etcd/issues
[good first issue]: https://github.com/search?type=issues&q=org%3Aetcd-io+state%3Aopen++label%3A%22good+first+issue%22
@ -62,7 +62,7 @@ For more, because etcd uses Kubernetes' prow infrastructure to run CI jobs, the
If you find any flaky tests on testgrid, please
1. Check [existing issues](https://github.com/etcd-io/etcd/issues?q=is%3Aissue+is%3Aopen+label%3Atype%2Fflake) to see if an issue has already been opened for this test. If not, open an issue with the `type/flake` label.
2. Try to reproduce the flaky test on your machine via `stress`, for example to reproduce the failure of `TestPeriodicSkipRevNotChange`:
2. Try to reproduce the flaky test on your machine via `stress`, for example, to reproduce the failure of `TestPeriodicSkipRevNotChange`:
```bash
cd server/etcdserver/api/v3compactor
@ -73,29 +73,29 @@ stress -p=8 ./v3compactor.test
```
3. Fix it.
## Setup development environment
## Set up development environment
The etcd project supports two options for development:
1. Manually setup local environment.
2. Automatically setup [devcontainer](https://containers.dev).
1. Manually set up the local environment.
2. Automatically set up [devcontainer](https://containers.dev).
For both options the only supported architecture is `linux-amd64`. Bug reports for other environments will generally be ignored. Supporting new environments requires introduction of proper tests and maintainer support that is currently lacking in the etcd project.
For both options, the only supported architecture is `linux-amd64`. Bug reports for other environments will generally be ignored. Supporting new environments requires the introduction of proper tests and maintainer support that is currently lacking in the etcd project.
If you would like etcd to support your preferred environment you can [file an issue].
### Option 1 - Manually setup local environment
### Option 1 - Manually set up the local environment
This is the original etcd development environment, is most supported and is backwards compatible for development of older etcd versions.
This is the original etcd development environment, is most supported, and is backward compatible for the development of older etcd versions.
Follow the steps below to setup the environment:
Follow the steps below to set up the environment:
- [Clone the repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository)
- Install Go by following [installation](https://go.dev/doc/install). Please check minimal go version in [go.mod file](./go.mod#L3).
- Install Go by following [installation](https://go.dev/doc/install). Please check the minimal go version in [go.mod file](./go.mod#L3).
- Install build tools:
- `make`: For debian based distributions you can run `sudo apt-get install build-essential`
- `protoc`: You can download for your os. Use version [`v3.20.3`](https://github.com/protocolbuffers/protobuf/releases/tag/v3.20.3).
- `yamllint`: For debian based distribution you can run `sudo apt-get install yamllint`
- `make`: For Debian-based distributions you can run `sudo apt-get install build-essential`
- `protoc`: You can download it for your os. Use version [`v3.20.3`](https://github.com/protocolbuffers/protobuf/releases/tag/v3.20.3).
- `yamllint`: For Debian-based distribution you can run `sudo apt-get install yamllint`
- Verify that everything is installed by running `make build`
Note: `make build` runs with `-v`. Other build flags can be added through env `GO_BUILD_FLAGS`, **if required**. Eg.,
@ -103,17 +103,17 @@ Note: `make build` runs with `-v`. Other build flags can be added through env `G
GO_BUILD_FLAGS="-buildmode=pie" make build
```
### Option 2 - Automatically setup devcontainer
### Option 2 - Automatically set up devcontainer
This is a more recently added environment that aims to make it faster for new contributors to get started with etcd. This option is supported for etcd versions 3.6 onwards.
This option can be [used locally](https://code.visualstudio.com/docs/devcontainers/tutorial) on a system running Visual Studio Code and Docker, or in a remote cloud based [Codespaces](https://github.com/features/codespaces) environment.
This option can be [used locally](https://code.visualstudio.com/docs/devcontainers/tutorial) on a system running Visual Studio Code and Docker, or in a remote cloud-based [Codespaces](https://github.com/features/codespaces) environment.
To get started, create a codespace for this repository by clicking this 👇
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=11225014)
A codespace will open in a web-based version of Visual Studio Code. The [dev container](.devcontainer/devcontainer.json) is fully configured with software needed for this project.
A codespace will open in a web-based version of Visual Studio Code. The [dev container](.devcontainer/devcontainer.json) is fully configured with the software needed for this project.
**Note**: Dev containers is an open spec which is supported by [GitHub Codespaces](https://github.com/codespaces) and [other tools](https://containers.dev/supporting).
@ -121,30 +121,30 @@ A codespace will open in a web-based version of Visual Studio Code. The [dev con
## Implement your change
etcd code should follow coding style suggested by the Golang community.
etcd code should follow the coding style suggested by the Golang community.
See the [style doc](https://github.com/golang/go/wiki/CodeReviewComments) for details.
Please ensure that your change passes static analysis (requires [golangci-lint](https://golangci-lint.run/usage/install/)):
- `make verify` to verify if all checks pass.
- `make verify-*` to verify a single check, for example `make verify-bom` to verify if bill-of-materials.json file is up-to-date.
- `make verify-*` to verify a single check, for example, `make verify-bom` to verify if `bill-of-materials.json` file is up-to-date.
- `make fix` to fix all checks.
- `make fix-*` to fix a single checks, for example `make fix-bom` to update bill-of-materials.json.
- `make fix-*` to fix a single check, for example, `make fix-bom` to update `bill-of-materials.json`.
Please ensure that your change passes tests.
- `make test-unit` to run unit tests.
- `make test-integration` to run integration tests.
- `make test-e2e` to run e2e tests.
All changes are expected to come with unit test.
All changes are expected to come with a unit test.
All new features are expected to have either e2e or integration tests.
## Commit your change
etcd follows a rough convention for commit messages:
* First line:
* Should start name of package (for example `etcdserver`, `etcdctl`) followed by `:` character.
* Should start with the name of the package (for example `etcdserver`, `etcdctl`) followed by the `:` character.
* Describe the `what` behind the change
* Optionally author might provide the `why` behind the change in the main commit message body.
* Optionally, the author might provide the `why` behind the change in the main commit message body.
* Last line should be `Signed-off-by: firstname lastname <email@example.com>` (can be automatically generate by providing `--signoff` to git commit command).
Example of commit message:
@ -162,9 +162,9 @@ Signed-off-by: FirstName LastName <github@github.com>
## Create a pull request
Please follow [making a pull request](https://docs.github.com/en/get-started/quickstart/contributing-to-projects#making-a-pull-request) guide.
Please follow the [making a pull request](https://docs.github.com/en/get-started/quickstart/contributing-to-projects#making-a-pull-request) guide.
If you are still working on the pull request, you can convert it to draft by clicking `Convert to draft` link just below list of reviewers.
If you are still working on the pull request, you can convert it to a draft by clicking `Convert to draft` link just below the list of reviewers.
Multiple small PRs are preferred over single large ones (>500 lines of code).
@ -180,6 +180,6 @@ It might happen that some unrelated tests on your PR are failing, due to their f
In such cases please [file an issue] to deflake the problematic test and ask one of [maintainers] to rerun the tests.
If all checks were successful feel free to reach out for review from people that were involved in the original discussion or [maintainers].
Depending on complexity of the PR it might require between 1 and 2 maintainers to approve your change before merging.
Depending on the complexity of the PR it might require between 1 and 2 maintainers to approve your change before merging.
Thanks for contributing!