Skip to content

Commit 97af857

Browse files
ianbotsfianbotsf
authored
chore: update/clarify changelog instructions in CONTRIBUTING.md (#58)
1 parent f21eaa0 commit 97af857

File tree

2 files changed

+60
-8
lines changed

2 files changed

+60
-8
lines changed

‎.changes/3c9cedab-7cd3-479c-b887-0cbdceeb9341.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{
2+
"id": "3c9cedab-7cd3-479c-b887-0cbdceeb9341",
3+
"type": "misc",
4+
"description": "Update/clarify changelog and add commit instructions in the Contributing Guidelines"
5+
}

‎CONTRIBUTING.md‎

Lines changed: 55 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,13 @@ Merges to this repository must include one or more changelog entries which descr
4646
Entries are placed in the top-level `.changes/` directory. An entry is a file containing a JSON object with the
4747
following fields:
4848

49-
| Field name | Type | Required | Enum | Description |
50-
|---------------|------------|----------|----------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
51-
| `id` | `string` | yes | | A unique identifier for this entry. We recommend you generate a UUID for this field. |
52-
| `type` | `string` | yes | `bugfix`, `feature`, `documentation`, `misc` | The type of change being made. |
53-
| `description` | `string` | yes | | A description of the change being made. |
49+
| Field name | Type | Required | Enum | Description |
50+
|---------------|------------|----------|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
51+
| `id` | `string` | yes | | A unique identifier for this entry. We recommend you generate a UUID for this field. |
52+
| `type` | `string` | yes | `bugfix`, `feature`, `documentation`, `misc` | The type of change being made. |
53+
| `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> |
5454
| `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> |
55-
| `module` | `string` | no | | The area of the code affected by your changes. If unsure, leave this value unset. |
55+
| `module` | `string` | no | | The area of the code affected by your changes. If unsure, leave this value unset. |
5656

5757
The filename of an entry is arbitrary. We recommend `<id>.json`, where `<id>` corresponds to the `id` field of the entry
5858
itself.
@@ -68,14 +68,61 @@ of your request may disagree and ask that you add one anyway.
6868
{
6969
"id": "263ea6ab-4b75-41a8-9c37-821c30d7b9e5",
7070
"type": "feature",
71-
"description": "Add binding for CRT URL parsing.",
71+
"description": "Add binding for CRT URL parsing",
7272
"issues": [
7373
"awslabs/aws-crt-kotlin#12345"
7474
]
7575
}
7676
```
7777

78+
### Git Commit Guidelines
79+
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.
7880

81+
Each commit message consists of a **header**, a **body** (optional), and a **footer** (optional). The header has a special format that includes a **type** and a **subject**:
82+
83+
```
84+
<type>: <subject>
85+
<BLANK LINE>
86+
<body>
87+
<BLANK LINE>
88+
<footer>
89+
```
90+
91+
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.
92+
93+
#### Type
94+
95+
Must be one of the following:
96+
97+
- **feat**: A new feature
98+
- **fix**: A bug fix
99+
- **docs**: Documentation only changes
100+
- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
101+
- **refactor**: A code change that neither fixes a bug or adds a feature
102+
- **perf**: A code change that improves performance
103+
- **test**: Adding missing tests
104+
- **chore**: Changes to the build process or auxiliary tools and libraries such as documentation generation
105+
- **ci**: Changes to CI/CD scripts and tooling
106+
107+
#### Subject
108+
109+
The subject contains succinct description of the change:
110+
111+
- Use the imperative present tense (e.g., "change" not "changed" nor "changes")
112+
- Don't capitalize first letter
113+
- No dot (.) at the end
114+
115+
#### Body (optional)
116+
117+
Just as in the **subject**, use the imperative present tense (e.g., "change" not "changed" nor "changes"). The body should include the motivation for the change and contrast this with previous behavior.
118+
119+
#### Footer (optional)
120+
121+
The footer should contain any information about **Breaking Changes** and is also the place to reference GitHub issues that this commit **Closes**.
122+
123+
The last line of commits introducing breaking changes should be in the form `BREAKING CHANGE: <desc>`
124+
125+
Breaking changes should also add an exclamation mark `!` after the type (e.g. `refactor!: drop support for Android API < 20`)
79126

80127
## Finding contributions to work on
81128
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
@@ -88,7 +135,7 @@ [email protected] with any additional questions or comments.
88135

89136

90137
## Security issue notifications
91-
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
138+
If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public GitHub issue.
92139

93140

94141
## Licensing

0 commit comments

Comments
 (0)