diff --git a/.github/workflows/changelog-verification.yml b/.github/workflows/changelog-verification.yml index 755fc510bda..547b155abf8 100644 --- a/.github/workflows/changelog-verification.yml +++ b/.github/workflows/changelog-verification.yml @@ -19,6 +19,6 @@ jobs: if: ${{ failure() }} run: | echo "::error ::No new/updated changelog entry found in /.changes directory. Please either:" - echo "::error ::* Add a changelog entry (in most cases) –or–" + echo "::error ::* Add a changelog entry (see CONTRIBUTING.md for instructions) –or–" echo "::error ::* Add the 'no-changelog' label to this PR (in rare cases not warranting a changelog entry)" exit 1 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c54620cac3..841a3da97b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,6 +47,7 @@ To send us a pull request, please: 1. Fork the repository. 2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change. + * Ensure your modifications are accompanied by a [changelog entry](#Changelog) where necessary. 3. Ensure local tests pass. 4. Commit to your fork using clear commit messages. 5. Send us a pull request, answering any default questions in the pull request interface. @@ -55,6 +56,40 @@ To send us a pull request, please: GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and [creating a pull request](https://help.github.com/articles/creating-a-pull-request/). +### Changelog +Merges to this repository must include one or more changelog entries which describe the modifications made. + +Entries are placed in the top-level `.changes/` directory. An entry is a file containing a JSON object with the +following fields: + +| Field name | Type | Required | Enum | Description | +|---------------|------------|----------|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | `string` | yes | | A unique identifier for this entry. We recommend you generate a UUID for this field. | +| `type` | `string` | yes | `bugfix`, `feature`, `documentation`, `misc` | The type of change being made. | +| `description` | `string` | yes | | A description of the change being made. | +| `issues` | `string[]` | no | | A list of references to any related issues in the relevant repositories. A reference can be specified in several ways: