From 80c71ac69ca966d8ec478f5d708e76869a19a74b Mon Sep 17 00:00:00 2001 From: Daniel Szoke Date: Fri, 22 May 2026 13:59:48 +0200 Subject: [PATCH 1/3] meta(commit): Add commit message helpers Add a `commit-msg` `pre-commit` hook that expands GitHub issue footers into markdown links and appends a matching Linear footer when GitHub comments include a linked Linear issue. Running this as a hook ensures footer expansion happens for both agent-written and manually-written commit messages. Add a commit agent skill that fetches Sentry commit guidelines before creating or amending commits and documents the footer format expected by the hook. I have been using a similar [commit skill](https://github.com/szokeasaurusrex/pi-agent/blob/85d169d0022f31c46cf7821e2f176bd739b1b2a2/skills/commit/SKILL.md) locally; this checks it into this repo with modifications for the new `pre-commit` hook. ### Examples A footer for [getsentry/sentry-rust#1](https://github.com/getsentry/sentry-rust/issues/1): ``` References #1 ``` becomes: ``` References [#1](https://github.com/getsentry/sentry-rust/issues/1) ``` A footer for [getsentry/sentry-rust#1130](https://github.com/getsentry/sentry-rust/issues/1130), which has a Linear linkback to [RUST-216](https://linear.app/getsentry/issue/RUST-216): ``` References #1130 ``` becomes: ``` References [#1130](https://github.com/getsentry/sentry-rust/issues/1130) References [RUST-216](https://linear.app/getsentry/issue/RUST-216) ``` --- .agents/skills/commit/SKILL.md | 55 ++++ .../commit/scripts/fetch-commit-guidelines.sh | 5 + .pre-commit-config.yaml | 8 + scripts/commit-msg-expand-issues.py | 244 ++++++++++++++++++ 4 files changed, 312 insertions(+) create mode 100644 .agents/skills/commit/SKILL.md create mode 100755 .agents/skills/commit/scripts/fetch-commit-guidelines.sh create mode 100644 .pre-commit-config.yaml create mode 100755 scripts/commit-msg-expand-issues.py diff --git a/.agents/skills/commit/SKILL.md b/.agents/skills/commit/SKILL.md new file mode 100644 index 000000000..2e9da3ee1 --- /dev/null +++ b/.agents/skills/commit/SKILL.md @@ -0,0 +1,55 @@ +--- +name: commit +description: Use this skill when asked to create or amend a commit. +--- + +# Commit + +Use this skill whenever creating or amending a commit. + +## 1) Fetch and follow official commit guidelines + +Run: + +```bash +scripts/fetch-commit-guidelines.sh +``` + +Use that output as the source of truth for commit format/rules. + +**Exception:** Do not **manually wrap lines** or **enforce maximum line length**, ignore any instructions to the contrary. + +## 2) Write the commit body for maintainers + +Commit messages are reused as PR descriptions. Therefore, write commit messages keeping in mind that the primary audiences are human code reviewers and future maintainers. Optimize for skimmability while retaining sufficient context around changes, but do not repeat context that is easily inferred from the changes themselves, linked issues, or background information that mainters with at least a basic familiarity of the codebase would possess. + +Some tips: +- include brief context for why the change is needed +- include why this approach was chosen (when relevant) +- include links to relevant sources/issues/docs when useful +- be concise, human, and specific +- assume reviewers will skim the linked issue; do not restate it in depth + +Commit messages use Markdown formatting. For example, use backticks for technical literals, inline links for URLs, and lists where useful. + +When committing, you should use heredoc format to preserve newlines and other formatting. + +## 3) Append Commit Footer + +If a commit is related to a GitHub issue, this must be noted in a footer. + +These footers must be placed on their own lines. The footer looks like the following: + +``` +[keyword] #[issue-id] +``` + +When the issue is in a different repo, use `[keyword] [repo]#[issue-id]` or, if the repo belongs to a different owner, `[keyword] [owner]/[repo]#[issue-id]`. + +The keywords "Closes", "Fixes" and "Resolves" indicate that the commit fully addresses the issue. Merging a pull request containing such a commit will close the referenced issue. + +The keywords "References", "Related to", and "Contributes to" may be used to indicate a relation to the issue, when the issue is not fully addressed by the commit. The issue will not be auto-closed upon merge. + +One commit may contain zero or more footers; make sure all related issues you are aware of have a corresponding footer. + +A pre-commit hook will take care of linking Linear issues, where applicable. Do not manually add these links, or use any format other than what is described here. You need to follow this precise format so that the pre-commit hook can work properly. diff --git a/.agents/skills/commit/scripts/fetch-commit-guidelines.sh b/.agents/skills/commit/scripts/fetch-commit-guidelines.sh new file mode 100755 index 000000000..ccc2026f8 --- /dev/null +++ b/.agents/skills/commit/scripts/fetch-commit-guidelines.sh @@ -0,0 +1,5 @@ +#!/usr/bin/env bash +set -euo pipefail + +URL="https://develop.sentry.dev/engineering-practices/commit-messages.md" +curl -fsSL "$URL" diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..784969acd --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,8 @@ +repos: + - repo: local + hooks: + - id: expand-github-linear-footer + name: Expand GitHub/Linear commit footer + entry: scripts/commit-msg-expand-issues.py + language: script + stages: [commit-msg] diff --git a/scripts/commit-msg-expand-issues.py b/scripts/commit-msg-expand-issues.py new file mode 100755 index 000000000..abcc0db2d --- /dev/null +++ b/scripts/commit-msg-expand-issues.py @@ -0,0 +1,244 @@ +#!/usr/bin/env python3 +"""Expand GitHub issue commit footers and add Linear footers when available.""" + +from __future__ import annotations + +import json +import re +import subprocess +import sys +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +FOOTER_RE = re.compile( + r"^(?P\s*)(?P\w+)\s+" + r"(?P(?:(?P[A-Za-z0-9_.-]+)/)?(?:(?P[A-Za-z0-9_.-]+))?#(?P[1-9][0-9]*))" + r"(?P\s*)$" +) +LINEAR_LINKBACK_AUTHORS = {"linear", "linear-code"} +LINEAR_LINKBACK_MARKERS = ("linear-linkback", "linear linkback") + +LINEAR_URL_RE = re.compile( + r"(?Phttps://linear\.app/[^\s<>)\]\"']*/issue/(?P[^/\s<>)\]\"']+)[^\s<>)\]\"']*)" +) + + +@dataclass(frozen=True) +class Match: + line_index: int + prefix: str + keyword: str + display: str + owner: str | None + repo: str | None + issue: str + suffix: str + + +@dataclass(frozen=True) +class IssueInfo: + url: str + linear_id: str | None = None + linear_url: str | None = None + + +def warn(message: str) -> None: + print(f"commit-msg-expand-issues: warning: {message}", file=sys.stderr) + + +def run_gh(args: list[str]) -> tuple[dict[str, Any] | None, str | None]: + try: + result = subprocess.run( + ["gh", *args], + check=False, + capture_output=True, + encoding="utf-8", + ) + except FileNotFoundError: + return None, "gh was not found" + except OSError as exc: + return None, f"failed to run gh: {exc}" + + if result.returncode != 0: + detail = (result.stderr or result.stdout).strip() + return None, detail or f"gh exited with status {result.returncode}" + + try: + return json.loads(result.stdout), None + except json.JSONDecodeError as exc: + return None, f"failed to parse gh output: {exc}" + + +def run_gh_text(args: list[str]) -> tuple[str | None, str | None]: + try: + result = subprocess.run( + ["gh", *args], + check=False, + capture_output=True, + encoding="utf-8", + ) + except FileNotFoundError: + return None, "gh was not found" + except OSError as exc: + return None, f"failed to run gh: {exc}" + + if result.returncode != 0: + detail = (result.stderr or result.stdout).strip() + return None, detail or f"gh exited with status {result.returncode}" + return result.stdout.strip(), None + + +def current_repo() -> tuple[str, str] | None: + name_with_owner, error = run_gh_text( + ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"] + ) + if error is not None: + warn(f"could not resolve current repository: {error}") + return None + + if not name_with_owner or "/" not in name_with_owner: + warn("could not resolve current repository: unexpected gh output") + return None + + owner, repo = name_with_owner.split("/", 1) + return owner, repo + + +def is_linear_linkback_comment(comment: dict[str, Any]) -> bool: + author = comment.get("author") + if not isinstance(author, dict) or author.get("login") not in LINEAR_LINKBACK_AUTHORS: + return False + + body = comment.get("body") + if not isinstance(body, str): + return False + + normalized_body = body.lower() + return any(marker in normalized_body for marker in LINEAR_LINKBACK_MARKERS) + + +def find_linear_link(issue: dict[str, Any]) -> tuple[str, str] | None: + comments = issue.get("comments") or [] + if not isinstance(comments, list): + return None + + for comment in comments: + if not isinstance(comment, dict) or not is_linear_linkback_comment(comment): + continue + + body = comment["body"] + url_match = LINEAR_URL_RE.search(body) + if not url_match: + continue + + return url_match.group("id"), url_match.group("url") + return None + + +def fetch_issue(owner_repo: str, issue_number: str) -> IssueInfo | None: + result, error = run_gh( + ["issue", "view", issue_number, "-R", owner_repo, "--json", "number,url,comments"] + ) + if error is not None: + warn(f"could not fetch {owner_repo}#{issue_number}: {error}") + return None + if not isinstance(result, dict) or not isinstance(result.get("url"), str): + warn(f"could not fetch {owner_repo}#{issue_number}: unexpected gh output") + return None + + linear = find_linear_link(result) + if linear is None: + return IssueInfo(url=result["url"]) + linear_id, linear_url = linear + return IssueInfo(url=result["url"], linear_id=linear_id, linear_url=linear_url) + + +def collect_matches(lines: list[str]) -> list[Match]: + matches: list[Match] = [] + for index, line in enumerate(lines): + stripped_newline = line.removesuffix("\n") + match = FOOTER_RE.match(stripped_newline) + if match is None: + continue + matches.append( + Match( + line_index=index, + prefix=match.group("prefix"), + keyword=match.group("keyword"), + display=match.group("display"), + owner=match.group("owner"), + repo=match.group("repo"), + issue=match.group("issue"), + suffix=match.group("suffix"), + ) + ) + return matches + + +def resolve_owner_repo(match: Match, current_owner: str, current_repo_name: str) -> str: + if match.owner is not None and match.repo is not None: + return f"{match.owner}/{match.repo}" + if match.repo is not None: + return f"{current_owner}/{match.repo}" + return f"{current_owner}/{current_repo_name}" + + +def process_message(path: Path) -> None: + try: + lines = path.read_text(encoding="utf-8").splitlines(keepends=True) + except OSError as exc: + warn(f"could not read commit message: {exc}") + return + + matches = collect_matches(lines) + if not matches: + return + + repo = current_repo() + if repo is None: + return + current_owner, current_repo_name = repo + + issue_cache: dict[tuple[str, str], IssueInfo | None] = {} + replacements: dict[int, str] = {} + + for match in matches: + owner_repo = resolve_owner_repo(match, current_owner, current_repo_name) + key = (owner_repo, match.issue) + if key not in issue_cache: + issue_cache[key] = fetch_issue(owner_repo, match.issue) + + issue = issue_cache[key] + if issue is None: + continue + + replacement = f"{match.prefix}{match.keyword} [{match.display}]({issue.url}){match.suffix}\n" + if issue.linear_id is not None and issue.linear_url is not None: + next_line = lines[match.line_index + 1] if match.line_index + 1 < len(lines) else "" + linear_line = f"{match.prefix}{match.keyword} [{issue.linear_id}]({issue.linear_url})\n" + if next_line != linear_line: + replacement += linear_line + replacements[match.line_index] = replacement + + if not replacements: + return + + new_lines = [replacements.get(index, line) for index, line in enumerate(lines)] + try: + path.write_text("".join(new_lines), encoding="utf-8") + except OSError as exc: + warn(f"could not write commit message: {exc}") + + +def main(argv: list[str]) -> int: + if len(argv) != 2: + warn("expected exactly one commit message file path") + return 0 + + process_message(Path(argv[1])) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv)) From fed14cd96c2bcaf8527e06c88a5d3d62ac6a5143 Mon Sep 17 00:00:00 2001 From: Daniel Szoke Date: Tue, 26 May 2026 10:07:06 +0200 Subject: [PATCH 2/3] fixup! Fix regex --- .gitignore | 1 + scripts/commit-msg-expand-issues.py | 25 +++++++++++++++++++------ 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index 78c683245..56d1d0d49 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ target venv .claude/settings.local.json .DS_Store +__pycache__ diff --git a/scripts/commit-msg-expand-issues.py b/scripts/commit-msg-expand-issues.py index abcc0db2d..7d1c50a77 100755 --- a/scripts/commit-msg-expand-issues.py +++ b/scripts/commit-msg-expand-issues.py @@ -12,9 +12,9 @@ from typing import Any FOOTER_RE = re.compile( - r"^(?P\s*)(?P\w+)\s+" - r"(?P(?:(?P[A-Za-z0-9_.-]+)/)?(?:(?P[A-Za-z0-9_.-]+))?#(?P[1-9][0-9]*))" - r"(?P\s*)$" + r"^(?P\s*)(?P\w+(?:\s+to)?)\s+" + r"(?P(?:(?P[A-Za-z0-9_.-]+)/)?(?:(?P[A-Za-z0-9_.-]+))?#(?P[1-9]\d*))" + r"(?P\.?\s*)$" ) LINEAR_LINKBACK_AUTHORS = {"linear", "linear-code"} LINEAR_LINKBACK_MARKERS = ("linear-linkback", "linear linkback") @@ -107,7 +107,10 @@ def current_repo() -> tuple[str, str] | None: def is_linear_linkback_comment(comment: dict[str, Any]) -> bool: author = comment.get("author") - if not isinstance(author, dict) or author.get("login") not in LINEAR_LINKBACK_AUTHORS: + if ( + not isinstance(author, dict) + or author.get("login") not in LINEAR_LINKBACK_AUTHORS + ): return False body = comment.get("body") @@ -138,7 +141,15 @@ def find_linear_link(issue: dict[str, Any]) -> tuple[str, str] | None: def fetch_issue(owner_repo: str, issue_number: str) -> IssueInfo | None: result, error = run_gh( - ["issue", "view", issue_number, "-R", owner_repo, "--json", "number,url,comments"] + [ + "issue", + "view", + issue_number, + "-R", + owner_repo, + "--json", + "number,url,comments", + ] ) if error is not None: warn(f"could not fetch {owner_repo}#{issue_number}: {error}") @@ -215,7 +226,9 @@ def process_message(path: Path) -> None: replacement = f"{match.prefix}{match.keyword} [{match.display}]({issue.url}){match.suffix}\n" if issue.linear_id is not None and issue.linear_url is not None: - next_line = lines[match.line_index + 1] if match.line_index + 1 < len(lines) else "" + next_line = ( + lines[match.line_index + 1] if match.line_index + 1 < len(lines) else "" + ) linear_line = f"{match.prefix}{match.keyword} [{issue.linear_id}]({issue.linear_url})\n" if next_line != linear_line: replacement += linear_line From 7b4b8279a13541b3cbb7eb91862928ad92911971 Mon Sep 17 00:00:00 2001 From: "Daniel Szoke (via Pi Coding Agent)" Date: Tue, 26 May 2026 10:12:25 +0200 Subject: [PATCH 3/3] fixup! meta(commit): Add commit message helpers --- .pre-commit-config.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 784969acd..310024ec7 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,3 +1,5 @@ +default_install_hook_types: [commit-msg] + repos: - repo: local hooks: