Project: Consul (Orchestration & Management / Service Mesh)
File: CONTRIBUTING.md

Note: We take Consul's security and our users' trust very seriously. If you believe you have found a security issue in Consul, please responsibly disclose by contacting us at security@hashicorp.com. First: if you're unsure or afraid of anything, just ask or submit the issue or pull request anyways. You won't be yelled at for giving your best effort. The worst that can happen is that you'll be politely asked to change something. We appreciate any sort of contributions, and don't want a wall of rules to get in the way of that. That said, if you want to ensure that a pull request is likely to be merged, talk to us! A great way to do this is in issues themselves. When you want to work on an issue, comment on it first and tell us the approach you want to take. Report potential bugs. Suggest product enhancements. Increase our test coverage. Fix a . Implement a requested . Improve our guides and documentation. Consul's , , and are deployed from this repo. Respond to questions about usage on the issue tracker or the Consul section of the [HashiCorp forum]: (https://discuss.hashicorp.com/c/consul) Note: Issues on GitHub for Consul are intended to be related to bugs or feature requests. Questions should be directed to other community resources such as the: , , or . Make sure you test against the latest released version. It is possible we already fixed the bug you're experiencing. However, if you are on an older version of Consul and feel the issue is critical, do let us know. Check existing issues (both open and closed) to make sure it has not been reported previously. Provide a reproducible test case. If a contributor can't reproduce an issue, then it dramatically lowers the chances it'll get fixed. Aim to respond promptly to any questions made by the Consul team on your issue. Stale issues will be closed. The issue is reported. The issue is verified and categorized by a Consul maintainer. Categorization is done via tags. For example, bugs are tagged as "bug". Unless it is critical, the issue is left for a period of time (sometimes many weeks), giving outside contributors a chance to address the issue. The issue is addressed in a pull request or commit. The issue will be referenced in the commit message so that the code that fixes it is clearly linked. Any change a Consul user might need to know about will include a changelog entry in the PR. The issue is closed. If you wish to work on Consul itself, you'll first need to: install To build Consul, run `make dev`. In a few moments, you'll have a working `consul` executable in `consul/bin` and `$GOPATH/bin`: Note: `make dev` will build for your local machine's os/architecture. If you wish to build for all os/architecture combinations, use `make`. Go provides . If you make any changes to the code, run `gofmt -s -w` to automatically format the code according to Go standards. Group imports using `goimports -local github.com/hashicorp/consul/` to keep in their own section. Example: ``` import ( "context" "fmt" "net/http" "github.com/hashicorp/go-cleanhttp" "github.com/mitchellh/mapstructure" "github.com/hashicorp/consul/api" "github.com/hashicorp/consul/lib" ) ``` If a dependency is added or change, run `go mod tidy` to update `go.mod` and `go.sum`. Developer-focused documentation about the Consul code base is under [./docs], and godoc package document can be read at

During development, it may be more convenient to check your work-in-progress by running only the tests which you expect to be affected by your changes, as the full test suite can take several minutes to execute. allows specifying a list of packages to test and the `-run` option to only include test names matching a regular expression. The `go test -short` flag can also be used to skip slower tests. Examples (run from the repository root): `go test -v ./connect` will run all tests in the connect package (see `./connect` folder) `go test -v -run TestRetryJoin ./command/agent` will run all tests in the agent package (see `./command/agent` folder) with name substring `TestRetryJoin` When a pull request is opened CI will run all tests and lint to verify the change. Before writing any code, we recommend: Create a Github issue if none already exists for the code change you'd like to make. Write a comment on the Github issue indicating you're interested in contributing so maintainers can provide their perspective if needed. Keep your pull requests (PRs) small and open them early so you can get feedback on approach from maintainers before investing your time in larger changes. For example, see how started with before applying more broadly. When you're ready to submit a pull request: Review the for common changes and follow any that apply to your work. Include evidence that your changes work as intended (e.g., add/modify unit tests; describe manual tests you ran, in what environment, and the results including screenshots or terminal output). Open the PR from your fork against base repository `hashicorp/consul` and branch `main`. . Include any specific questions that you have for the reviewer in the PR description or as a PR comment in Github. If there's anything you find the need to explain or clarify in the PR, consider whether that explanation should be added in the source code as comments. You can submit a if your changes aren't finalized but would benefit from in-process feedback. If there's any reason Consul users might need to know about this change, . Add labels to your pull request. A table of commonly use labels is below. If you have any questions about which to apply, feel free to call it out in the PR or comments. | Label | When to Use | | | | | `pr/no-changelog` | This PR does not have an intended changelog entry | | `pr/no-metrics-test` | This PR does not require any testing for metrics | | `backport/1.12.x` | Backport the changes in this PR to the targeted release branch. Consult the page to view active releases. Website documentation merged to the latest release branch is deployed immediately | Other labels may automatically be added by the Github Action CI. After you submit, the Consul maintainers team needs time to carefully review your contribution and ensure it is production-ready, considering factors such as: security, backwards-compatibility, potential regressions, etc. After you address Consul maintainer feedback and the PR is approved, a Consul maintainer will merge it. Your contribution will be available from the next major release (e.g., 1.x) unless explicitly backported to an existing or previous major release by the maintainer. Any backport labels will generate an additional PR to the targeted release branch. These will be linked in the original PR. Assuming the tests pass, the PR will be merged automatically. If the tests fail, it is you responsibility to resolve the issues with backports and request another reviewer. Some common changes that many PRs require are documented through checklists as `checklist-*.md` files in , including: