Contributing to Consul
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 firstname.lastname@example.org.
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.
Some Ways to Contribute
- Report potential bugs.
- Suggest product enhancements.
- Increase our test coverage.
- Fix a bug.
- Implement a requested enhancement.
- Improve our guides and documentation. Consul's Guides, Docs, and api godoc 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)
Reporting an Issue:
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.
The issue is closed.
Next, clone this repository into
make dev. In a few moments, you'll have a working
make devwill build for your local machine's os/architecture. If you wish to build for all os/architecture combinations use
Making Changes to Consul
The first step to making changes is to fork Consul. Afterwards, the easiest way to work on the fork is to set it as a remote of the Consul project:
- Navigate to
- Rename the existing remote's name:
git remote rename origin upstream.
- Add your fork as a remote by running
git remote add origin <github url of fork>. For example:
git remote add origin https://github.com/myusername/consul.
- Checkout a feature branch:
git checkout -t -b new-feature
- Make changes
- Push changes to the fork when ready to submit PR:
git push -u origin new-feature
By following these steps you can push to your fork to create a PR, but the code on disk still lives in the spot where the go cli tools are expecting to find it.
Note: If you make any changes to the code, run
make formatto automatically format the code according to Go standards.
Before submitting changes, run all tests locally by typing
The test suite may fail if over-parallelized, so if you are seeing stochastic
GOTEST_FLAGS="-p 2 -parallel 2" make test.
Certain testing patterns such as creating a test
Client in the
TestAgent followed by a session can lead to flaky tests. More generally,
any tests with components that rely on readiness of other components are often
Our makefile has some tooling built in to help validate the stability of single
or package-wide tests. By running the
test-flake goal we spin up a local docker
container that mirrors a CPU constrained version of our CI environment. Here we can
surface uncommon failures that are typically hard to reproduce by re-running
tests multiple times.
The makefile goal accepts the following variables as arguments:
FLAKE_PKG Target package (required)
FLAKE_TEST Target test
FLAKE_CPUS Amount of CPU resources for container
FLAKE_N Number of times to run tests
make test-flake FLAKE_PKG=connect/proxy
make test-flake FLAKE_PKG=connect/proxy FLAKE_TEST=TestUpstreamListener
make test-flake FLAKE_PKG=connect/proxy FLAKE_TEST=TestUpstreamListener FLAKE_CPUS=0.15 FLAKE_N=30
The underlying script dumps the full Consul log output to
the directory of the target package. In the example above it would be
Historically, the defaults for
FLAKE_CPUS (30) and
FLAKE_N (0.15) have been
sufficient to surface a flaky test. If a test is run in this environment and
it does not fail after 30 iterations, it should be sufficiently stable.
Consul currently uses Go Modules for vendoring.
Please only apply the minimal vendor changes to get your PR to work. Consul does not attempt to track the latest version for each dependency.
Some common changes that many PRs require such as adding config fields, are documented through checklists.
Please check in
contributing/ for any
checklist-*.md files that might help
with your change.