From ecc0f50c39881e8188958833c9590b7c8746017b Mon Sep 17 00:00:00 2001 From: Roman Lutz Date: Thu, 9 Apr 2026 15:42:52 -0700 Subject: [PATCH 1/3] DOC: Add patch release guide to release process Add an appendix explaining cherry-pick-based patch releases, covering when to use them, the abbreviated steps, and key differences from regular releases. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- doc/contributing/10_release_process.md | 82 ++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/doc/contributing/10_release_process.md b/doc/contributing/10_release_process.md index 9c532a444..e1d5b8ba5 100644 --- a/doc/contributing/10_release_process.md +++ b/doc/contributing/10_release_process.md @@ -222,3 +222,85 @@ However, important bug fixes, new features, and breaking changes are good candid If you are unsure about whether to include certain changes please consult with your fellow maintainers. When you're done, hit "Publish release" and mark it as the latest release. + +## Appendix: Patch Releases (Cherry-Pick Process) + +A patch release (e.g., `0.12.0` → `0.12.1`) ships a targeted fix — typically a security +patch or critical bug fix — without including other in-flight changes from `main`. +The process follows the same steps as a regular release with a few key differences. + +### When to use a patch release + +- A security vulnerability needs to be shipped urgently. +- A critical bug was found in the latest release that blocks users. +- The fix is already merged to `main`, but `main` also contains other changes + that are not ready for release. + +### Abbreviated steps + +**1. Create a release branch from the previous tag, not from `main`:** + +```bash +git fetch origin +git checkout -b release/vx.y.z vx.y.(z-1) +``` + +For example, to create `0.12.1` from `0.12.0`: + +```bash +git checkout -b release/v0.12.1 v0.12.0 +``` + +**2. Cherry-pick the fix from `main`:** + +Identify the merge commit SHA on `main` (e.g., from the merged PR) and cherry-pick it: + +```bash +git cherry-pick +``` + +If the cherry-pick has conflicts, resolve them manually. Since this is a patch release +the fix should apply cleanly in most cases. + +**3. Bump the version:** + +Update the version in all three files (`pyproject.toml`, `pyrit/__init__.py`, `frontend/package.json`) +to the new patch version (e.g., `0.12.1`). Also update any version-pinned links in `README.md` +(e.g., image URLs pointing to `releases/v0.12.0` → `releases/v0.12.1`). + +Commit the version bump: + +```bash +git add pyproject.toml pyrit/__init__.py frontend/package.json README.md +git commit -m "Bump version to x.y.z" +``` + +**4. Push and tag:** + +Push the release branch with the `releases/` prefix and create the tag: + +```bash +git push origin release/vx.y.z:releases/vx.y.z +git tag -a vx.y.z -m "vx.y.z release" +git push origin vx.y.z +``` + +**5. Follow the regular release process from step 6 onward:** + +- Build the package (step 6) +- Test the built package in a clean environment (step 7) +- Run integration tests (step 7) +- Publish to PyPI (step 8) +- Update `main` with the next dev version (step 9) — for a patch release after `x.y.z`, + the next version on `main` may be either `x.y.(z+1).dev0` or `x.(y+1).0.dev0` + depending on what the next planned release is. +- Create the GitHub release (step 10) + +### Key differences from a regular release + +| Aspect | Regular release | Patch release | +|---|---|---| +| Branch base | `main` | Previous release tag (e.g., `v0.12.0`) | +| Changes included | Everything on `main` | Only cherry-picked fix(es) | +| Deprecated code removal | Yes (if minor bump) | No | +| Integration test scope | Full | Focused on affected areas | From 5cd6b540d89ab3eadbf8fd2d6aa6ca79cb67e6db Mon Sep 17 00:00:00 2001 From: Roman Lutz Date: Fri, 10 Apr 2026 10:32:39 -0700 Subject: [PATCH 2/3] Update doc/contributing/10_release_process.md Co-authored-by: jsong468 --- doc/contributing/10_release_process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/10_release_process.md b/doc/contributing/10_release_process.md index e1d5b8ba5..f0723e135 100644 --- a/doc/contributing/10_release_process.md +++ b/doc/contributing/10_release_process.md @@ -231,7 +231,7 @@ The process follows the same steps as a regular release with a few key differenc ### When to use a patch release -- A security vulnerability needs to be shipped urgently. +- A security vulnerability fix needs to be shipped urgently. - A critical bug was found in the latest release that blocks users. - The fix is already merged to `main`, but `main` also contains other changes that are not ready for release. From fd09b07187cde088ad3fcea3542af28db069da99 Mon Sep 17 00:00:00 2001 From: Roman Lutz Date: Fri, 10 Apr 2026 10:53:08 -0700 Subject: [PATCH 3/3] Add patch release notes guidance Address review feedback: clarify that patch release notes should highlight the specific reason for the patch (security fix, critical bug, etc.) and will be shorter than regular release notes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- doc/contributing/10_release_process.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/doc/contributing/10_release_process.md b/doc/contributing/10_release_process.md index f0723e135..e4789729d 100644 --- a/doc/contributing/10_release_process.md +++ b/doc/contributing/10_release_process.md @@ -294,7 +294,12 @@ git push origin vx.y.z - Update `main` with the next dev version (step 9) — for a patch release after `x.y.z`, the next version on `main` may be either `x.y.(z+1).dev0` or `x.(y+1).0.dev0` depending on what the next planned release is. -- Create the GitHub release (step 10) +- Create the GitHub release (step 10) — for patch releases the release notes should + clearly state the reason for the patch (e.g., "Security fix for …" or "Critical bug fix + for …"). Because a patch release contains only cherry-picked changes, the "What's + changed?" summary and the full changelog will be much shorter than a regular release. + Make sure to call out the specific issue or vulnerability that prompted the patch so + users can quickly assess whether they need to upgrade. ### Key differences from a regular release @@ -304,3 +309,4 @@ git push origin vx.y.z | Changes included | Everything on `main` | Only cherry-picked fix(es) | | Deprecated code removal | Yes (if minor bump) | No | | Integration test scope | Full | Focused on affected areas | +| Release notes | Full changelog with curated summary | Short, focused on the reason for the patch |