chore: add changelog howto in CONTRIBUTING (#681)

Author: lucix-aws

.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

CONTRIBUTING.md

@@ -32,14 +32,50 @@ 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.
-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.
-6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
+   * Ensure your modifications are accompanied by a [changelog entry](#Changelog) where necessary.
+4. Ensure local tests pass.
+5. Commit to your fork using clear commit messages.
+6. Send us a pull request, answering any default questions in the pull request interface.
+7. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
 
 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:<ul><li>The issue number, if local to this repository (eg. `#12345`)</li><li>A fully-qualified issue ID (eg.`awslabs/aws-sdk-kotlin#12345`)</li><li>A fully-qualified URL (eg. `https://issuetracker.com/12345`)</li></ul> |
+| `module`      | `string`   | no       |                                              | The area of the code affected by your changes. If unsure, leave this value unset.                                                                                                                                                                                                                                                                |
+
+The filename of an entry is arbitrary. We recommend `<id>.json`, where `<id>` corresponds to the `id` field of the entry
+itself.
+
+Entries in the `.changes/` directory are automatically rolled into the main `CHANGELOG.md` file in every release.
+
+If you believe that your modifications do not warrant a changelog entry, you can add the `no-changelog` label to your
+pull request. The label will suppress the CI that blocks merging in the absence of a changelog, though the reviewer(s)
+of your request may disagree and ask that you add one anyway.
+
+#### Example
+```json
+{
+  "id": "263ea6ab-4b75-41a8-9c37-821c30d7b9e5",
+  "type": "feature",
+  "description": "Add multiplatform support for URL parsing.",
+  "issues": [
+    "awslabs/smithy-kotlin#12345"
+  ]
+}
+```
+
 
 When submitting a pull request please have your commits follow these guidelines: