pr-title.yml

name: PR title

on:
  pull_request:
    # Re-run on title edits + initial open + every push so the state
    # reflects the current title, not the one at PR creation.
    types: [opened, edited, synchronize, reopened]

permissions:
  contents: read
  pull-requests: read

# Closes the gap left by commitizen: the commit-msg hook only runs locally.
# Since this repo squash-merges every PR (see memory
# project_solo_owner_admin_merge), the merge commit's subject is the PR
# title — so enforcing conventional format on PR titles enforces it on
# main/develop history, regardless of merge method.
jobs:
  lint-pr-title:
    name: Lint PR title (conventional commits)
    runs-on: ubuntu-latest
    steps:
      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50  # v6.1.1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          # Same seven types as [tool.commitizen] in pyproject.toml.
          # `release` is project-specific for develop -> main release PRs.
          types: |
            feat
            fix
            docs
            test
            refactor
            chore
            release
          requireScope: false
          # Reject Title Case prose (`Add thing`, `Fix bug`) but allow
          # all-caps initialisms (`CI failure`, `SDK upgrade`, `API notes`)
          # and normal lowercase starts (`add thing`). The pattern matches
          # <uppercase><lowercase> which unambiguously signals Title Case;
          # <uppercase><uppercase> and <uppercase><non-letter> are fine.
          subjectPattern: '^(?![A-Z][a-z]).+$'
          subjectPatternError: |
            The subject "{subject}" found in the pull request title "{title}"
            starts with Title Case (a capitalised word as in prose). Use
            lowercase (`add the thing`, `fix the bug`) or an all-caps
            initialism (`CI failure`, `SDK upgrade`, `API contract`). See
            docs/DEVELOPMENT.md#commit-messages for the convention.