docs(maintainers): improve release process documentation #7088
+41
−7
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
pull-request-size
bot
added
the
size/M
boring-cyborg
bot
added
documentation
leandrodamascena
requested review from
dreamorosi
and removed request for
anafalcao
1 task
|
Will review before Monday - thank you! |
dreamorosi
reviewed
Aug 4, 2025
| @@ -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" | |||
There was a problem hiding this comment.
Not mandatory, but I'd consider rephrasing/simplifying to "Only maintainers with write access to this repository can release new version/can make releases"
|
|
||
| > **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 |
There was a problem hiding this comment.
Consider linking the workflow page for easy access.
|
|
||
| > **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 | ||
| 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 |
There was a problem hiding this comment.
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 input31
This entire process can be tricky and overwhelming, let's remove as much ambiguity and cognitive load as possible.
| 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 | ||
| 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 |
There was a problem hiding this comment.
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.
|
|
||
| #### 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: |
There was a problem hiding this comment.
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: |
| 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: | ||
|
|
||
| **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. |
There was a problem hiding this comment.
Can we say the name of the step(s) that can be retried with this mechanism?
| 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. | ||
|
|
||
| **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. |
There was a problem hiding this comment.
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
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Issue number: #7086
Summary
Improves the maintainers documentation for the release process by restructuring the content for better clarity and adding guidance for handling workflow failures.
Changes
Changes in the documentation.
User experience
Checklist
If your change doesn't seem to apply, please leave them unchecked.
Is this a breaking change?
RFC issue number:
Checklist:
Acknowledgment
By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.
Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.