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

[John McCall (lowlydba)]

Summary

Phase 2.B of the branching strategy (#533): release-event detection on main plus the versioning/release documentation. No publish workflows — those are Phase 3 (#509), which this partially unblocks.

Key decisions

These resolve the TBDs flagged in #533/#509, plus one deliberate deviation from the original issue text:

1. Patch destination: CodeArtifact only (Option B in [Devops] Branching Strategy - Phase 3 #509). Publishing a GitHub Release is the sole trigger for public PyPI. Keeps the public release signal curated; every main merge is not a public event.
2. Umbrella-only release trigger (deviation from "any package"). The issues said any package's major/minor bump cuts a release, but a single v<major>.<minor>.0 tag can't represent two packages bumping to different versions — e.g. a cli 0.1→0.2 bump would have cut a misleading v0.2.0. Only the umbrella overture-schema bump now cuts a release; its version names the tag. Escape hatch: a non-core package needing public PyPI immediately bumps the umbrella minor in the same PR (one line, and honest — the umbrella distribution's contents changed). Otherwise it rides the next umbrella release.
3. Changelog: manual notes at release time. No fragment files or auto-generation machinery. Evaluated per-PR fragments (antsibull pattern) and GitHub auto-generated notes; rejected for friction/quality respectively.
4. Draft-release human gate. The bump merge creates a draft release; a maintainer writes notes and clicks Publish, and only that release: published event fires the Phase 3 publish. Pairs the manual-notes decision with a natural approval gate — no accidental public releases.
5. No semantic-release/release-please. Those tools want to own versioning end-to-end from conventional commits, conflicting with the 2.A model (human owns major/minor in pyproject.toml, CI computes patch from CodeArtifact state). The custom trigger is ~40 lines.

Changes

release-trigger workflow (new)

• Runs on push to main, path-filtered to packages/overture-schema/pyproject.toml.
• Compares the umbrella package's <major>.<minor> before/after via git show + stdlib tomllib.
• On bump: creates a draft GitHub Release tagged v<major>.<minor>.0. Fails loudly if the tag already exists. Patch-only changes are a no-op.
• Handles an unresolvable before SHA (force-push) gracefully.
• zizmor clean.

docs/versioning.md (new)

Version scheme (human owns major/minor, CI owns patch), CI trigger/destination table, bump rules, full release process, vnext→main merge process, guardrails.

CONTRIBUTING.md

Release trigger CI section, versioning quick reference, vnext release diagram annotated with the bump commit + draft tag, roadmap table (2.B → done), Phase 2.B/3 migration notes updated with locked decisions.

Notes

• Phase 1 vnext skips (vnext-compat, rebase-vnext) verified already in place — no changes needed.
• Phase 3's p3-release-publish trigger should be updated in [Devops] Branching Strategy - Phase 3 #509 to release: published.

Closes #533

[github-actions]

🗺️ Schema reference docs preview is live!

🌍 Preview	https://staging.overturemaps.org/schema/pr/557/schema/index.html
🕐 Updated	Jul 14, 2026 15:02 UTC
📝 Commit	4d1c242
🔧 env SCHEMA_PREVIEW	true

Note

♻️ This preview updates automatically with each push to this PR.

[Copilot]

Pull request overview

Adds Phase 2.B release-event detection on main and documents the versioning/release process so Phase 3 publish workflows can rely on a clear trigger and scheme.

Changes:

• Adds a release-trigger GitHub Actions workflow that detects umbrella overture-schema <major>.<minor> bumps on main and creates a draft GitHub Release/tag.
• Adds docs/versioning.md describing version ownership (human vs CI), trigger→destination behavior, and the release process.
• Updates CONTRIBUTING.md with a release-trigger section, a versioning quick reference, and Phase status updates.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
.github/workflows/release-trigger.yaml	New workflow that detects umbrella major/minor bumps and creates a draft GitHub Release/tag to gate public releases.
docs/versioning.md	New documentation for version scheme, CI version behavior, and the release process.
CONTRIBUTING.md	Adds contributor-facing guidance and references to the new versioning/release process docs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[John McCall (lowlydba)]

If we want this, the better approach is to make tags immutable with a Ruleset at the GitHub repo layer - I can configure this if desired.