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

Merge pull request #14458 from serathius/contributing

Browse Source 
Improve contributor guidelines and simplify development commands
This commit is contained in:
Benjamin Wang 2022-09-15 06:02:43 +08:00 committed by GitHub
commit 1222269eba
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 143 additions and 255 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

158
CONTRIBUTING.md
View File

@ -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 <email@example.com>` (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 <github@github.com>
```
The format can be described more formally as follows:
## Create a pull request
```
<package>: <what changed>
<BLANK LINE>
<why this change was made>
<BLANK LINE>
<footer>
```
Please follow [making a pull request](https://docs.github.com/en/get-started/quickstart/contributing-to-projects#making-a-pull-request) guide.
The first line is the subject and should be no longer than 70 characters, the second
line is always blank, and other lines should be wrapped at 80 characters. This allows
the message to be easier to read on GitHub as well as in various git tools.
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.
### Pull request across multiple files and packages
Multiple small PRs are preferred over single large ones (>500 lines of code).
If multiple files in a package are changed in a pull request for example:
## Get your pull request reviewed
```
etcdserver/config.go
etcdserver/corrupt.go
```
Before requesting review please ensure that all GitHub checks were successful.
It might happen that some unrelated tests on your PR are failing, due to their flakiness.
In such cases please [file an issue] to deflake the problematic test and ask one of [maintainers] to rerun the tests.
At the end of the review process if multiple commits exist for a single package they
should be squashed/rebased into a single commit before being merged.
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.
```
etcdserver: <what changed>
[..]
```
If a pull request spans many packages these commits should be squashed/rebased into a single
commit using message with a more generic `*:` prefix.
```
*: <what changed>
[..]
```
### Static analysis.
We recommend that you install [golangci-lint](https://golangci-lint.run/usage/install/) and run `make lint`.
We also have a GitHub action to run our linters on every pull request.
Thanks for contributing!

192
Makefile
View File

@ -1,25 +1,3 @@
# run from repository root
# Example:
# make build
# make clean
# make docker-clean
# make docker-start
# make docker-kill
# make docker-remove
UNAME := $(shell uname)
XARGS = xargs
ARCH ?= $(shell go env GOARCH)
# -r is only necessary on GNU xargs.
ifeq ($(UNAME), Linux)
XARGS += -r
endif
XARGS += rm -r
.PHONY: build
build:
GO_BUILD_FLAGS="-v" ./scripts/build.sh
@ -27,8 +5,39 @@ build:
./bin/etcdctl version
./bin/etcdutl version
build_tools:
GO_BUILD_FLAGS="-v" ./scripts/build_tools.sh
.PHONY: test-fmt
test-fmt:
PASSES="fmt" ./scripts/test.sh
.PHONY: test-bom
test-bom:
PASSES="bom" ./scripts/test.sh
.PHONY: test-unit
test-unit:
PASSES="unit" ./scripts/test.sh
.PHONY: test-integration
test-integration:
PASSES="integration" ./scripts/test.sh
.PHONY: test-e2e
test-e2e: build
PASSES="e2e" ./scripts/test.sh
.PHONY: test-e2e-release
test-e2e-release: build
PASSES="release e2e" ./scripts/test.sh
.PHONY: test-all
test-all:
PASSES="fmt bom dep unit integration release e2e" ./scripts/test.sh
lint:
golangci-lint run
lint-fix:
golangci-lint run --fix
clean:
rm -f ./codecov
@ -40,137 +49,4 @@ clean:
rm -rf ./release
rm -rf ./coverage/*.err ./coverage/*.out
rm -rf ./tests/e2e/default.proxy
find ./ -name "127.0.0.1:*" -o -name "localhost:*" -o -name "*.log" -o -name "agent-*" -o -name "*.coverprofile" -o -name "testname-proxy-*" | $(XARGS)
GO_VERSION ?= 1.17.8
ETCD_VERSION ?= $(shell git rev-parse --short HEAD || echo "GitNotFound")
TEST_SUFFIX = $(shell date +%s | base64 | head -c 15)
TEST_OPTS ?= PASSES='unit'
TMP_DIR_MOUNT_FLAG = --tmpfs=/tmp:exec
ifdef HOST_TMP_DIR
TMP_DIR_MOUNT_FLAG = --mount type=bind,source=$(HOST_TMP_DIR),destination=/tmp
endif
TMP_DOCKERFILE:=$(shell mktemp)
# Example:
# GO_VERSION=1.14.3 make build-docker-test
# make build-docker-test
#
# gcloud auth configure-docker
# GO_VERSION=1.14.3 make push-docker-test
# make push-docker-test
#
# gsutil -m acl ch -u allUsers:R -r gs://artifacts.etcd-development.appspot.com
# make pull-docker-test
build-docker-test:
$(info GO_VERSION: $(GO_VERSION))
@sed 's|REPLACE_ME_GO_VERSION|$(GO_VERSION)|g' ./tests/Dockerfile > $(TMP_DOCKERFILE)
docker build \
--network=host \
--tag gcr.io/etcd-development/etcd-test:go$(GO_VERSION) \
--file $(TMP_DOCKERFILE) .
push-docker-test:
$(info GO_VERSION: $(GO_VERSION))
docker push gcr.io/etcd-development/etcd-test:go$(GO_VERSION)
pull-docker-test:
$(info GO_VERSION: $(GO_VERSION))
docker pull gcr.io/etcd-development/etcd-test:go$(GO_VERSION)
# Example:
#
# Local machine:
# TEST_OPTS="PASSES='fmt'" make test
# TEST_OPTS="PASSES='fmt bom dep build unit'" make test
# TEST_OPTS="PASSES='build unit release integration_e2e functional'" make test
# TEST_OPTS="PASSES='build grpcproxy'" make test
#
# grpc-proxy tests:
# TEST_OPTS="PASSES='build grpcproxy'" make test
# HOST_TMP_DIR=/tmp TEST_OPTS="PASSES='build grpcproxy'" make test
.PHONY: test
test:
$(info TEST_OPTS: $(TEST_OPTS))
$(info log-file: test-$(TEST_SUFFIX).log)
$(TEST_OPTS) OUTPUT_FILE="test-$(TEST_SUFFIX).log" ./scripts/test.sh
! egrep "(--- FAIL:|FAIL:|DATA RACE|panic: test timed out|appears to have leaked)" -B50 -A10 test-$(TEST_SUFFIX).log
test-smoke:
$(info log-file: test-$(TEST_SUFFIX).log)
PASSES="fmt build unit" OUTPUT_FILE="test-$(TEST_SUFFIX).log" ./scripts/test.sh
test-full:
$(info log-file: test-$(TEST_SUFFIX).log)
PASSES="fmt build release unit integration functional e2e grpcproxy" OUTPUT_FILE="test-$(TEST_SUFFIX).log" ./scripts/test.sh
ensure-docker-test-image-exists:
make pull-docker-test || ( echo "WARNING: Container Image not found in registry, building locally"; make build-docker-test )
docker-test: ensure-docker-test-image-exists
$(info GO_VERSION: $(GO_VERSION))
$(info ETCD_VERSION: $(ETCD_VERSION))
$(info TEST_OPTS: $(TEST_OPTS))
$(info log-file: test-$(TEST_SUFFIX).log)
$(info HOST_TMP_DIR: $(HOST_TMP_DIR))
$(info TMP_DIR_MOUNT_FLAG: $(TMP_DIR_MOUNT_FLAG))
docker run \
--rm \
$(TMP_DIR_MOUNT_FLAG) \
--mount type=bind,source=`pwd`,destination=/go/src/go.etcd.io/etcd \
gcr.io/etcd-development/etcd-test:go$(GO_VERSION) \
/bin/bash -c "$(TEST_OPTS) OUTPUT_FILE='test-$(TEST_SUFFIX).log' ./scripts/test.sh"
! egrep "(--- FAIL:|FAIL:|DATA RACE|panic: test timed out|appears to have leaked)" -B50 -A10 test-$(TEST_SUFFIX).log
docker-test-coverage:
$(info GO_VERSION: $(GO_VERSION))
$(info ETCD_VERSION: $(ETCD_VERSION))
$(info log-file: docker-test-coverage-$(TEST_SUFFIX).log)
$(info HOST_TMP_DIR: $(HOST_TMP_DIR))
$(info TMP_DIR_MOUNT_FLAG: $(TMP_DIR_MOUNT_FLAG))
docker run \
--rm \
$(TMP_DIR_MOUNT_FLAG) \
--mount type=bind,source=`pwd`,destination=/go/src/go.etcd.io/etcd \
gcr.io/etcd-development/etcd-test:go$(GO_VERSION) \
/bin/bash ./scripts/codecov_upload.sh docker-test-coverage-$(TEST_SUFFIX).log \
! egrep "(--- FAIL:|FAIL:|DATA RACE|panic: test timed out|appears to have leaked)" -B50 -A10 docker-test-coverage-$(TEST_SUFFIX).log
# Example:
# ETCD_VERSION=v3-test make build-docker-release-main
# ETCD_VERSION=v3-test make push-docker-release-main
# gsutil -m acl ch -u allUsers:R -r gs://artifacts.etcd-development.appspot.com
build-docker-release-main:
$(info ETCD_VERSION: $(ETCD_VERSION))
cp ./Dockerfile-release.$(ARCH) ./bin/Dockerfile-release.$(ARCH)
docker build \
--network=host \
--tag gcr.io/etcd-development/etcd:$(ETCD_VERSION) \
--file ./bin/Dockerfile-release.$(ARCH) \
./bin
rm -f ./bin/Dockerfile-release.$(ARCH)
docker run \
--rm \
gcr.io/etcd-development/etcd:$(ETCD_VERSION) \
/bin/sh -c "/usr/local/bin/etcd --version && /usr/local/bin/etcdctl version && /usr/local/bin/etcdutl version"
push-docker-release-main:
$(info ETCD_VERSION: $(ETCD_VERSION))
docker push gcr.io/etcd-development/etcd:$(ETCD_VERSION)
# Recursively analyzes the tree:
lint:
golangci-lint run
# Fixes found issues, if supported by the linter:
lint-fix:
golangci-lint run --fix
find ./ -name "127.0.0.1:*" -o -name "localhost:*" -o -name "*.log" -o -name "agent-*" -o -name "*.coverprofile" -o -name "testname-proxy-*" -delete

48
README.md
View File

@ -33,21 +33,6 @@ See [etcdctl][etcdctl] for a simple command line client.
[vulcand]: https://github.com/vulcand/vulcand
[etcdctl]: https://github.com/etcd-io/etcd/tree/main/etcdctl
## Community meetings
etcd contributors and maintainers have monthly (every four weeks) meetings at 11:00 AM (USA Pacific) on Thursday.
An initial agenda will be posted to the [shared Google docs][shared-meeting-notes] a day before each meeting, and everyone is welcome to suggest additional topics or other agendas.
Meeting recordings are uploaded to [Etcd YouTube channel].
Join Hangouts Meet: [meet.google.com/umg-nrxn-qvs](https://meet.google.com/umg-nrxn-qvs)
Join by phone: +1 405-792-0633‬ PIN: ‪299 906‬#
[shared-meeting-notes]: https://docs.google.com/document/d/16XEGyPBisZvmmoIHSZzv__LoyOeluC5a4x353CX0SIM/edit
[Etcd YouTube channel]: https://www.youtube.com/channel/UC7tUWR24I5AR9NMsG-NYBlg
## Maintainers
[MAINTAINERS](MAINTAINERS) strive to shape an inclusive open source project culture where users are heard and contributors feel respected and empowered. MAINTAINERS maintain productive relationships across different companies and disciplines. Read more about [MAINTAINERS role and responsibilities](GOVERNANCE.md#maintainers).
@ -60,11 +45,8 @@ The easiest way to get etcd is to use one of the pre-built release binaries whic
For more installation guides, please check out [play.etcd.io](http://play.etcd.io) and [operating etcd](https://etcd.io/docs/latest/op-guide).
For those wanting to try the very latest version, [build the latest version of etcd][dl-build] from the `main` branch. This first needs [*Go*](https://golang.org/) installed ([version 1.17+](/go.mod#L3) is required). All development occurs on `main`, including new features and bug fixes. Bug fixes are first targeted at `main` and subsequently ported to release branches, as described in the [branch management][branch-management] guide.
[github-release]: https://github.com/etcd-io/etcd/releases
[branch-management]: https://etcd.io/docs/latest/branch_management
[dl-build]: https://etcd.io/docs/latest/install/#build-from-source
### Running etcd
@ -83,12 +65,6 @@ mv /tmp/etcd-download-test/etcd /usr/local/bin/
etcd
```
If etcd is [built from the main branch][dl-build], run it as below:
```bash
./bin/etcd
```
This will bring up etcd listening on port 2379 for client communication and on port 2380 for server-to-server communication.
Next, let's set a single key, and then retrieve it:
@ -157,10 +133,26 @@ Now it's time to dig into the full etcd API and other guides.
## Contact
- Mailing list: [etcd-dev](https://groups.google.com/forum/?hl=en#!forum/etcd-dev)
- Slack: [#etcd](https://kubernetes.slack.com/messages/C3HD8ARJ5/details/)
- Planning: [milestones](https://github.com/etcd-io/etcd/milestones)
- Bugs: [issues](https://github.com/etcd-io/etcd/issues)
- Email: [etcd-dev](https://groups.google.com/forum/?hl=en#!forum/etcd-dev)
- Slack: [#etcd](https://kubernetes.slack.com/messages/C3HD8ARJ5/details/) channel on Kubernetes ([get an invite](http://slack.kubernetes.io/))
- [Community meetings](#Community-meetings)
### Community meetings
etcd contributors and maintainers have monthly (every four weeks) meetings at 11:00 AM (USA Pacific) on Thursday.
An initial agenda will be posted to the [shared Google docs][shared-meeting-notes] a day before each meeting, and everyone is welcome to suggest additional topics or other agendas.
Meeting recordings are uploaded to official etcd [YouTube channel].
Get calendar invitation by joining [etcd-dev](https://groups.google.com/forum/?hl=en#!forum/etcd-dev) mailing group.
Join Hangouts Meet: [meet.google.com/umg-nrxn-qvs](https://meet.google.com/umg-nrxn-qvs)
Join by phone: +1 405-792-0633‬ PIN: ‪299 906‬#
[shared-meeting-notes]: https://docs.google.com/document/d/16XEGyPBisZvmmoIHSZzv__LoyOeluC5a4x353CX0SIM/edit
[YouTube channel]: https://www.youtube.com/channel/UC7tUWR24I5AR9NMsG-NYBlg
## Contributing