How to contribute

If you're sending a pull request to hashicorp/consul, this section walks through the workflow, conventions, and tooling. The canonical reference is .github/CONTRIBUTING.md; this page extracts the essentials and points to specifics in the codebase.

Pull request workflow

1. Open an issue describing the bug or feature, then comment that you'd like to work on it. The Consul team triages with type/bug, type/enhancement, etc.
2. Fork the repo and create a feature branch from main.
3. Implement the change. Match the conventions used in the surrounding code (see Patterns and conventions).
4. Add a changelog entry in .changelog/<PR>.txt unless the PR is labeled pr/no-changelog. The template is in docs/contributing/add-a-changelog-entry.md.
5. Run tests for the packages you touched and make lint.
6. Open a PR against hashicorp/consul:main. Apply labels (pr/no-changelog, pr/no-backport, backport/1.22.x, backport/all, etc.) per the README in .changelog/.
7. Address review feedback. Maintainers review for security, backwards compatibility, and Enterprise impact. The CE-only files (*_ce.go) sometimes have Enterprise counterparts that maintainers need to keep in sync.
8. Merge. A maintainer merges; backport bots open follow-up PRs to release branches if labeled.

Definition of done

A change is ready to merge when:

• All make lint checks pass on the touched modules.
• New behavior has unit tests in the relevant *_test.go file. Integration tests in test-integ/ are added for cross-component features.
• Public API changes (HTTP, gRPC, CLI) include or update docs in hashicorp/web-unified-docs (PR linked from this PR).
• A changelog entry exists or pr/no-changelog is set.
• Config-entry, FSM-command, or RPC-protocol changes follow the relevant checklist in docs/contributing/.

Backport policy

CE bug fixes can be backported to the current major. Enterprise additionally backports to N-2 majors and the two latest LTS releases. Apply backport/<version> labels to request automatic backport PRs. The list of active branches lives in .release/versions.hcl.

Sub-pages

• Development workflow — branching, building, smoke-testing
• Testing — unit, integration, race, and golden tests
• Debugging — logging, common errors, troubleshooting
• Patterns and conventions — code style, error handling, file layout
• Tooling — Makefile targets, code generation, lint configuration

Checklists

There are several explicit checklists for common changes in docs/:

• docs/config/checklist-adding-config-fields.md — when adding fields to the agent config schema
• docs/contributing/add-a-changelog-entry.md — changelog format
• docs/contributing/build-an-rpm-and-deb-package.md — packaging
• docs/contributing/fork-the-project.md — fork setup
• Many more checklist-*.md files in docs/ for specific subsystems (FSM, config-entries, gRPC, etc.)