[FEATURE] Branching strategy Phase 2.B - release trigger and versioning docs

[John McCall (lowlydba)]

Summary

Phase 2.B of the branching strategy (#533): release detection on main, the changelog machinery, and the versioning docs. No publish workflows, those are Phase 3 (#509), which this unblocks.

The versioning model settled during review (thanks Victor Schappert (@vcschapp), Seth Fitzsimmons (@sethfitz)): humans own the full <major>.<minor>.<patch> per package, any bump merged to main is a release, and CI only versions the interim internal builds between releases.

What lands

Release trigger

• release-trigger.yaml + detect_version_bumps.py: on push to main, diffs every packages/*/pyproject.toml version against the previous commit. Any increase (patch included) cuts one published GitHub Release per bumped package: tag <pkg>-v<version>, title `<pkg>` <version>, notes read from that package's CHANGELOG.md. Fails loudly on version decreases and on pre-existing tags. The umbrella overture-schema release is marked Latest.
• Major-bump cascade guard: a package whose direct workspace dependency takes a major bump must take one itself, since the old dependency floor would admit a breaking version. Enforced at PR time by the version check and again by release-trigger. Direct-dep checking covers longer chains, each unbumped link fails its own check.
• create-package-release composite action with a dry-run input for testing.

Changelog machinery

• towncrier fragments per package (packages/<pkg>/changelog.d/), config centralized in the root pyproject.toml.
• require-changelog-fragment.yaml: any PR touching a package must carry a fragment or a built CHANGELOG.md. Plain git diff + grep, no action dependencies.
• Release PRs run towncrier build so the notes are reviewed as part of the version-bump diff.

Internal build versioning

• compute-version reworked: no-bump merges produce <version>.postN+main.<sha> (or +vnext.<sha>). PEP 440 post-releases order after the release, so >=X.Y.Z consumers resolve the freshest internal build while ==X.Y.Z selects the clean release; local labels are rejected by public PyPI, keeping these builds internal by construction. N is a per-version sequence resolved from CodeArtifact: the first internal build of a version is .post0, later builds increment the highest published .postN.
• Verified against uv with a local two-wheel resolution test; the one spec gotcha (> never matches post-releases) is documented.
• main and vnext builds must not share a CodeArtifact repository (local labels don't participate in ordering, so >= consumers could resolve vnext breaking builds). vnext publishing is blocked on the dedicated dev repo in ops-team#299.

Workspace dependency floors

• Intra-repo dependencies now follow uv's dual declaration pattern: explicit >= floors in project.dependencies alongside the [tool.uv.sources] workspace entries. Built wheels carry the floors directly, no build-time metadata rewriting. Floors are hand-maintained; the cascade guard above is the sanity net. This replaced an earlier just-in-time materialization script after review discussion.

Docs

• docs/versioning.md: scheme, trigger x destination table, bump rules, floor maintenance, release walkthrough, pin guidance.
• CONTRIBUTING.md: per-path release flows with gitGraphs, versioning quick reference, phase roadmap.

Bonus

• 🧹 package_versions.py replaces the dual-checkout version diff: reads pyproject.toml blobs straight from git and derives the topological order from declared dependencies instead of a hardcoded map. The reusable check drops a checkout, two uv syncs, and Python setup on the no-change path.
• 🧹 The change-type label check sheds its github-script JS for jq over the event payload.
• 🔧 The legacy publish workflow syncs with --locked so it installs exactly the committed uv.lock.

Testing

Detection, cascade enforcement, release-notes extraction, floor-carrying wheel metadata, and the resolver-ordering claims are tested locally against real repo history (simulated bump, downgrade, uncascaded-major, and multi-package cases). The workflows themselves can't run until they're on main; release-trigger supports dry-run for a low-stakes first live pass. zizmor is clean on all touched workflows.

Closes #533

[Seth Fitzsimmons (sethfitz)]

P>=1.2.3 is ignored entirely as long as there's a package in the workspace that matches by name.

John McCall (John McCall (@lowlydba)) and I just met on this topic. The tl;dr is:

• We acknowledge it's a real issue.
• The solution is a bit complex.
• We're recommending to go forward and finish this phase without solving it, and let our experience with the system in the wild tell us how important it is to add guardrails. In other words, defer for now; if needed fix later.

Seth Fitzsimmons (Seth Fitzsimmons (@sethfitz)) What are your thoughts on the above?

Works for me. I don't want to overthink it (yet), but did want to flag the behavioral side-effect to using intra-repo dependency specifiers (which, even if we have to do crazy things to enforce them, seem like a net positive).

[Victor Schappert (vcschapp)]

Found two little tiny documentation things to tweak (two lines).

Everything else looks absolutely stellar.