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

.github/actions/compute-version/action.yml

@@ -1,16 +1,25 @@
 name: Compute package version
 description: >
-  Computes the version string for a package given branch context.
+  Computes the internal build version string for a package on a no-bump merge.
 
-  Contexts:
-    - `vnext`: `<last-published>+dev.<run_number>` (PEP 440 local version).
-      Falls back to `<major>.<minor>.0+dev.<run_number>` if never published.
-      Local versions are rejected by PyPI — only suitable for private indexes
-      like CodeArtifact.
-    - `main`: `<major>.<minor>.<next-patch>` — increments the highest
-      published patch for the same major.minor series.
-    - `main-bump`: `<major>.<minor>.0` — used when a major/minor bump commit
-      lands on main (patch resets to 0).
+  All three released version components (<major>.<minor>.<patch>) are
+  human-owned in pyproject.toml; releases publish that version as-is. This
+  action only versions the interim internal builds published to CodeArtifact
+  between releases, using a PEP 440 post-release so they order AFTER the
+  released version and are picked up by `>=<version>` specifiers:
+
+    - `main`:  `<version>.post<N>+main.<shortsha>`
+    - `vnext`: `<version>.post<N>+vnext.<shortsha>`
+
+  `N` is a per-version sequence: the first internal build of a version is
+  `.post0` (communicating "identical to the release"), and each subsequent
+  build increments from the highest `.postN` already published to
+  CodeArtifact.
+
+  The `+main`/`+vnext` local label distinguishes the two build streams; local
+  labels are ignored during version comparison so ordering comes from
+  `.post<N>` alone. Local versions are rejected by public PyPI, which
+  guarantees these builds stay internal.
 
   Prerequisites: repo must be checked out and `uv` must be available.
 
@@ -20,8 +29,8 @@ inputs:
     required: true
   context:
     description: >
-      Branch context controlling the version formula.
-      Supported values: `vnext`, `main`, `main-bump`.
+      Branch context naming the build stream. Supported values: `main`,
+      `vnext`.
     required: true
   index_url:
     description: >
@@ -45,88 +54,49 @@ runs:
         PACKAGE: ${{ inputs.package }}
         CONTEXT: ${{ inputs.context }}
         INDEX_URL: ${{ inputs.index_url }}
-        RUN_NUMBER: ${{ github.run_number }}
+        SHA: ${{ github.sha }}
       run: |
         set -euo pipefail
 
-        # --- Read seed version from pyproject.toml ---
-        SEED=$(cd "packages/${PACKAGE}" && uv version --short)
-        MAJOR_MINOR=$(echo "$SEED" | grep -oE '^[0-9]+\.[0-9]+')
-        echo "Seed version for ${PACKAGE}: ${SEED} (major.minor: ${MAJOR_MINOR})"
-
-        # --- Query CodeArtifact for the latest published version ---
-        # uv pip compile resolves the latest matching version from the index.
-        # We constrain to the current major.minor series for `main` context.
-        resolve_latest() {
-          local constraint="$1"
-          local output
-          # uv pip compile exits non-zero both when nothing matches (a normal
-          # "not published yet" result) and on real failures (network/auth/etc).
-          # Only treat the former as benign; anything else must surface and fail.
-          output=$(echo "$constraint" \
-            | uv pip compile - --index-url "$INDEX_URL" --no-deps --quiet 2>&1) || {
-            if echo "$output" | grep -qiE 'no solution found|could not find a version|not found in the package registry'; then
-              echo ""
-              return 0
-            fi
-            echo "ERROR: uv pip compile failed for '${constraint}':" >&2
-            echo "$output" >&2
-            exit 1
-          }
-          echo "$output" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1 || true
-        }
-
-        # --- Compute version based on context ---
         case "$CONTEXT" in
-          vnext)
-            LATEST=$(resolve_latest "$PACKAGE")
-            if [ -n "$LATEST" ]; then
-              BASE="$LATEST"
-              echo "Latest published version: ${LATEST}"
-            else
-              # No published version at all — use the pyproject.toml seed
-              # as-is (not just its major.minor) so a patch already bumped
-              # there (e.g. baselining) isn't regressed.
-              BASE="$SEED"
-              echo "No published version found — falling back to seed version ${BASE}"
-            fi
-            VERSION="${BASE}+dev.${RUN_NUMBER}"
-            ;;
-
-          main)
-            # Resolve the highest patch within the current major.minor series.
-            LATEST_IN_SERIES=$(resolve_latest "${PACKAGE}>=${MAJOR_MINOR}.0,<${MAJOR_MINOR}.99999")
-            SEED_PATCH=$(echo "$SEED" | grep -oE '[0-9]+$')
-            if [ -n "$LATEST_IN_SERIES" ]; then
-              CURRENT_PATCH=$(echo "$LATEST_IN_SERIES" | grep -oE '[0-9]+$')
-              NEXT_FROM_PUBLISHED=$((CURRENT_PATCH + 1))
-              echo "Latest in ${MAJOR_MINOR}.x series: ${LATEST_IN_SERIES} → next patch: ${NEXT_FROM_PUBLISHED}"
-            else
-              NEXT_FROM_PUBLISHED=0
-              echo "No published version in ${MAJOR_MINOR}.x series"
-            fi
-            # The pyproject.toml seed's patch acts as a floor so a manual
-            # bump there (e.g. baselining) is never regressed — CI only
-            # takes over incrementing once publishing has caught up to it.
-            if [ "$SEED_PATCH" -gt "$NEXT_FROM_PUBLISHED" ]; then
-              NEXT_PATCH=$SEED_PATCH
-              echo "Seed patch (${SEED_PATCH}) is ahead of published — using it as the baseline"
-            else
-              NEXT_PATCH=$NEXT_FROM_PUBLISHED
-            fi
-            VERSION="${MAJOR_MINOR}.${NEXT_PATCH}"
-            ;;
-
-          main-bump)
-            VERSION="${MAJOR_MINOR}.0"
-            echo "Major/minor bump — patch resets to 0"
-            ;;
-
+          main|vnext) ;;
           *)
-            echo "::error::Unknown context '${CONTEXT}'. Supported: vnext, main, main-bump."
+            echo "::error::Unknown context '${CONTEXT}'. Supported: main, vnext."
             exit 1
             ;;
         esac
 
+        SEED=$(cd "packages/${PACKAGE}" && uv version --short)
+        SHORT_SHA=$(echo "$SHA" | cut -c1-7)
+
+        # Resolve the highest published build of the seed version. The `.*`
+        # prefix match includes the release itself and its post-releases.
+        # uv pip compile exits non-zero both when nothing matches (a normal
+        # "not published yet" result) and on real failures (network/auth/etc).
+        # Only treat the former as benign; anything else must surface and fail.
+        LATEST=""
+        if ! OUTPUT=$(echo "${PACKAGE}==${SEED}.*" \
+          | uv pip compile - --index-url "$INDEX_URL" --no-deps --quiet 2>&1); then
+          if ! echo "$OUTPUT" | grep -qiE 'no solution found|could not find a version|not found in the package registry'; then
+            echo "ERROR: uv pip compile failed for '${PACKAGE}==${SEED}.*':" >&2
+            echo "$OUTPUT" >&2
+            exit 1
+          fi
+        else
+          LATEST=$(echo "$OUTPUT" | grep -oE "==[0-9][^ ]*" | head -1 | cut -c3-)
+        fi
+
+        # First build of this version is .post0; otherwise increment the
+        # highest published .postN.
+        if [[ "$LATEST" =~ \.post([0-9]+) ]]; then
+          N=$(( ${BASH_REMATCH[1]} + 1 ))
+          echo "Latest published build: ${LATEST} -> next N: ${N}"
+        else
+          N=0
+          echo "No published .post build for ${SEED} (latest: '${LATEST:-none}') -> N: 0"
+        fi
+
+        VERSION="${SEED}.post${N}+${CONTEXT}.${SHORT_SHA}"
+
         echo "Computed version for ${PACKAGE} (${CONTEXT}): ${VERSION}"
-        echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+        echo "version=${VERSION}" >> "$GITHUB_OUTPUT"

.github/actions/create-package-release/action.yml

@@ -0,0 +1,146 @@
+name: Create package release
+description: >
+  Creates a published GitHub Release for a single package from its towncrier
+  CHANGELOG.md.
+
+  Reads the `## [<version>]` section of `packages/<package>/CHANGELOG.md` for
+  the release notes (falling back to a pointer message if absent), fails if the
+  target tag already exists, and creates the release tagged
+  `<package>-v<version>` at `target`. Optionally also creates a bare vanity
+  tag (no second GitHub Release) to continue a legacy tag series.
+
+  Prerequisites: repo must be checked out and the GitHub CLI (`gh`) available
+  (both true on GitHub-hosted runners).
+
+inputs:
+  package:
+    description: Package directory name under packages/ (e.g. overture-schema).
+    required: true
+  version:
+    description: Release version, major.minor.patch (e.g. 1.18.0).
+    required: true
+  tag:
+    description: Release tag (e.g. overture-schema-v1.18.0).
+    required: true
+  target:
+    description: Commit SHA the tag should point at.
+    required: true
+  latest:
+    description: Whether to mark this release as "Latest" (true/false).
+    required: false
+    default: "false"
+  vanity-tag:
+    description: >
+      Optional additional bare git tag to create at `target` (e.g. v1.18.0),
+      with no GitHub Release attached. A pre-existing tag warns instead of
+      failing; the vanity tag is cosmetic and must not fail a completed
+      release.
+    required: false
+    default: ""
+  dry-run:
+    description: >
+      When "true", resolve and print what would be released without creating
+      anything. Read-only: a pre-existing tag is reported as a warning, not a
+      failure.
+    required: false
+    default: "false"
+  token:
+    description: "Token used to create the release (needs contents: write)."
+    required: true
+
+outputs:
+  release-url:
+    description: URL of the created release, or empty on a dry run.
+    value: ${{ steps.release.outputs.release-url }}
+
+runs:
+  using: composite
+  steps:
+    - name: Create release
+      id: release
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        PACKAGE: ${{ inputs.package }}
+        VERSION: ${{ inputs.version }}
+        TAG: ${{ inputs.tag }}
+        TARGET: ${{ inputs.target }}
+        LATEST: ${{ inputs.latest }}
+        VANITY_TAG: ${{ inputs.vanity-tag }}
+        DRY_RUN: ${{ inputs.dry-run }}
+      run: |
+        set -euo pipefail
+
+        tag_exists=false
+        if gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+          tag_exists=true
+        fi
+
+        if [ "$tag_exists" = "true" ] && [ "$DRY_RUN" != "true" ]; then
+          echo "::error::Release ${TAG} already exists. A duplicate ${PACKAGE} ${VERSION} bump landed on main; investigate before re-releasing."
+          exit 1
+        fi
+
+        changelog="packages/${PACKAGE}/CHANGELOG.md"
+        notes=$(python3 "${GITHUB_ACTION_PATH}/extract_release_notes.py" "$VERSION" "$changelog")
+        if [ -z "$notes" ]; then
+          notes="Release ${VERSION} of \`${PACKAGE}\`. No changelog section was found; add towncrier fragments under \`packages/${PACKAGE}/changelog.d\` and run \`uv run towncrier build --config pyproject.toml --dir packages/${PACKAGE} --version ${VERSION}\`."
+        fi
+        printf '%s\n' "$notes" > "${RUNNER_TEMP}/notes.md"
+
+        latest_flag="--latest=false"
+        [ "$LATEST" = "true" ] && latest_flag="--latest"
+
+        if [ "$DRY_RUN" = "true" ]; then
+          [ "$tag_exists" = "true" ] && echo "::warning::Release ${TAG} already exists; a real run would fail here."
+          {
+            echo "## 🔍 Dry run: \`${PACKAGE}\` ${VERSION}"
+            echo ""
+            echo "Would create tag \`${TAG}\` at \`${TARGET}\` (${latest_flag})."
+            if [ -n "$VANITY_TAG" ]; then
+              echo "Would also create vanity tag \`${VANITY_TAG}\` (no release)."
+            fi
+            echo ""
+            echo "<details><summary>Notes</summary>"
+            echo ""
+            cat "${RUNNER_TEMP}/notes.md"
+            echo ""
+            echo "</details>"
+          } >> "$GITHUB_STEP_SUMMARY"
+          echo "release-url=" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        gh release create "$TAG" \
+          --repo "$GITHUB_REPOSITORY" \
+          --target "$TARGET" \
+          --title "\`${PACKAGE}\` ${VERSION}" \
+          --notes-file "${RUNNER_TEMP}/notes.md" \
+          $latest_flag
+
+        url=$(gh release view "$TAG" --repo "$GITHUB_REPOSITORY" --json url --jq .url)
+        echo "release-url=${url}" >> "$GITHUB_OUTPUT"
+
+        # Vanity tag: a bare ref continuing the legacy series, no second
+        # release. Cosmetic, so a collision warns rather than failing the
+        # already-published release.
+        if [ -n "$VANITY_TAG" ]; then
+          if gh api "repos/${GITHUB_REPOSITORY}/git/ref/tags/${VANITY_TAG}" >/dev/null 2>&1; then
+            echo "::warning::Vanity tag ${VANITY_TAG} already exists; leaving it untouched."
+          else
+            gh api "repos/${GITHUB_REPOSITORY}/git/refs" \
+              -f ref="refs/tags/${VANITY_TAG}" \
+              -f sha="$TARGET" >/dev/null
+            echo "Created vanity tag ${VANITY_TAG} at ${TARGET}."
+          fi
+        fi
+
+        {
+          echo "## 📦 Released \`${PACKAGE}\` ${VERSION}"
+          echo ""
+          echo "Tag \`${TAG}\`: [published GitHub Release](${url})."
+          if [ -n "$VANITY_TAG" ]; then
+            echo ""
+            echo "Vanity tag \`${VANITY_TAG}\` continues the legacy series (no separate release)."
+          fi
+        } >> "$GITHUB_STEP_SUMMARY"

.github/actions/create-package-release/extract_release_notes.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+
+"""
+Extract one package's release notes from its CHANGELOG.md.
+
+Run by the `Publish GitHub release` workflow. Prints the changelog section for the
+given version (the block from `## [<version>]` up to the next `## [` heading,
+stripped). Prints nothing if the changelog or the section is absent, so the
+caller can fall back to a default message.
+
+Usage:
+    extract_release_notes.py <version> <changelog-path>
+"""
+
+from pathlib import Path
+import sys
+
+
+def extract(version: str, changelog: str) -> str:
+    """Return the trimmed `## [<version>]` section, or "" if not found."""
+    path = Path(changelog)
+    if not path.is_file():
+        return ""
+
+    lines = path.read_text(encoding="utf-8").splitlines()
+    start = next(
+        (i for i, line in enumerate(lines) if line.startswith(f"## [{version}]")),
+        None,
+    )
+    if start is None:
+        return ""
+
+    end = next(
+        (j for j in range(start + 1, len(lines)) if lines[j].startswith("## [")),
+        len(lines),
+    )
+    return "\n".join(lines[start:end]).strip()
+
+
+def main() -> None:
+    if len(sys.argv) != 3:
+        print(f"Usage: {sys.argv[0]} <version> <changelog-path>", file=sys.stderr)
+        sys.exit(2)
+
+    sys.stdout.write(extract(sys.argv[1], sys.argv[2]))
+
+
+if __name__ == "__main__":
+    main()