Development workflow

Practical loop for building, testing, and iterating on etcd.

1. Find work

CONTRIBUTING.md lists the labels to filter issues by:

• good first issue — for newcomers
• help wanted — bite-sized, well-scoped
• priority/important — actively-needed

Flaky test work is also welcomed; see type/flake issues. The project tracks flake-history in tools/testgrid-analysis/.

2. Set up the environment

Two supported paths:

• Local Linux/amd64 with the Go toolchain pinned in .go-version, plus protoc 3.20.3, make, yamllint, jq, and xz.
• Devcontainer via .devcontainer/devcontainer.json (works in VS Code Codespaces or any tool that speaks the containers.dev spec).

Verify the install:

make build       # produces bin/etcd, bin/etcdctl, bin/etcdutl
./bin/etcd --version

3. Branching and commits

• Fork on GitHub, then git checkout -b feature/your-change.
• Keep PRs small (the project explicitly prefers multiple <500 LoC PRs over one large one).
• Sign off every commit (git commit -s adds Signed-off-by:). Etcd enforces the DCO via the DCO file.

The conventional commit format is:

<package>: <one-line "what">

<optional "why" body>

Signed-off-by: First Last <you@example.com>

<package> is usually a short directory name (e.g. etcdserver, clientv3, mvcc, etcdctl).

4. Iterate locally

Common loops:

make test-unit                              # fast feedback
make test-integration GO_TEST_FLAGS='-run TestKVPut'
make verify                                 # before pushing
make fix                                    # auto-fix lint/format issues

Run a single member for manual testing:

./bin/etcd --logger=zap --log-level=debug
./bin/etcdctl put k v

For a 3-node cluster, goreman start against Procfile is the canonical local cluster.

5. Submit a pull request

• Open the PR against main.
• Link to an issue, or describe the motivation if no issue exists.
• Mark the PR a draft (Convert to draft) while you iterate.
• Once green, request review from people who recently touched the area (git log is your friend) or from OWNERS/OWNERS_ALIASES.

First-time contributors will see their PR labelled needs-ok-to-test. An etcd-io org member must comment /ok-to-test to let CI run. Once CI is green, ping reviewers; depending on impact 1–2 maintainer approvals are required.

6. Merge and backport

tide (Prow's merge bot) handles the actual merge once required labels are present (lgtm, approved, no do-not-merge/*). Cherry-picks to release branches use scripts/cherrypick.sh; CI hooks under .github/workflows/cherrypick-bot-ok-to-test.yaml automate the auth handshake.

7. After-merge tasks

Don't close the originating issue until:

• All linked PRs (potentially multiple per issue) are merged.
• Necessary backports to release-3.5 / release-3.6 are complete.

The project explicitly calls this out in CONTRIBUTING.md.