prepare-release.yml

name: 'Prepare Release'

# Manual, on-demand releases (workflow_dispatch only). Bumps the version in
# pyproject.toml, rolls CHANGELOG.md [Unreleased] → the new version, opens a
# prepare-release/vX.Y.Z branch, and commits it as "chore: release vX.Y.Z".
# It does NOT merge or tag — a human merges the bump PR through the normal
# CI/review gate, then pushes the tag vX.Y.Z. That tag push (release.yml runs
# on: push tags) builds the stable semver Docker image, creates the GitHub
# release, and posts notes to Discord. We do not auto-merge (fleet policy,
# 2026-06-02: auto-merge fires on stale SHAs + breaks stacked PRs).
#
# Releases are deliberately NOT cut on every merge — pick the bump level and
# run this when a batch is ready. See docs/guides/releasing.md.

on:
  workflow_dispatch:
    inputs:
      bump:
        description: 'Version bump type'
        required: true
        type: choice
        options: [patch, minor, major]
        default: patch
      dry_run:
        description: 'Preview only — no branch or PR created'
        type: boolean
        default: false

concurrency:
  group: prepare-release
  cancel-in-progress: false

jobs:
  prepare:
    name: Prepare Release
    runs-on: ubuntu-latest  # workspace-config: allow-hosted-runner public repo — GH-hosted is free
    # Opt-in guard (fork-friendly): set the `RELEASE_ENABLED` repo variable to
    # `true` to enable the release pipeline. Forks enable it without editing this
    # workflow — so upstream changes to the file don't conflict on re-sync.
    if: vars.RELEASE_ENABLED == 'true'
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v5
        with:
          ref: main
          fetch-depth: 0
          # GH_PAT required (not GITHUB_TOKEN) so the release-branch push
          # below fires the PR's CI checks — the default token can't trigger
          # downstream workflows on pushes it makes.
          token: ${{ secrets.GH_PAT }}

      - uses: actions/setup-python@v6
        with:
          python-version: '3.12'

      - name: Bump version
        run: python scripts/version.py ${{ inputs.bump || 'patch' }}

      - name: Read new version
        id: version
        run: |
          V=$(python -c "
          import re, pathlib
          m = re.search(r'version\s*=\s*\"([^\"]+)\"', pathlib.Path('pyproject.toml').read_text())
          print(m.group(1))
          ")
          echo "version=$V" >> "$GITHUB_OUTPUT"

      - name: Roll changelog
        run: python scripts/changelog.py roll "${{ steps.version.outputs.version }}"

      - name: Scaffold a draft marketing changelog entry (curated content preserved)
        run: python scripts/changelog.py scaffold "${{ steps.version.outputs.version }}"

      - name: Preview (dry run)
        if: inputs.dry_run == true
        run: |
          echo "New version: v${{ steps.version.outputs.version }}"
          git --no-pager diff pyproject.toml CHANGELOG.md sites/marketing/data/changelog.json

      - name: Create release branch + PR
        if: inputs.dry_run != true
        env:
          GH_TOKEN: ${{ secrets.GH_PAT }}
        run: |
          VERSION="${{ steps.version.outputs.version }}"
          BRANCH="prepare-release/v${VERSION}"

          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          git checkout -b "${BRANCH}"
          git add pyproject.toml CHANGELOG.md sites/marketing/data/changelog.json
          git commit -m "chore: release v${VERSION}"
          git push origin "${BRANCH}"

          PR_URL=$(gh pr create \
            --base main \
            --head "${BRANCH}" \
            --title "chore: release v${VERSION}" \
            --body "Automated version bump to \`v${VERSION}\`. Review + merge through the normal CI/review gate, then push the tag to cut the release: \`git checkout main && git pull && git tag -a v${VERSION} -m 'Release v${VERSION}' && git push origin v${VERSION}\`. The tag push triggers release.yml (Docker tags + GitHub Release + Discord) — don't also workflow_dispatch release.yml afterward (redundant; 422s on the duplicate).")
          echo "Opened: ${PR_URL}"

          # We do NOT auto-merge or tag here (fleet policy, 2026-06-02:
          # auto-merge fires on stale SHAs + breaks stacked PRs). A human
          # merges this bump PR through the normal CI/review gate, then pushes
          # the tag v${VERSION} — the push (on: push tags) triggers release.yml,
          # which cuts the GitHub release + Docker tags + Discord notes. Do NOT
          # also workflow_dispatch release.yml (redundant; 422s on duplicate).
          echo "Next: review + merge that PR (we do not auto-merge), then push tag v${VERSION} to cut the release."