Add changelog creation to contributor docs
This commit is contained in:
parent
d667e8576f
commit
7dda1df00f
|
@ -1,4 +1,5 @@
|
||||||
# Contributing to Consul
|
# Contributing to Consul
|
||||||
|
|
||||||
>**Note:** We take Consul's security and our users' trust very seriously.
|
>**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
|
>If you believe you have found a security issue in Consul, please responsibly
|
||||||
>disclose by contacting us at security@hashicorp.com.
|
>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.
|
work on an issue, comment on it first and tell us the approach you want to take.
|
||||||
|
|
||||||
## Getting Started
|
## Getting Started
|
||||||
|
|
||||||
### Some Ways to Contribute
|
### Some Ways to Contribute
|
||||||
|
|
||||||
* Report potential bugs.
|
* Report potential bugs.
|
||||||
* Suggest product enhancements.
|
* Suggest product enhancements.
|
||||||
* Increase our test coverage.
|
* 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.
|
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)
|
* 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.
|
>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).
|
>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
|
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
|
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.
|
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
|
## Making Changes to Consul
|
||||||
|
|
||||||
The first step to making changes is to fork Consul. Afterwards, the easiest way
|
### Prerequisites
|
||||||
to work on the fork is to set it as a remote of the Consul project:
|
|
||||||
|
|
||||||
1. Navigate to `$GOPATH/src/github.com/hashicorp/consul`
|
If you wish to work on Consul itself, you'll first need to:
|
||||||
2. Rename the existing remote's name: `git remote rename origin upstream`.
|
- install [Go](https://golang.org) (the version should match that of our
|
||||||
3. Add your fork as a remote by running
|
[CI config's](https://github.com/hashicorp/consul/blob/main/.circleci/config.yml) Go image).
|
||||||
`git remote add origin <github url of fork>`. For example:
|
- [fork the Consul repo](../docs/contributing/fork-the-project.md)
|
||||||
`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`
|
|
||||||
|
|
||||||
By following these steps you can push to your fork to create a PR, but the code on disk still
|
### Building Consul
|
||||||
lives in the spot where the go cli tools are expecting to find it.
|
|
||||||
|
|
||||||
>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.
|
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.
|
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.
|
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],
|
When you're ready to submit a pull request:
|
||||||
and godoc package document can be read at [pkg.go.dev/github.com/hashicorp/consul].
|
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
|
#### Checklists
|
||||||
[pkg.go.dev/github.com/hashicorp/consul]: https://pkg.go.dev/github.com/hashicorp/consul
|
|
||||||
|
|
||||||
### Checklists
|
Some common changes that many PRs require are documented through checklists as
|
||||||
|
`checklist-*.md` files in [docs/](../docs/), including:
|
||||||
Some common changes that many PRs require such as adding config fields, are
|
- [Adding config fields](../docs/config/checklist-adding-config-fields.md)
|
||||||
documented through checklists.
|
|
||||||
|
|
||||||
Please check in [docs/](../docs/) for any `checklist-*.md` files that might help
|
|
||||||
with your change.
|
|
|
@ -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.
|
|
@ -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`
|
Loading…
Reference in New Issue