|
13 | 13 | - [Triage Bug Reports](#triage-bug-reports)
|
14 | 14 | - [Triage RFCs](#triage-rfcs)
|
15 | 15 | - [Releasing a new version](#releasing-a-new-version)
|
| 16 | + - [Changelog generation](#changelog-generation) |
| 17 | + - [Bumping the version](#bumping-the-version) |
| 18 | + - [Drafting release notes](#drafting-release-notes) |
16 | 19 | - [Releasing a documentation hotfix](#releasing-a-documentation-hotfix)
|
17 | 20 | - [Maintain Overall Health of the Repo](#maintain-overall-health-of-the-repo)
|
18 | 21 | - [Manage Roadmap](#manage-roadmap)
|
@@ -112,7 +115,7 @@ Use and enforce [semantic versioning](https://semver.org/) pull request titles,
|
112 | 115 |
|
113 | 116 | > TODO: This is an area we want to automate using the new GitHub GraphQL API.
|
114 | 117 |
|
115 |
| -For issues linked to a PR, make sure `pending release` label is applied to them when merging. Upon release, all issues with that label will be notified which version contains that change. |
| 118 | +For issues linked to a PR, make sure `pending release` label is applied to them when merging. [Upon release](#releasing-a-new-version), all issues with that label will be notified which version contains that change. |
116 | 119 |
|
117 | 120 | See [Common scenarios](#common-scenarios) section for additional guidance.
|
118 | 121 |
|
@@ -160,8 +163,47 @@ Some examples using our initial and new RFC templates: #92, #94, #95, #991, #122
|
160 | 163 |
|
161 | 164 | ### Releasing a new version
|
162 | 165 |
|
163 |
| -> WORK-IN-PROGRESS |
164 |
| -> convert what's written in [publish.yml](.github/workflows/publish.yml) |
| 166 | +> TODO: This is an area we want to increase automation while keeping communication at human level. |
| 167 | +
|
| 168 | +Firstly, make sure you are using the `develop` branch and it is up to date with the origin. |
| 169 | + |
| 170 | +There are three main steps to release a new version: Changelog generation, version bumping, and drafting release notes. |
| 171 | + |
| 172 | +#### Changelog generation |
| 173 | + |
| 174 | +You can pre-generate a temporary CHANGELOG using `make changelog`. This will generate a `TMP_CHANGELOG.md` with all staged changes under the `unreleased` section. |
| 175 | + |
| 176 | +Each unreleased line item is a commit. You can adjust them if you find the commit titles are insufficient to describe their intent. Once you're comfortable, bring these changes to the `CHANGELOG.md` with a new version heading like in previous versions. |
| 177 | + |
| 178 | +#### Bumping the version |
| 179 | + |
| 180 | +Use `poetry version <major|minor|patch|specific version>` to bump the version. For example, you can use `poetry version minor` when releasing a minor version. |
| 181 | + |
| 182 | +NOTE. Make sure both `CHANGELOG` and `pyproject.toml` are committed and pushed to the remote `develop` branch before proceeding. |
| 183 | + |
| 184 | +#### Drafting release notes |
| 185 | + |
| 186 | +Visit the [Releases page](https://github.com/awslabs/aws-lambda-powertools-python/releases) and choose the edit pencil button. |
| 187 | + |
| 188 | +Make sure the `tag` field reflects the new version you're releasing, target branch field is set to `develop`, and `release title` matches your tag e.g., `v1.26.0`. |
| 189 | + |
| 190 | +You'll notice that all changes are grouped based on their [labels](#labels) like `feature`, `bug`, `documentation`, etc. |
| 191 | + |
| 192 | +> **Q: What if there's an incorrect title or grouping?** |
| 193 | +
|
| 194 | +Edit the respective PR title and update their [labels](#labels). Then run the [Release Drafter workflow](https://github.com/awslabs/aws-lambda-powertools-python/actions/workflows/release-drafter.yml) to update the Draft release. |
| 195 | + |
| 196 | +The best part comes now. Replace the placeholder `[Human readable summary of changes]` with what you'd like to communicate to customers what this release is all about. Always put yourself in the customers shoes. For that, these are some questions to keep in mind when drafting your first or future release notes: |
| 197 | + |
| 198 | +* Can customers understand at a high level what changed in this release? |
| 199 | +* Is there a link to the documentation where they can read more about each main change? |
| 200 | +* Are there any graphics or code snippets that can enhance readability? |
| 201 | +* Are we calling out any key contributor(s) to this release? |
| 202 | + - All contributors are automatically credited, use this as an exceptional case to feature them |
| 203 | + |
| 204 | +Once you're happy, hit `Publish release`. This will kick off the [Publishing workflow](https://github.com/awslabs/aws-lambda-powertools-python/actions/workflows/publish.yml) and within a few minutes you should see the latest version in PyPi, and all issues labelled as `pending-release` will be notified. |
| 205 | + |
| 206 | +> TODO: Wait for @am29d new Lambda Layers pipeline work to complete, then add how Lambda Layers are published |
165 | 207 |
|
166 | 208 | ### Releasing a documentation hotfix
|
167 | 209 |
|
@@ -210,7 +252,7 @@ When in doubt, use `need-more-information` or `need-customer-feedback` labels to
|
210 | 252 |
|
211 | 253 | ### Crediting contributions
|
212 | 254 |
|
213 |
| -> TODO: mention release notes and provide an example. |
| 255 | +We credit all contributions as part of each [release note](https://github.com/awslabs/aws-lambda-powertools-python/releases) as an automated process. If you find that contributors are missing from the release note you're producing, please add them manually. |
214 | 256 |
|
215 | 257 | ### Is that a bug?
|
216 | 258 |
|
|
0 commit comments