2.1 Main-Branch Cutover Checklist
Migration note: This page documents a migration path or historical transition. It is not the current 3.2 happy path.
Use this checklist to promote the 2.x line to main, park the old line as 1.x-maintenance, and ship 2.1.0 as the first stable PyPI release on the promoted line.
Desired End State
mainpoints at the former2.xhistory and is the stable2.xline.1.x-maintenancepoints at the formermainhistory and is clearly deprecated.2.1.0publishes both GitHub release artifacts and the PyPI package.- Install and docs messaging consistently describe
1.x-maintenanceas maintenance-only.
Phase 0: Freeze and Confirm
- Freeze non-release merges during the cutover window.
- Confirm the cutover is a branch rename/cutover, not a merge.
- Confirm the intended open-PR outcome:
- PRs targeting
2.xshould land on the futuremain. - PRs targeting current
mainshould either stay on1.x-maintenanceor be explicitly rebased.
- PRs targeting
- Confirm the release version is
2.1.0.
Phase 1: Repo and Distribution Prep
- Merge the release-preparation changes for
2.1.0:- version bump
- changelog entry
- README/docs release-track update
- release workflow with PyPI publish
- release-readiness targeting
main(and temporarily2.x)
- Configure PyPI Trusted Publishing for
spec-kitty-cli:- owner/repo:
Priivacy-ai/spec-kitty - workflow:
.github/workflows/release.yml - environment:
pypi
- owner/repo:
- Verify GitHub environment settings for
pypiif environment protection rules are used. - Confirm branch protections are defined for both current
mainand2.xbefore rename.
Phase 2: Pre-Cutover Verification
- Confirm latest
2.xHEAD is the intended release candidate. - Confirm
CI Qualityis green on that commit. - Confirm
Release Readiness Checkpasses for the2.1.0PR. - Confirm
gh pr listshows the expected open PRs and bases. - Confirm docs and metadata now describe:
mainas stable2.x1.x-maintenanceas deprecated maintenance-only- PyPI publication starting with
2.1.0
Phase 3: Branch Cutover on GitHub
Do these steps in GitHub settings/UI during the freeze window.
- Temporarily change the default branch from current
mainto2.x. - Rename current
mainto1.x-maintenance. - Rename current
2.xtomain. - Set
mainback as the default branch. - Verify branch protection rules carried over correctly after rename.
- Verify open PR retargeting:
- current
2.xPRs should now targetmain - current
mainPRs should now target1.x-maintenance
- current
Phase 4: Post-Cutover Repository Checks
- Verify the repository homepage and default-branch badge point at the new
main. - Verify raw
mainasset URLs still resolve as expected. - Verify docs contribution/edit links point at
main. - Verify workflows trigger on the right branches after the rename.
- Verify
README.mdon GitHub clearly marks1.x-maintenanceas deprecated. - Add a short deprecation note or pinned issue for
1.x-maintenanceif desired.
Phase 5: Release 2.1.0
- Check out the new
mainlocally and pull latest. - Confirm
pyproject.tomlandCHANGELOG.mdstill show2.1.0. - Tag the release:
Terminal window git checkout maingit pull origin maingit tag -a v2.1.0 -m "Release v2.1.0"git push origin v2.1.0 - Watch
.github/workflows/release.yml. - Verify:
- tests passed
- distributions built
- PyPI publish succeeded
- GitHub release was created with artifacts and notes
Phase 6: Release Verification
- Verify GitHub release
v2.1.0exists. - Verify PyPI shows
2.1.0as the latest version. - Verify
pipx install spec-kitty-cliinstalls2.1.0; optionally verifypython -m pip install spec-kitty-cliinside a virtual environment. - Smoke-test
spec-kitty --versionandspec-kitty initfrom the PyPI install. - Verify upgrade behavior on a representative existing project.
Phase 7: Follow-Through
- Announce
2.1.0as the new stable line. - State clearly that
1.x-maintenanceis deprecated and maintenance-only. - Update any external docs or pinned install instructions that still mention the old split-track model.
- Close or retarget any stale PRs/issues that still refer to the old branch setup.
Current PRs to Check During Cutover
At the time this checklist was prepared:
#305targets2.xand should end up on the newmain.#277targets2.xand should end up on the newmain.#265targets currentmainand should end up on1.x-maintenanceunless intentionally rebased.
Rollback Plan
If the branch rename causes unexpected automation or protection issues:
- Pause tagging and PyPI publication.
- Fix branch protection and workflow targeting on GitHub first.
- Re-verify PR bases and default branch behavior.
- Only tag
v2.1.0after the branch model is stable.