Development workflow

Cloning and branches

git clone https://github.com/coredns/coredns
cd coredns
git checkout -b feature/my-thing master

The default branch is master. PRs target master directly. Long-lived feature branches are uncommon — most changes are small enough to land directly.

Day-to-day commands

Most edits cycle through:

# Build to make sure it still compiles.
make

# Run the tests touched by the change.
go test ./plugin/forward/...

# Format.
gofmt -s -w plugin/forward/

# Lint.
golangci-lint run ./...

If you touched plugin.cfg or any of the generators (directives_generate.go, owners_generate.go):

make gen

make gen regenerates core/plugin/zplugin.go and core/dnsserver/zdirectives.go. Commit both files alongside your plugin.cfg change. The verify-make-gen workflow will fail your PR if you forget.

If you touched a plugin's README.md:

make -f Makefile.doc

This rebuilds man/coredns-<name>.7 from the README. Commit the updated man page. The make.doc workflow checks for staleness on every PR.

Commit messages

Follow conventional commits where it makes sense (feat:, fix:, lint:, chore:, test:, build(deps):). The history shows a mix — older commits were freer-form, modern ones lean on the prefix. Keep titles under ~70 characters.

git log --oneline produces examples like:

feat(proxyproto): add proxy protocol support (#7738)
fix(kubernetes): sanitize non-UTF-8 host in metrics (#7998)
lint(revive): fix unused-parameter violations (#7980)
test(forward): restore defaultTimeout (#7981)
plugin/forward: add max_age option to enforce an absolute connection lifetime (#7903)

Both feat:-style and plugin/<name>:-style are accepted.

Use git commit -s to add the DCO sign-off automatically.

Submitting a PR

1. Push your branch to your fork (or to coredns/coredns if you have write access).
2. Open the PR with the provided template. Mention the issue you're addressing, summarise the change, and describe how you tested it.
3. CI runs automatically. Common failures and remedies are in Tooling.
4. A CODEOWNERS-listed reviewer will pick up the PR. Plugin-scoped owners are at the bottom of CODEOWNERS; project-wide changes need a steering committee member.
5. Address review feedback in new commits on the same branch (so reviewers can see the diff between iterations). Squashing is done at merge time.

Most PRs merge within a week if they are small and well-tested. Larger PRs can sit longer.

Releases

Cut by the steering committee on a roughly quarterly cadence. The release flow is in Makefile.release and .github/workflows/release.yml:

1. Tag the commit (git tag v1.x.y).
2. The GitHub workflow builds binaries for every supported architecture and pushes them to the release.
3. Makefile.docker builds and pushes the Docker images.
4. Release notes go into notes/coredns-<version>.md as part of the same PR. The notes file is generated from the merged commits and curated.

There is a deprecation policy in README.md:

When there is a backwards incompatible change in CoreDNS the following process is followed: x.y.z announce, x.y+1.0 implement with backward-compatible parsing, x.y+1.1 remove the legacy parsing.

So a deprecation always spans at least three releases.

Stale issues and PRs

The stale.yml workflow auto-closes inactive issues and PRs. If a reviewer hasn't responded for a long time, ping the issue or #coredns on Slack rather than opening a duplicate PR.

Plugin-specific workflows

For an existing plugin, a typical PR touches:

• plugin/<name>/<file>.go — the change.
• plugin/<name>/<file>_test.go — tests.
• plugin/<name>/README.md — docs (and man/coredns-<name>.7 after make -f Makefile.doc).
• plugin/<name>/metrics.go — if a new metric is introduced.

For a new plugin, see the staged process in CONTRIBUTING.md: start with a README.md-only PR to settle the syntax, then follow up with setup.go, the handler, tests, and finally the plugin.cfg insertion. Add an owners.json so owners_generate.go updates CODEOWNERS.