From 3ef426c0d0046bb2fccfd76b423c2b8ba5db33d7 Mon Sep 17 00:00:00 2001 From: Luc Talatinian Date: Tue, 9 Aug 2022 13:37:12 -0400 Subject: [PATCH 1/3] chore: add blurb in CONTRIBUTING describing how to include changelog entries --- CONTRIBUTING.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c54620cac3..984fa494ed6 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. | +| `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 `.json`, where `` corresponds to the `id` field of the entry +itself. + +Example: +```json +{ + "id": "263ea6ab-4b75-41a8-9c37-821c30d7b9e5", + "type": "feature", + "description": "Add multiplatform support for URL parsing.", + "issues": [ + "awslabs/aws-sdk-kotlin#12345" + ] +} +``` + +Entries in the `.changes/` directory are automatically rolled into the main `CHANGELOG` 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. ## Finding contributions to work on 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'](https://github.com/aws-samples/aws-sdk-kotlin/labels/help%20wanted) issues is a great place to start. From d6c161dd1ec354550d22826484735d8851db7f04 Mon Sep 17 00:00:00 2001 From: Luc Talatinian Date: Tue, 9 Aug 2022 13:42:03 -0400 Subject: [PATCH 2/3] point to CONTRIBUTING in changelog verify error --- .github/workflows/changelog-verification.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/changelog-verification.yml b/.github/workflows/changelog-verification.yml index 755fc510bda..b3d809ebd52 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 for instructions) –or–" echo "::error ::* Add the 'no-changelog' label to this PR (in rare cases not warranting a changelog entry)" exit 1 From 9893d29fc7461a3199b3aa9402b133dc24e97e8e Mon Sep 17 00:00:00 2001 From: Luc Talatinian Date: Tue, 9 Aug 2022 14:06:59 -0400 Subject: [PATCH 3/3] address styling/clarification issues in changelog CONTRIBUTING --- .github/workflows/changelog-verification.yml | 2 +- CONTRIBUTING.md | 28 ++++++++++---------- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/.github/workflows/changelog-verification.yml b/.github/workflows/changelog-verification.yml index b3d809ebd52..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 (see CONTRIBUTING for instructions) –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 984fa494ed6..841a3da97b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,18 +62,24 @@ Merges to this repository must include one or more changelog entries which descr 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. | -| `module` | `string` | no | | The area of the code affected by your changes. If unsure, leave this value unset. | +| 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:
  • The issue number, if local to this repository (eg. `#12345`)
  • A fully-qualified issue ID (eg.`awslabs/smithy-kotlin#12345`)
  • A fully-qualified URL (eg. `https://issuetracker.com/12345`)
| +| `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 `.json`, where `` corresponds to the `id` field of the entry itself. -Example: +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", @@ -85,12 +91,6 @@ Example: } ``` -Entries in the `.changes/` directory are automatically rolled into the main `CHANGELOG` 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. - ## Finding contributions to work on 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'](https://github.com/aws-samples/aws-sdk-kotlin/labels/help%20wanted) issues is a great place to start.