From cf75162584c5513180f8371ca1aa3f02687c8c1d Mon Sep 17 00:00:00 2001
From: Ian Smith Botsford <issmith@amazon.com>
Date: Fri, 23 Sep 2022 20:27:56 +0000
Subject: [PATCH] chore: update/clarify changelog and add commit instructions
 in the Contributing Guidelines

---
 .../a82f99a1-c12f-4530-ae0d-33f1a746ab7d.json |  5 ++
 CONTRIBUTING.md                               | 60 ++++++++++++++++++-
 2 files changed, 63 insertions(+), 2 deletions(-)
 create mode 100644 .changes/a82f99a1-c12f-4530-ae0d-33f1a746ab7d.json

diff --git a/.changes/a82f99a1-c12f-4530-ae0d-33f1a746ab7d.json b/.changes/a82f99a1-c12f-4530-ae0d-33f1a746ab7d.json
new file mode 100644
index 00000000000..ccf169d9a1c
--- /dev/null
+++ b/.changes/a82f99a1-c12f-4530-ae0d-33f1a746ab7d.json
@@ -0,0 +1,5 @@
+{
+    "id": "a82f99a1-c12f-4530-ae0d-33f1a746ab7d",
+    "type": "misc",
+    "description": "Update/clarify changelog and add commit instructions in the Contributing Guidelines"
+}
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 92f87be7add..14e942ec4df 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -66,7 +66,7 @@ following fields:
 |---------------|------------|----------|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `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.                                                                                                                                                                                                                                                                                                         |
+| `description` | `string`   | yes      |                                              | A description of the change being made.<ul><li>Prefix with `**Breaking**:` if the change is breaking</li><li>Use the imperative present tense (e.g., "change" not "changed" nor "changes")</li><li>Capitalize first letter</li><li>No dot (.) at the end unless there are multiple sentences</li></ul>                                          |
 | `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/smithy-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.                                                                                                                                                                                                                                                               |
 
@@ -84,13 +84,69 @@ of your request may disagree and ask that you add one anyway.
 {
   "id": "263ea6ab-4b75-41a8-9c37-821c30d7b9e5",
   "type": "feature",
-  "description": "Add multiplatform support for URL parsing.",
+  "description": "Add multiplatform support for URL parsing",
   "issues": [
     "awslabs/aws-sdk-kotlin#12345"
   ]
 }
 ```
 
+### Git Commit Guidelines
+This project uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) for its commit message format and expects all contributors to follow these guidelines.
+
+Each commit message consists of a **header**, a **body** (optional), and a **footer** (optional). The header has a special format that includes a **type**, a **scope** and a **subject**:
+
+```
+<type>(<scope>): <subject>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+Any line of the commit message should not be longer 100 characters. This allows the message to be easier to read on GitHub as well as in various git tools.
+
+#### Type
+
+Must be one of the following:
+
+- **feat**: A new feature
+- **fix**: A bug fix
+- **docs**: Documentation only changes
+- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
+- **refactor**: A code change that neither fixes a bug or adds a feature
+- **perf**: A code change that improves performance
+- **test**: Adding missing tests
+- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation
+- **ci**: Changes to CI/CD scripts and tooling
+
+#### Scope
+
+The scope is optional but should be included when possible and refer to a module that is being touched. Examples:
+
+- codegen
+- rt (optionally the target platform e.g. rt-android)
+
+#### Subject
+
+The subject contains succinct description of the change:
+
+- Use the imperative present tense (e.g., "change" not "changed" nor "changes")
+- Don't capitalize first letter
+- No dot (.) at the end
+
+#### Body (optional)
+
+Just as in the **subject**, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.
+
+#### Footer (optional)
+
+The footer should contain any information about **Breaking Changes** and is also the place to reference GitHub issues that this commit **Closes**.
+
+The last line of commits introducing breaking changes should be in the form `BREAKING CHANGE: <desc>`
+
+Breaking changes should also add an exclamation mark `!` after the type/scope (e.g. `refactor(rt)!: drop support for Android API < 20`)
+
 ### Automated PR checks
 
 A number of automated workflows run when a PR is submitted. Generally speaking, each of these must pass before the PR is