changelog-prestage.yml

name: Pre-stage CHANGELOG before release

# Triggered manually (`workflow_dispatch`) before opening a release PR.
# Inserts the `## [<tag>] - <date>` heading + footer link into develop's
# CHANGELOG ahead of time, and merges main into develop on the prestage
# branch so develop's CHANGELOG already has the structural shape main
# carries. The release PR opened afterwards is conflict-free by
# construction.
#
# Why: release PRs commonly hit a same-line CHANGELOG conflict on the
# release-branch push because git sees both develop and main editing
# the region right after `## [Unreleased]`. The pre-#168 pattern was for
# the operator to manually `git merge origin/main` on the release branch
# every time; this workflow packages the same merge plus the heading
# insertion as a reviewable PR.
#
# Distinct from `changelog-rollup.yml`: rollup runs *after* a release
# tag is cut, bumps the version, and is auto-triggered by release.yml
# success. Prestage runs *before* the tag, doesn't bump version (the
# post-release rollup does), and is operator-triggered. Both share
# `.github/scripts/rollup_changelog.py` — prestage uses the `--no-bump`
# flag.

on:
  workflow_dispatch:
    inputs:
      tag:
        description: "Tag about to be released (e.g. v1.11.0)"
        required: true
        type: string
      prior_tag:
        description: "Prior release tag for the compare link (auto-resolves if empty)"
        required: false
        type: string
        default: ""
      date:
        description: "Release date YYYY-MM-DD (defaults to today UTC)"
        required: false
        type: string
        default: ""

permissions:
  contents: write
  pull-requests: write

jobs:
  prestage:
    name: Open prestage PR
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
        with:
          ref: develop
          # Full history so `git describe --abbrev=0 --tags` can resolve
          # the prior tag, and the `git merge origin/main` step has a
          # complete merge-base.
          fetch-depth: 0
          # Prefer RELEASE_BOT_TOKEN so the prestage branch's push fires
          # `pull_request` workflows on the auto-PR. Falls back to
          # GITHUB_TOKEN when the secret isn't set — the auto-PR still
          # opens, but its CI doesn't run until a user pushes on top.
          token: ${{ secrets.RELEASE_BOT_TOKEN || secrets.GITHUB_TOKEN }}

      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
        with:
          python-version: "3.14"

      - name: Resolve inputs
        id: resolve
        run: |
          set -euo pipefail
          TAG="${{ inputs.tag }}"
          if [ -z "${TAG}" ]; then
            echo "::error::tag input is required"
            exit 1
          fi
          # Auto-resolve prior tag if not provided (mirrors changelog-rollup.yml).
          PRIOR="${{ inputs.prior_tag }}"
          if [ -z "${PRIOR}" ]; then
            if PRIOR=$(git describe --abbrev=0 --tags --match 'v*.*.*' "${TAG}^" 2>/dev/null); then
              echo "prior tag (resolved): ${PRIOR}"
            else
              # Try the most recent tag on main if `<TAG>^` doesn't resolve
              # (the tag isn't cut yet — that's the whole point of prestage).
              if PRIOR=$(git describe --abbrev=0 --tags --match 'v*.*.*' origin/main 2>/dev/null); then
                echo "prior tag (resolved from main): ${PRIOR}"
              else
                PRIOR=""
                echo "no prior tag (first release)"
              fi
            fi
          fi
          DATE="${{ inputs.date }}"
          if [ -z "${DATE}" ]; then
            DATE=$(date -u +%Y-%m-%d)
          fi
          echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
          echo "prior=${PRIOR}" >> "$GITHUB_OUTPUT"
          echo "date=${DATE}" >> "$GITHUB_OUTPUT"
          echo "branch=chore/changelog-prestage-${TAG}" >> "$GITHUB_OUTPUT"

      - name: Create prestage branch + merge main
        env:
          BRANCH: ${{ steps.resolve.outputs.branch }}
        run: |
          set -euo pipefail
          # Idempotent: if the branch already exists from a previous replay,
          # bail rather than force-push.
          if git ls-remote --exit-code --heads origin "${BRANCH}" >/dev/null 2>&1; then
            echo "::warning::branch ${BRANCH} already exists; skipping push to avoid clobbering an in-flight prestage PR"
            exit 0
          fi
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git checkout -b "${BRANCH}"
          # Bring main's CHANGELOG state into develop. Prefer auto-merge;
          # if there's a real conflict (rare in steady-state — develop and
          # main usually share their post-rollup history), fail fast with
          # a clear message so the operator can resolve manually.
          if ! git merge --no-edit origin/main; then
            echo "::error::main → develop merge hit a conflict the prestage can't auto-resolve. Resolve manually on a local branch and re-run, or open the release PR by hand and merge main into the release branch (the pre-#168 pattern)."
            git merge --abort
            exit 1
          fi

      - name: Run rollup script in pre-stage mode
        run: |
          python .github/scripts/rollup_changelog.py \
            --tag "${{ steps.resolve.outputs.tag }}" \
            --prior-tag "${{ steps.resolve.outputs.prior }}" \
            --date "${{ steps.resolve.outputs.date }}" \
            --no-bump

      - name: Open prestage PR
        env:
          # Same fallback as the checkout step (#174) so the auto-PR
          # fires `pull_request` workflows on creation when the secret
          # is provisioned; falls back to GITHUB_TOKEN otherwise.
          GH_TOKEN: ${{ secrets.RELEASE_BOT_TOKEN || secrets.GITHUB_TOKEN }}
          BRANCH: ${{ steps.resolve.outputs.branch }}
          TAG: ${{ steps.resolve.outputs.tag }}
          DATE: ${{ steps.resolve.outputs.date }}
        run: |
          set -euo pipefail
          git add CHANGELOG.md
          git commit -m "chore: pre-stage CHANGELOG for ${TAG} - ${DATE}"
          git push origin "${BRANCH}"
          gh pr create \
            --base develop \
            --head "${BRANCH}" \
            --title "chore: pre-stage CHANGELOG for ${TAG} - ${DATE}" \
            --body "$(cat <<EOF
          Auto-opened by [.github/workflows/changelog-prestage.yml](.github/workflows/changelog-prestage.yml) before the ${TAG} release PR.

          ## What this PR does

          - Merges \`origin/main\` into develop (so develop's CHANGELOG has the same structural shape main carries).
          - Inserts \`## [${TAG#v}] - ${DATE}\` heading after \`## [Unreleased]\` in CHANGELOG.md.
          - Updates \`[Unreleased]: …/compare/${TAG}...HEAD\` footer link.
          - Adds \`[${TAG#v}]: …/compare/<prior>...${TAG}\` footer link.
          - **Does not** bump \`pyproject.toml\` / \`uv.lock\` — that's the post-release rollup's job.

          ## Operator next step

          Merge this PR into develop, then open the release PR develop → main with title \`release: ${TAG}\`. The release PR will be conflict-free because develop and main now agree on the CHANGELOG's structural shape.

          See [docs/DEVELOPMENT.md#creating-a-release](docs/DEVELOPMENT.md#creating-a-release) for the full cycle.
          EOF
          )"