GitHub PR Title
Craft clear PR titles using conventional commits format.
CRITICAL: PR titles must follow conventional commit format. This drives release-please version automation and ensures consistent git history when using squash-and-merge.
When to Use
| Use this skill when... | Use X instead when... |
|---|---|
| Creating a PR title | Full PR workflow (git-pr) |
| Reviewing title format | Issue titles (github-issue-writing) |
| Updating existing PR title | Fixing committed messages (see git-commit) |
Format
<type>(<scope>): <subject>
See Conventional Commits Standards for comprehensive format guide.
Type Selection
| Type | Use Case | Version Bump |
|---|---|---|
feat |
New feature | Minor |
fix |
Bug fix | Patch |
perf |
Performance improvement | Patch |
refactor |
Code restructure (no behavior change) | None |
docs |
Documentation only | None |
test |
Tests | None |
build |
Build/deps | None |
ci |
CI config | None |
chore |
Maintenance | None |
Decision tree: Feature → feat | Bug → fix | Performance → perf | Restructure → refactor | Docs → docs | Everything else → chore
Scope
Optional component identifier. Keeps commits organized:
feat(auth): add OAuth support
fix(api): handle null response
docs(readme): update install steps
refactor(core): simplify error handling
Discover repo scopes:
gh pr list --state merged -L 30 --json title | jq -r '.[].title' | grep -oE '\([^)]+\)' | sort | uniq -c | sort -rn
Or from commits:
git log --format='%s' -n 50 | grep -oE '\([^)]+\)' | sort | uniq -c | sort -rn
Subject
- Imperative mood: "add" not "adds" or "added"
- Lowercase: Start with lowercase after colon
- No period: Don't end with punctuation
- Under 50 chars: Keep concise
Examples:
| ❌ Bad | ✅ Good |
|---|---|
Added login button |
add login button |
Fixes the bug. |
fix null pointer in auth |
Update |
update dependencies |
Resolved Performance Issues |
improve query performance |
Breaking Changes
Append ! before colon:
feat(api)!: remove deprecated endpoints
fix!: require Node.js 18+
refactor(db)!: change schema format
Breaking changes trigger major version bumps.
Reverts
revert: feat(auth): add OAuth support
Quick Reference
| Scenario | Template |
|---|---|
| Feature | feat(<scope>): add <what> |
| Bug fix | fix(<scope>): resolve <what> |
| Performance | perf(<scope>): optimize <what> |
| Docs | docs(<scope>): update <what> |
| Refactor | refactor(<scope>): simplify <what> |
| Deps | build(deps): bump <pkg> to <ver> |
| Breaking | feat(<scope>)!: change <what> |
Why This Matters
Conventional commit PR titles ensure:
- Accurate automation - release-please reads PR titles to determine version bumps
- Clean git history - squash-and-merge uses PR title as commit message
- Searchable commits - type prefix makes filtering easy
- CHANGELOG accuracy - commits are grouped by type in generated changelogs
Agentic Optimizations
| Context | Command |
|---|---|
| Get commits | git log origin/main..HEAD --format='%s' -n 10 |
| Changed dirs | git diff origin/main..HEAD --name-only | xargs dirname | sort -u |
| Update title | gh pr edit N --title "new title" |
| Discover scopes | gh pr list --state merged -L 30 --json title | jq -r '.[].title' | grep -oE '\([^)]+\)' | sort | uniq |
Reference
For detailed rules, patterns, and troubleshooting, see Conventional Commits Standards.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.