Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

ci(governance): require a Conventional Commit PR title (#3063)

Tejas Chopracbb950a441b0
diff --git a/scripts/pr-governance.py b/scripts/pr-governance.py
index 8c5165e39..313be118f 100644
--- a/scripts/pr-governance.py
+++ b/scripts/pr-governance.py
@@ -41,6 +41,28 @@ ROLLOUT_FIELDS = (
"Rollback path",
)
+# Conventional-commit types accepted by .commitlintrc.json. Keep the two in
+# sync: commitlint gates the *commits* on a PR, but the repo squash-merges, so
+# it is the PR *title* that becomes the subject line on main.
+COMMIT_TYPES = (
+ "build",
+ "chore",
+ "ci",
+ "deps",
+ "docs",
+ "feat",
+ "fix",
+ "parity",
+ "perf",
+ "refactor",
+ "revert",
+ "style",
+ "test",
+)
+
+# type(optional-scope)!: subject
+TITLE_RE = re.compile(rf"^(?:{'|'.join(COMMIT_TYPES)})(?:\([^)]+\))?!?: .+")
+
SECTION_RE = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE)
CHECKBOX_RE = re.compile(r"^- \[(?P<checked>[ xX])\] (?P<label>.+)$", re.MULTILINE)
HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
@@ -172,6 +194,19 @@ def validate_pull_request(event: dict[str, Any]) -> GovernanceReport:
sections = extract_sections(body)
problems: list[str] = []
+ # A squash-merge uses the PR title as the commit subject on main, and
+ # release-please parses those subjects. One unparseable title stops it
+ # building a release PR at all, and the change is silently dropped from the
+ # changelog either way. commitlint cannot catch this: it lints the commits
+ # inside the PR, not the title that replaces them.
+ title = (pull_request.get("title") or "").strip()
+ if not TITLE_RE.match(title):
+ problems.append(
+ f"PR title must be a Conventional Commit — `type(scope): subject` — because "
+ f"squash-merge makes it the commit subject on `main` and release-please parses it. "
+ f"Got: `{title or '(empty)'}`. Valid types: {', '.join(f'`{t}`' for t in COMMIT_TYPES)}."
+ )
+
for section_name in REQUIRED_SECTIONS:
if section_name not in sections:
problems.append(f"Missing required section `{section_name}`.")
diff --git a/scripts/tests/test_pr_governance.py b/scripts/tests/test_pr_governance.py
index b3505959a..511b091a2 100644
--- a/scripts/tests/test_pr_governance.py
+++ b/scripts/tests/test_pr_governance.py
@@ -19,11 +19,21 @@ def _load_module():
return module
-def _event(body: str, *, draft: bool = False, login: str = "octocat") -> dict[str, object]:
+def _event(
+ body: str,
+ *,
+ draft: bool = False,
+ login: str = "octocat",
+ title: str = "feat(governance): add a required PR-governance gate",
+) -> dict[str, object]:
+ # A real `pull_request` payload always carries a title, and squash-merge
+ # turns it into the commit subject on main, so the default here is a valid
+ # Conventional Commit. Tests that exercise the title rule pass their own.
return {
"pull_request": {
"number": 42,
"draft": draft,
+ "title": title,
"body": body,
"user": {"login": login},
}
@@ -233,3 +243,71 @@ def test_validate_pull_request_skips_bot_authored_prs() -> None:
assert report.is_bot_pr is True
assert report.needs_author_action is False
assert report.labels_to_add == []
+
+
+def test_validate_pull_request_rejects_non_conventional_title() -> None:
+ """The exact title that stalled release-please on v0.35.0 must be caught.
+
+ `Unify savings attribution ...` squash-merged to main as commit 31452426.
+ release-please could not parse it (`unexpected token ' ' at 1:6`), so the
+ change never reached a changelog. commitlint passed the PR because it lints
+ the commits inside it, not the title that replaces them on squash-merge.
+ """
+ module = _load_module()
+ report = module.validate_pull_request(
+ _event(
+ VALID_BODY, title="Unify savings attribution across stats, perf, metrics, and dashboard"
+ )
+ )
+
+ assert report.valid is False
+ assert any("Conventional Commit" in problem for problem in report.problems)
+
+
+def test_validate_pull_request_accepts_conventional_titles() -> None:
+ module = _load_module()
+ for title in (
+ "fix(proxy): keep prefixed core tools resident",
+ "deps: bump sha2 from 0.10.9 to 0.11.0",
+ "chore: release main",
+ "feat!: drop python 3.10",
+ "fix(proxy/anthropic): stop replaying the recorded prefix",
+ ):
+ report = module.validate_pull_request(_event(VALID_BODY, title=title))
+ assert report.valid is True, (title, report.problems)
+
+
+def test_validate_pull_request_rejects_empty_and_typeless_titles() -> None:
+ module = _load_module()
+ for title in ("", " ", "WIP", "fix:", "Fix(proxy): capitalised type", "update stuff"):
+ report = module.validate_pull_request(_event(VALID_BODY, title=title))
+ assert report.valid is False, title
+ assert any("Conventional Commit" in problem for problem in report.problems), title
+
+
+def test_bot_authored_prs_skip_title_enforcement() -> None:
+ """Dependabot/release-please titles are already conventional; don't gate them."""
+ module = _load_module()
+ report = module.validate_pull_request(
+ _event("", login="dependabot[bot]", title="Bump sha2 from 0.10.9 to 0.11.0")
+ )
+
+ assert report.is_bot_pr is True
+ assert report.valid is True
+
+
+def test_commit_types_match_commitlint_config() -> None:
+ """The gate and commitlint must accept the same type vocabulary.
+
+ They enforce the same rule at two points in the lifecycle -- commitlint on
+ the PR's commits, this on the title that squash-merge substitutes for them.
+ Divergence would let a title through that the commit hook rejects, or vice
+ versa.
+ """
+ module = _load_module()
+ config = json.loads(
+ (Path(__file__).parent.parent.parent / ".commitlintrc.json").read_text(encoding="utf-8")
+ )
+ _level, _applicable, allowed = config["rules"]["type-enum"]
+
+ assert sorted(module.COMMIT_TYPES) == sorted(allowed)