How to contribute

This section is the contributor guide. The canonical sources are CONTRIBUTING.md (PR/issue process) and README.md (build, test, run); these pages summarize them and then go deeper into patterns the team uses.

Picking up work

• Issues: each PR should reference an existing GitHub issue, except for trivial fixes. If no issue exists yet, open one first to coordinate. The lifecycle and triage rules are in CONTRIBUTING.md.
• Discuss: for design-heavy changes, post on the Vault discussion forum before writing code.
• Stale issues: closed automatically after 30 days without activity. Don't be shy about reopening if the problem still applies.

Pull request expectations

Every PR ships:

1. A description that explains what, how, and why.
2. Tests — unit tests for logic changes, acceptance tests if you touch a backend with external dependencies.
3. A changelog entry under changelog/<PR_ID>.txt using the release-note:CATEGORY syntax. Categories are security, change, feature, improvement, bug. See CONTRIBUTING.md for examples.
4. Sign the CLA — required for non-HashiCorp contributors.
5. Consistent style — make fmtcheck and make lint must pass.

The code-review bot checks the changelog format automatically (.github/workflows/changelog-checker.yml).

Workflow at a glance

1. Open or claim an issue.
2. Branch from main (or the appropriate release/x.y branch for backports).
3. Implement and add tests.
4. Run make fmt, make lint, and the relevant make test targets locally.
5. Create the changelog file under changelog/.
6. Open the PR, expect review, address feedback.
7. A maintainer merges; backports to active release branches happen via the Vault Automation bot.

See Development workflow for the day-to-day commands and Testing for which test target to run when.

Definition of done

Vault sets a high bar:

• New CLI commands have integration tests that actually run them.
• New API endpoints update the OpenAPI spec generation in sdk/framework/openapi.go.
• New plugin types follow the v5 protocol in sdk/plugin/plugin_v5.go.
• New configuration fields are wired into both HCL parsing (internalshared/configutil/) and the vault operator diagnose checks (command/operator_diagnose.go).
• Anything that touches storage updates the migration logic in vault/init.go if the layout changes.
• UI changes have ember-cli tests and pass pnpm test.

Subtopics

• Development workflow — branches, commits, the local feedback loop
• Testing — unit, acceptance, Enos, UI test conventions
• Debugging — logs, race detectors, deadlock detection
• Patterns and conventions — error handling, logging, request flow, Enterprise stubs
• Tooling — Makefile, golangci-lint, copywrite, generators