Add changelog creation to contributor docs

.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 
+### 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.
 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],
+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.

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/<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.

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`