From a36bcfff1fefe3b77644a4b8c1c5815c6477048a Mon Sep 17 00:00:00 2001 From: Marek Siarkowicz Date: Tue, 13 Sep 2022 14:53:37 +0200 Subject: [PATCH] Improve contributor guidelines and simplify development commands Signed-off-by: Marek Siarkowicz --- CONTRIBUTING.md | 158 ++++++++++++++++++++++----------------- Makefile | 192 +++++++++--------------------------------------- README.md | 48 +++++------- 3 files changed, 143 insertions(+), 255 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 450892296..7d84fed9a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,46 +1,92 @@ # How to contribute -etcd is Apache 2.0 licensed and accepts contributions via GitHub pull requests. This document outlines some of the conventions on commit message formatting, contact points for developers, and other resources to help get contributions into etcd. - -# Email and chat - -- Email: [etcd-dev](https://groups.google.com/forum/?hl=en#!forum/etcd-dev) -- Slack: [#etcd](https://kubernetes.slack.com/messages/C3HD8ARJ5/details/) - -## Getting started - -- Fork the repository on GitHub -- Read the README.md for build instructions - -## Reporting bugs and creating issues - -Reporting bugs is one of the best ways to contribute. However, a good bug report has some very specific qualities, so please read over our short document on [reporting bugs](https://etcd.io/docs/latest/reporting_bugs) before submitting a bug report. This document might contain links to known issues, another good reason to take a look there before reporting a bug. - -## Contribution flow +etcd is Apache 2.0 licensed and accepts contributions via GitHub pull requests. +This document outlines 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) +* [Setup development environment](#Setup-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) -- Create a topic branch from where to base the contribution. This is usually main. -- Make commits of logical units. -- Make sure commit messages are in the proper format (see below). -- Push changes in a topic branch to a personal fork of the repository. -- Submit a pull request to etcd-io/etcd. -- The PR must receive a LGTM from two maintainers found in the MAINTAINERS file. +If you have any questions about, please reach out using one of the methods listed in [contact]. -Thanks for contributing! +[contact]: ./README.md#Contact -### Code style +## Learn more about etcd -The coding style suggested by the Golang community is used in etcd. See the [style doc](https://github.com/golang/go/wiki/CodeReviewComments) for details. +Before making a change please look through resources below to learn more about etcd and tools used for development. -Please follow this style to make etcd easy to review, maintain and develop. +* 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 contributing guides](https://github.com/etcd-io/etcd/tree/main/Documentation/contributor-guide) +* 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) -### Format of the commit message +## Find something to work on -We follow a rough convention for commit messages that is designed to answer two -questions: what changed and why. The subject line should feature the what and -the body of the commit should describe the why. +All the work in 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 conformable in your contributions, checkout [help wanted]. +* Advanced contributors can try to help with issues labeled [important] covering 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. + +[github issue tracker]: https://github.com/etcd-io/etcd/issues +[good first issue]: https://github.com/etcd-io/etcd/labels/good%20first%20issue +[help wanted]: https://github.com/etcd-io/etcd/labels/help%20wanted +[maintainers]: https://github.com/etcd-io/etcd/blob/main/MAINTAINERS +[important]: https://github.com/etcd-io/etcd/labels/important + +## Setup development environment + +etcd supported development environments include only linux-amd64. +Bug reports for any non-supported environments will be ignored. +Supporting new environments requires introduction of proper tests and maintainer support that is currently lacking in etcd project. +If you want help etcd support your preferred environment, please [file an issue]. + +Setup 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 build tools (make): + - For ubuntu and debian run `sudo apt-get install build-essentials` +- Verify that everything is installed by running `make build` + +[file an issue]: https://github.com/etcd-io/etcd/issues/new/choose + +## Implement your change + +etcd code should follow 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: +- `make test-fmt` to format code. +- `make lint` to run linter (requires [golangci-lint](https://golangci-lint.run/usage/install/)) +- `make lint-fix` to fix linter errors (requires [golangci-lint](https://golangci-lint.run/usage/install/)) + +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 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. + * Describe the `what` behind the change +* Optionally author might provide the `why` behind the change in the main commit message body. +* Last line should be `Signed-off-by: firstname lastname ` (can be automatically generate by providing `--signoff` to git commit command). + +Example of commit message: ``` etcdserver: add grpc interceptor to log info on incoming requests @@ -50,50 +96,24 @@ remote client info, request content (with value field redacted), request handling latency, response size, etc. Uses zap logger if available, otherwise uses capnslog. -Fixes #38 +Signed-off-by: FirstName LastName ``` -The format can be described more formally as follows: +## Create a pull request -``` -: - - - -