Add changelog creation to contributor docs

This commit is contained in:
Jared Kirschner 2021-10-20 08:09:59 -07:00
parent d667e8576f
commit 7dda1df00f
3 changed files with 134 additions and 42 deletions

View File

@ -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 <github url of fork>`. 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)

View File

@ -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/<PR#>.txt`, where `<PR#>` is the number associated with the open
PR in Github. The text file should describe the changes in the following format:
````
```release-note:<change type>
<code area>: <brief description of the improvement you made here>
```
````
Valid values for `<change type>` 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
`<code area>` 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 `<code area>` 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/<PR#>.txt` file.

View File

@ -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`