Skip to content

ADR 003: Enforce PR Title Format

  • Status: Accepted
  • Date: 2026-01-31
  • Author: Victoria Cheng

Context and Problem Statement

Our automated release process (see ADR 001) relies entirely on the format of Pull Request titles to determine version bumps. If a PR title is malformed (e.g., "Updated the readme" instead of "docs: update readme"), the release automation will silently skip a release or fail to categorize it correctly.

Currently, this relies on human review, which is fallible and scales poorly. A mechanism is needed to strictly enforce this convention at the CI level before a PR can be merged.

Decision Outcome

A GitHub Action workflow will be implemented using amannn/action-semantic-pull-request (or a similar lightweight mechanism) to validate every PR title against the Conventional Commits specification.

Implementation Details

  • Trigger: On pull_request events (types: opened, edited, synchronize, reopened).
  • Validation:
  • Must start with one of the allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
  • Must use the format: type(scope): description or type: description.
  • Feedback: The check will fail the PR status if the title is invalid, preventing merge if "Require status checks to pass" is enabled in branch protection rules.

Alternatives Considered but Rejected

  • Commit Message Linting (Commitlint): Rejected because PRs are squash-merged, making the PR title the source of truth for the final commit message on main. Linting individual commits inside the PR is unnecessary friction.
  • Custom Shell Script: Rejected in favor of a maintained action that provides better error messages and configuration options out of the box.
  • Post-Merge Validation: Rejected as it's too late; a bad commit would already be on main, requiring a revert or manual fix.

Consequences

Positive

  • Release Accuracy: Guarantees every merged PR triggers the correct release behavior.
  • Immediate Feedback: Contributors get instant feedback about incorrect formatting.
  • Reviewer Relief: Reduces mental load on reviewers to check for syntax.

Negative

  • Contributor Barrier: Adds a small barrier to entry for new contributors (mitigated by clear error messages).
  • Title Rework: Requires PR titles to be edited if the scope changes during review.

Verification

  • [x] CI Check: A new workflow check-pr-title.yml will be added.
  • [x] Branch Protection: This status check will be made mandatory for merging into main.