[Devops] Branching Strategy - Phase 2.B - Release Versions

[lowlydba]

Goal

Implement CI release-event detection and the release process for main.

Depends on Phase 2.A (#508) — version scheme baseline and compute-version composite action must exist first.

Scope: release trigger + vnext→main merge process + changelog approach + docs. No publish workflows — those live in Phase 3 (#509), which this phase partially unblocks.

Release flows

1. Major/minor bump → public PyPI release

The only flow that produces a public release.

1. Human edits <major>.<minor> in any package's pyproject.toml and opens a PR to vnext (or main for non-breaking).
2. PR merges normally.
3. For breaking changes: maintainer opens a vnext→main PR (regular merge, not squash).
4. On merge to main: p2-release-trigger detects the <major>/<minor> bump → creates GH Release at v<major>.<minor>.0.
5. GH Release event fires p3-pypi-publish (Phase 3) → all affected packages publish to public PyPI at <major>.<minor>.0.

Important

The GH Release created here is the only trigger for PyPI publish. Nothing else causes a public release.

2. Normal patch commits (any package) → auto-versioned CA builds

No human version decision needed. <patch> is computed by CI.

• Push to vnext: affected packages publish to CA dev as <major>.<minor>.<last-patch>+dev.<N> via p3-dev-builds-ca (Phase 3).
• Push to main (no bump): affected packages publish to CA as <major>.<minor>.<next-patch> via p3-main-ca-publish (Phase 3).

Warning

TBD — patch destination: Does a patch commit to main publish to public PyPI, or CA only? This decision affects the scope of p2-release-trigger and whether patch builds share the PyPI publish path or stay CA-only. Must be resolved before p2-release-trigger can be finalized.

Note

Phase 3 owns the actual publish steps for this flow. Phase 2.B only needs to document it and ensure p2-release-trigger correctly skips non-bump pushes.

Tasks

p2-release-trigger

CI workflow on main push that inspects packages/*/pyproject.toml for <major>/<minor> changes. On bump: creates GH Release at v<major>.<minor>.0 with assembled release notes. On no bump: no-op (patch builds are Phase 3's concern).

Important

Release notes assembly approach is TBD — see p2-changelog-fragments below.

Warning

Scope of this workflow may expand depending on the patch destination decision (see flow 2 above).

p2-vnext-merge-process

Document and configure the human-driven release process (flow 1 above). Ensure p1-pr-compat-check and p1-post-merge-rebase skip via head.ref == 'vnext'. No title convention or label needed.

p2-changelog-fragments

Warning

Approach is undecided — must be evaluated at kickoff before p2-release-trigger can be completed.

Options to evaluate:

• Per-PR fragment files (changelogs/fragments/<pr-id>.yaml) assembled at release time (antsibull-changelog pattern)
• Auto-generated from PR titles/descriptions
• Manual release notes authored at release time

p2-docs

• Update CONTRIBUTING.md with version bump guidance and release process (flows above).
• Add docs/versioning.md covering: version scheme, bump rules, what CI does with <patch>, and the full release process.

Note

CONTRIBUTING.md versioning section is partially complete from Phase 2.A. Needs bump guidance and the full release process flow added.

Definition of done

• p2-release-trigger workflow live, detects bumps, creates GH Release, routes all packages correctly
• vnext→main release PR process documented + Phase 1 workflows updated to skip on head.ref == 'vnext'
• Patch destination decision made and documented
• Changelog approach decided
• docs/versioning.md created, CONTRIBUTING.md updated