Skip to content

docs(maintainers): improve release process documentation #7088

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from
+41 −7
Open

docs(maintainers): improve release process documentation #7088

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c71240b
Updating release documentation
leandrodamascena Aug 1, 2025
f15d7aa
Updating release documentation
leandrodamascena Aug 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 41 additions & 7 deletions docs/maintainers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,15 +151,33 @@ Some examples using our initial and new RFC templates: #92, #94, #95, #991, #122

### Releasing a new version

Firstly, make sure the commit history in the `develop` branch **(1)** it's up to date, **(2)** commit messages are semantic, and **(3)** commit messages have their respective area, for example `feat(logger): <change>`, `chore(ci): ...`).
!!! note "Only maintainers with write permissions to this repository can trigger the pipeline to release a new version"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not mandatory, but I'd consider rephrasing/simplifying to "Only maintainers with write access to this repository can release new version/can make releases"


**Looks good, what's next?**
Releasing a new version is a multi-step process that takes up to 2 hours to complete. Most steps are automated - you provide inputs to trigger the release and monitor progress.

Kickoff the [`Release` workflow](https://github.com/aws-powertools/powertools-lambda-python/blob/6db9079d21698b72f5d36d72c993c1aad7276db6/.github/workflows/release.yml#L3) with the intended version - this might take around 25m-30m to complete.
**Prerequisites**: Ensure the commit history in the `develop` branch is up to date, commit messages are semantic, and include their respective area (e.g., `feat(logger): <change>`, `chore(ci): ...`).

Once complete, you can start drafting the release notes to let customers know **what changed and what's in it for them (a.k.a why they should care)**. We have guidelines in the [release notes section](#drafting-release-notes) so you know what good looks like.
**Release Steps**:

> **NOTE**: Documentation might take a few minutes to reflect the latest version due to caching and CDN invalidations.
1. **Run end-to-end tests** and ensure they pass
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider linking the workflow page for easy access.

2. **Trigger Release v3 workflow** - Run the [`Release v3`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/release-v3.yml) workflow with two inputs: the new Powertools version (check [latest version](https://pypi.org/project/aws-lambda-powertools/)) and the new Lambda Layer version number
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding examples here, especially for the layer.

Let's tell the reader exactly where to look and what logic to follow:

  • go to this page / run this command to read the latest value from SSM
  • add +1 to that number, i.e. if the result is 30, then you should input 31

This entire process can be tricky and overwhelming, let's remove as much ambiguity and cognitive load as possible.

3. **Monitor the release workflow** - it runs tests, publishes to PyPI, deploys Lambda layers to Beta and Prod environments across all commercial regions, runs canary tests, and updates documentation. If it fails, see the [Re-run partial failed Release workflow](#re-run-partial-failed-release-workflow) section
4. **Review and merge documentation/version PRs** - two PRs will be created to update documentation and bump version files. Review, approve and merge both (order doesn't matter)
5. **Deploy GovCloud layers** - Run the [`Layer Deployment (GovCloud)`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/layer_govcloud.yml) workflow with `develop` branch, `Prod` environment, and the Layer version number from step 2. Contact the Powertools team via internal tools if this fails
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Contact the Powertools team via internal tools if this fails

This might be redundant since we said at the top that only maintainers can make releases.

6. **Deploy China layers** - Run the [`Layer Deployment (Partitions)`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/layers_partitions.yml) workflow with `develop` branch, `Prod` environment, and the Layer version number from step 2. Contact the Powertools team via internal tools if this fails
7. **Update documentation** - Run the [`Rebuild latest docs`](https://github.com/aws-powertools/powertools-lambda-python/actions/workflows/rebuild_latest_docs.yml) workflow with `develop` branch and the PyPI package version

Once complete, you can start drafting the release notes to let customers know **what changed and what's in it for them (a.k.a why they should care)**. We have guidelines in the [release notes](#drafting-release-notes) section so you know what good looks like.

#### Re-run partial failed Release workflow

While workflows are designed to be stable, failures can occur during the release process. If the Release v3 workflow fails, you have two recovery options:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
While workflows are designed to be stable, failures can occur during the release process. If the Release v3 workflow fails, you have two recovery options:
While workflows are designed to be stable, failures can occur during the release process. If the release workflow fails, you have two recovery options:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⬆️ future proofing


**Option 1: Re-run failed jobs**
If layer deployments fail due to CloudFormation errors (we deploy ~600 layers per release and can't control CloudFormation quotas), you can re-run only the failed jobs. This will retry the deployment and typically resolves quota-related issues.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we say the name of the step(s) that can be retried with this mechanism?


**Option 2: Re-trigger the entire workflow**
If the release fails due to workflow modifications or permission issues that prevent re-running failed jobs, trigger the Release v3 workflow again. In this case, check the `Skip publishing to PyPI as it can't publish more than once. Useful for semi-failed releases` option to avoid PyPI publishing conflicts.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider making the "Skip publishing ...." an > [!important] callout so it's extra clear

i.e. (but with MKdocs syntax)

Important

Make sure to select "Skip publishing to PyPI as it can't publish more than once. Useful for semi-failed releases" when rerunning the entire workflow to avoid duplicate publishes


#### Release process visualized

Expand Down Expand Up @@ -222,12 +240,28 @@ section Docs
Create PR (Layer ARN) : active, after layer_prod, 8s
Release versioned docs : active, 2.2m

Documentation release : milestone, m4, 10:28,1m
Documentation release : milestone, m5, 10:28,1m

section SSM Parameters
Update SSM Parameters : active, 8s

SSM Parameters : milestone, m6, 10:28,1m

section Post-release
Close pending issues : active, 8s

Release complete : milestone, m6, 10:31,2m
section GovCloud
Publish GovCloud layers (Gamma) : active, 8s
Publish GovCloud layers (Prod) : active, 8s
GovCloud layers published : milestone, m7


section China
Publish China layers (Gamma) : active, 8s
Publish China layers (Prod) : active, 8s
China layers published : milestone, m8

Release complete : milestone, m9, 10:31,2m
```

#### Drafting release notes
Expand Down