diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 9b55be796..a2e713e00 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,4 +1,5 @@ # 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 security@hashicorp.com. @@ -14,7 +15,9 @@ 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. ## Getting Started + ### Some Ways to Contribute + * Report potential bugs. * Suggest product enhancements. * Increase our test coverage. @@ -24,7 +27,8 @@ work on an issue, comment on it first and tell us the approach you want to take. 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: +### Reporting an Issue + >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: [Discuss Forum](https://discuss.hashicorp.com/c/consul/29), [FAQ](https://www.consul.io/docs/faq.html), or [Guides](https://www.consul.io/docs/guides/index.html). @@ -53,42 +57,47 @@ issue. Stale issues will be closed. 4. 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. + linked. Any change a Consul user might need to know about will include a + changelog entry in the PR. 5. The issue is closed. -## Building Consul - -If you wish to work on Consul itself, you'll first need [Go](https://golang.org) -installed (The version of Go should match the one of our [CI config's](https://github.com/hashicorp/consul/blob/main/.circleci/config.yml) Go image). - - -Next, clone this repository and then 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`. - ## 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: +### Prerequisites -1. Navigate to `$GOPATH/src/github.com/hashicorp/consul` -2. Rename the existing remote's name: `git remote rename origin upstream`. -3. Add your fork as a remote by running - `git remote add origin `. For example: - `git remote add origin https://github.com/myusername/consul`. -4. Checkout a feature branch: `git checkout -t -b new-feature` -5. Make changes -6. Push changes to the fork when ready to submit PR: - `git push -u origin new-feature` +If you wish to work on Consul itself, you'll first need to: +- install [Go](https://golang.org) (the version should match that of our + [CI config's](https://github.com/hashicorp/consul/blob/main/.circleci/config.yml) Go image). +- [fork the Consul repo](../docs/contributing/fork-the-project.md) -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. +### Building Consul ->Note: If you make any changes to the code, run `gofmt -s -w` to automatically format the code according to Go standards. +To build Consul, run `make dev`. In a few moments, you'll have a working +`consul` executable in `consul/bin` and `$GOPATH/bin`: -## Testing +>Note: `make dev` will build for your local machine's os/architecture. If you wish to build for all os/architecture combinations, use `make`. + +### Modifying the Code + +#### Code Formatting + +Go provides [tooling to apply consistent code formatting](https://golang.org/doc/effective_go#formatting). +If you make any changes to the code, run `gofmt -s -w` to automatically format the code according to Go standards. + +#### Updating Go Module Dependencies + +If a dependency is added or change, run `go mod tidy` to update `go.mod` and `go.sum`. + +#### Developer Documentation + +Developer-focused documentation about the Consul code base is under [./docs], +and godoc package document can be read at [pkg.go.dev/github.com/hashicorp/consul]. + +[./docs]: ../docs/README.md +[pkg.go.dev/github.com/hashicorp/consul]: https://pkg.go.dev/github.com/hashicorp/consul + +### Testing 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. [Go's built-in test tool](https://golang.org/pkg/cmd/go/internal/test/) 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. @@ -99,22 +108,44 @@ Examples (run from the repository root): When a pull request is opened CI will run all tests and lint to verify the change. -## Go Module Dependencies +### Submitting a Pull Request -If a dependency is added or change, run `go mod tidy` to update `go.mod` and `go.sum`. +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. -## Developer Documentation +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 [applying URL-decoding of resource names across the whole HTTP API](https://github.com/hashicorp/consul/issues/11258) +started with [iterating on the right approach for a few endpoints](https://github.com/hashicorp/consul/pull/11335) +before applying more broadly. -Documentation about the Consul code base is under [./docs], -and godoc package document can be read at [pkg.go.dev/github.com/hashicorp/consul]. +When you're ready to submit a pull request: +1. Review the [list of checklists](#checklists) for common changes and follow any + that apply to your work. +2. 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). +3. Open the PR from your fork against base repository `hashicorp/consul` and branch `main`. + - [Link the PR to its associated issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue). +4. 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 [draft PR](https://github.blog/2019-02-14-introducing-draft-pull-requests/) + if your changes aren't finalized but would benefit from in-process feedback. +5. If there's any reason Consul users might need to know about this change, + [add a changelog entry](../docs/contributing/add-a-changelog-entry.md). +6. 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. +7. 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. -[./docs]: ../docs/README.md -[pkg.go.dev/github.com/hashicorp/consul]: https://pkg.go.dev/github.com/hashicorp/consul +#### Checklists -### Checklists - -Some common changes that many PRs require such as adding config fields, are -documented through checklists. - -Please check in [docs/](../docs/) for any `checklist-*.md` files that might help -with your change. +Some common changes that many PRs require are documented through checklists as +`checklist-*.md` files in [docs/](../docs/), including: +- [Adding config fields](../docs/config/checklist-adding-config-fields.md) \ No newline at end of file diff --git a/docs/contributing/add-a-changelog-entry.md b/docs/contributing/add-a-changelog-entry.md new file mode 100644 index 000000000..4bba2e668 --- /dev/null +++ b/docs/contributing/add-a-changelog-entry.md @@ -0,0 +1,42 @@ +# Adding a Changelog Entry + +Any change that a Consul user might need to know about should have a changelog entry. + +What doesn't need a changelog entry? +- Docs changes +- Typos fixes, unless they are in a public-facing API +- Code changes we are certain no Consul users will need to know about + +To include a [changelog entry](../.changelog) in a PR, commit a text file +named `.changelog/.txt`, where `` is the number associated with the open +PR in Github. The text file should describe the changes in the following format: + +```` +```release-note: +: +``` +```` + +Valid values for `` include: +- `feature`: for the addition of a new feature +- `improvement`: for an improvement (not a bug fix) to an existing feature +- `bug`: for a bug fix +- `security`: for any Common Vulnerabilities and Exposures (CVE) resolutions +- `breaking-change`: for any change that is not fully backwards-compatible +- `deprecation`: for functionality which is now marked for removal in a future release + +`` is meant to categorize the functionality affected by the change. +Some common values are: +- `checks`: related to node or service health checks +- `cli`: related to the command-line interface and its commands +- `config`: related to configuration changes (e.g., adding a new config option) +- `connect`: catch-all for the Connect subsystem that provides service mesh functionality + if no more specific `` applies +- `http`: related to the HTTP API interface and its endpoints +- `dns`: related to DNS functionality +- `ui`: any change related to the built-in Consul UI (`website/` folder) + +Look in the [`.changelog/`](../.changelog) folder for examples of existing changelog entries. + +If a PR deserves multiple changelog entries, just add multiple entries separated by a newline +in the format described above to the `.changelog/.txt` file. diff --git a/docs/contributing/fork-the-project.md b/docs/contributing/fork-the-project.md new file mode 100644 index 000000000..941c0fe27 --- /dev/null +++ b/docs/contributing/fork-the-project.md @@ -0,0 +1,19 @@ +# Forking the Consul Repo + +Community members wishing to contribute code to Consul must fork the Consul project +(`your-github-username/consul`). Branches pushed to that fork can then be submitted +as pull requests to the upstream project (`hashicorp/consul`). + +To locally clone the repo so that you can pull the latest from the upstream project +(`hashicorp/consul`) and push changes to your own fork (`your-github-username/consul`): + +1. [Create the forked repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo#forking-a-repository) (`your-github-username/consul`) +2. Clone the `hashicorp/consul` repository and `cd` into the folder +3. Make `hashicorp/consul` the `upstream` remote rather than `origin`: + `git remote rename origin upstream`. +4. Add your fork as the `origin` remote. For example: + `git remote add origin https://github.com/myusername/consul` +5. Checkout a feature branch: `git checkout -t -b new-feature` +6. [Make changes](../../.github/CONTRIBUTING.md#modifying-the-code) +7. Push changes to the fork when ready to [submit a PR](../../.github/CONTRIBUTING.md#submitting-a-pull-request): + `git push -u origin new-feature` \ No newline at end of file