ci: check the pull request title, which a squash merge turns into a commit

[sgjholt]

Closes the hole that cost v0.5.0 its changelog entry. Its own title is the first thing the check runs against.

Why a hook cannot do this

A squash merge discards every subject on the branch and uses the PR title instead, composed by GitHub server-side, after all local hooks have run. The commit-msg hook never sees the subject that lands on main — and that subject is exactly what release-please parses.

#45 is the cost:

commit could not be parsed: 2af57e8 Make the station selection mean what the
  config says: radius, and one instrument per station (#45)
error message: Error: unexpected token ' ' at 1:5, valid tokens [(, !, :]
commits: 0
✔ Considering: 0 commits
✔ No commits for path: ., skipping

A radius fix, a WGS84 cut and two new config fields went out with no bump and no changelog entry. Both had to be repaired by hand in #47.

What this adds

.github/workflows/pr-title.yml runs tools/check_pr_title.py on opened, edited and reopened.

Written as a script rather than pulling in amannn/action-semantic-pull-request, for one reason worth the extra file: the accepted types are the ones release-please-config.json declares, and a test asserts the two lists are identical. A generic action would happily accept a type the release config does not know — which lands the work in no changelog section, the same silent failure reached from the other side.

The failure message names one thing to change:

::error::The pull request title is not a Conventional Commit: the type 'Feat'
must be lower case. A squash merge makes this title the commit subject on main,
and release-please computes the version and the changelog from it, so an
unparseable title ships the work with no changelog entry. Known types: feat,
fix, perf, refactor, docs, build, revert, test, ci, style, chore. Example:
'fix(acquire): ask for waveforms by name'.

Not "does not match ^(feat|fix|…)(\(.*\))?!?: .+$".

Security

The title is text anyone who can open a PR chooses. It reaches the script through env:, never interpolated into a shell command, and the workflow is pull_request with permissions: {} — not pull_request_target, which would hand a write token to a fork's title.

Tests

29 cases in tests/test_pr_title.py, seeded from what actually happened rather than from the grammar: #45's real title, #46's original Roadmap: …, a capitalised type, a missing space, an empty scope, every known type, and the (#45) suffix a squash appends.

Verification

pytest tests/test_pr_title.py tests/test_tools_track_the_api.py   38 passed
ruff check / ruff format --check                                  clean
mypy                                                              no issues in 65 source files

All 14 checks green on 3b4db69, including pr-title passing on this PR's own title.

Two things this does not do

• It does not disable squash merging. That is a repo setting (Settings → General → Pull Requests) and the safer default — a merge commit keeps every subject, which is why Unblock the release: compare the roadmap against the published minor, not the proposed one #44, feat(acquire): name the station-selection release, and file v0.4.0 as shipped #46 and docs(roadmap): file the station selection as shipped in v0.5.0 #48 all generated correct changelogs. This makes a squash safe when one is used anyway.
• It is not a required check until you add it to branch protection. Without that it reports but cannot block.

The estimator default change is not in here — measuring it turned up 21 failing tests and a prerequisite (REFACTOR_PLAN §6.6's absent config pin), so it wants its own PR rather than riding along with a CI fix.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 SpecMod | 🛠️ Build #34676347 | 📁 Comparing 3b4db69 against latest (ed4e10c)

  🔍 Preview build  

2 files changed

± roadmap.html
± tutorial/specmod-tutorial.html