Ruby Commit Message
Overview
Write structured commit messages following Conventional Commits. The body should help a junior Ruby on Rails developer understand the change during a debugging session.
Format
<type>(<scope>): <subject>
<body>
<footer>Quick Reference — Commit Types
| Type | Purpose |
|---|---|
feat | New feature |
fix | Bug fix |
refactor | Refactoring (no behavior change) |
perf | Performance improvement |
docs | Documentation only |
test | Test additions or corrections |
build | Build system or dependencies |
ci | CI configuration |
chore | Maintenance tasks |
style | Code formatting (no logic change) |
revert | Revert previous commit |
meta | Repository metadata |
license | License changes |
Subject Line Rules
- Imperative mood: "Add", "Fix", "Update", "Remove"
- Present tense: "Add feature" not "Added feature"
- Capitalized first letter, no period at end
- Maximum 70 characters
- Scope (optional): noun describing the section of codebase, e.g.
(api),(auth)
Body Guidelines
Couple of sentences, wrapped at 72 chars, blank line after subject. Write for a junior Ruby developer: simple language they can understand during debugging. Add any useful information that would help a junior Ruby developer understand the impact of the change, why the change was done.
- WHY — motivation, problem, or user impact. Use context if it exists for this.
- WHAT changed — make this brief; the diff already shows the HOW
- HOW — only when there are details about the how that are not reflected by the code or the naming in the code
Call out tradeoffs when supported by context. Do not invent details.
Footer & AI Attribution
Fixes TICKET-123 # or: Fixes #123, Refs TICKET-123
BREAKING CHANGE: ... # for breaking changes; use ! in type too: feat(api)!:
Co-Authored-By: <AI Name> <email> # when AI generated the changeDo NOT add "Generated by AI" or "Written with Claude" in the subject or body. Use only Co-Authored-By.
Examples
Security/Authorization Fix
fix(api): Scope report access to current user
Report.find allowed any authenticated user to view any report by ID.
Querying through current_user.reports makes Rails raise RecordNotFound
(404) if the report doesn't belong to the requester.New Feature
feat(alerts): Add Slack thread replies for alert updates
When an alert is updated or resolved, post a reply to the original
Slack thread. This keeps related notifications grouped together.
Refs GH-1234Breaking Change
feat(api)!: Remove deprecated v1 endpoints
Remove all v1 API endpoints deprecated in version 23.1.
Clients should migrate to v2 endpoints.
BREAKING CHANGE: v1 endpoints no longer availableCommon Mistakes
| Mistake | Fix |
|---|---|
| Body explains HOW without context | Only include HOW when it helps debugging |
| Subject describes implementation ("Changed X to Y") | Use imperative: "Fix X", "Add Y" |
| Body repeats what the diff shows | Explain WHY it was changed |
| Subject over 70 characters | Trim scope or rephrase |
| "Generated by AI" in body | Use Co-Authored-By footer only |