[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. overture-schema major/minor bump → public PyPI release

The only flow that produces a public release.

1. Human edits <major>.<minor> in packages/overture-schema/pyproject.toml and opens a PR to vnext.
2. PR merges to vnext normally.
3. Maintainer opens a vnext→main PR (regular merge, not squash — preserves vnext history).
4. On merge: 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) → overture-schema publishes 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. Supplemental package major/minor bump → CA release only

For packages other than overture-schema (e.g. overture-schema-cli, theme packages).

1. Human edits <major>.<minor> in the relevant pyproject.toml and opens a PR directly to main.
2. PR merges normally.
3. On merge: p2-release-trigger detects the bump → fires p3-supplemental-ca-release (Phase 3) → publishes that package to CA release repo at <major>.<minor>.0.
4. Never published to PyPI.

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

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 overture-schema bump: creates GH Release at v<major>.<minor>.0 with assembled release notes. On supplemental package bump: fires p3-supplemental-ca-release. On no bump: no-op (patch builds are Phase 3's concern).

Important

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

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 1–3 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 for overture-schema, routes supplemental packages correctly
• vnext→main release PR process documented + Phase 1 workflows updated to skip on head.ref == 'vnext'
• Changelog approach decided
• docs/versioning.md created, CONTRIBUTING.md updated