Commit Notation
Quatico's commit notation system is based on Arlo's commit notation, combining intention and risk metadata to provide clear, actionable information about each commit.
Overview
Every commit message starts with a 3-character prefix that communicates:
- What did you intend to do with the commit? (Core Intention)
- How risky was the change? (Risk Level)
Format
[Intention][Risk] Short subject line (< 75 chars) using present participle
Optional message body with further explanation.
#JIRA-TICKET-1234
The Four Risk Levels
Risk levels indicate how risky the change is with regard to altering the system behavior or the understanding of the code by yourself and your collaborators.
| Risk Level | Code | Example | Meaning |
|---|---|---|---|
| Known safe | lowercase letter | r Extract method Applesauce | Addresses all known and unknown risks. Perform task preventing potential risks. |
| Validated | uppercase letter | R Extract method Applesauce | Addresses all known risks. Includes validation for all known risks with automated tests. |
| Risky | uppercase followed by 2 bangs | R!! Extract method Applesauce | Known risks remain unverified. Aware of risks but no formal verification available. |
| (Probably) Broken | uppercase followed by 2 stars | R** Start extracting method with no name | No risk attestation. Known broken or no possibility to check. May not compile. |
Lower case means lower risk!
Core Intentions
Refactoring (r/R/R!!/R**)
Change implementation without changing program behavior
Changes code structure or organization without altering what the program does from a user's perspective.
Known Risks:
- May cause or fix a bug
- May change a behavior without impact to the customer
- May lead to a change in test code
| Code | Known Approaches |
|---|---|
r | One of: • Provable refactoring (automated tools) • Test-supported Procedural Refactoring entirely within test code |
R | Test-supported Procedural Refactoring |
R!! | Identified single, named refactoring, but executed by editing code or without whole-project test coverage |
R** | Remodeled by editing code, even in small chunks, does not even compile |
Bug (b/B/B!!/B**)
Repair one existing, undesirable program behavior without altering any others
Fixes a defect in the system while keeping everything else unchanged.
Known Risks:
- May alter related/unrelated features which were supposed to stay unchanged
- Implementation may be different than intended change
- May change behavior customers depend on (is it really a bug?)
| Code | Known Approaches |
|---|---|
b | None known |
B | Meets all of: • Reviewed current and new behavior with customer representative • Change is ≤ 8 LoC² • Bug's original (buggy) behavior was captured in a unit test prior to this change • Change includes 1 changed unit test, matching intended behavior alteration |
B!! | Change includes unit tests for new behavior |
B** | No automatic tests, or unfinished implementation |
Feature (f/F/F!!/F**)
Add, change or extend one program behavior aspect without altering others
Introduces new functionality or modifies existing functionality in an intentional way.
Known Risks:
- May alter related/unrelated features which were supposed to stay unchanged
- Implementation may be different than intended change
| Code | Known Approaches |
|---|---|
f | None known |
F | Meets all of: • Change is ≤ 8 LoC² • Feature was fully unit tested prior to this change • Change includes new or changed unit tests to match intended behavior alteration |
F!! | Change includes unit tests for new behavior |
F** | No automatic tests, or unfinished implementation |
Documentation (d/D/D!!/D**)
Change communicates to team members and does not impact program behavior
Updates documentation, comments, or other non-functional content.
Known Risks:
- May mislead future developers (including yourself) and other stakeholders
- May alter processes within team with unintended consequences
| Code | Known Approaches |
|---|---|
d | Developer-visible documentation, not in a source file, or verified to generate byte-identical compilation |
D | Dev-impacting only, but changes compilation or process. E.g., changing text on a dev-only screen, or changes code-review checklist |
D!! | Alters an important process |
D** | Trying out a process change that is intended to gain info, not to work |
Other Core Intentions
Test-only (T)
Alter automated tests without altering functionality.
Use when: You're adding/updating tests without changing production code behavior.
Environment (E)
Environment (non-code) changes that affect development setup and other tooling changes that don't affect program behavior (e.g., linting).
Use when: Updating build configurations, CI/CD pipelines, development tools, or linting rules.
Auto (A)
Automatic formatting, code generation.
Use when: Applying automated formatters, code generators, or similar tools.
Comment (C)
Changes in comments only, without Java/JS Doc.
Use when: Adding or updating inline comments that don't affect documentation generation.
Unknown/Multiple (*)
Just a bunch of changes to be checked in. No real way to verify safety and may not compile.
Use when: You're committing exploratory changes or work in progress. ⚠️ Use sparingly!
Spec (S)
Formal specification, design reviews.
Use when: Documenting formal specifications or architectural decisions.
Merge Commit (M)
Merge commit.
Use when: Merging branches. Often handled automatically by Git.
Benefits
For Code Reviews
- Quick Risk Assessment: Reviewers can immediately see how risky a change is
- Faster Approval: Low-risk commits (lowercase) can be approved quickly
- Focus Attention: High-risk commits (R!!, R**) get extra scrutiny
For Release Management
- Easy History Reading: Understand what changed in a release by scanning commit prefixes
- Risk Tracking: Identify which commits might need extra testing
- Deployment Decisions: Series of lowercase commits can be deployed without extensive regression testing
Provable Refactorings
If you can get a series of commits that is all lowercase commits, you can deploy without the need for regression testing, or lengthy conversations about accepting the pull request to trunk.
A provable refactoring requires the burden of proof. The main methods of proof are:
- Automated refactoring via tool
- Scripted manual refactoring, using the compiler to verify each step
- Very highly tested code, with the tests providing proof
Examples
Good Commit Messages
r Extract calculateTotal method
Extracted calculation logic into separate method for reusability.
#PROJ-1234
F Add user authentication
Implements JWT-based authentication with token refresh.
#PROJ-2345
B Fix null pointer in user service
User service crashed when email was null. Added null check
and test to verify the fix.
#PROJ-3456
D Update API documentation
Added examples for new endpoints in developer guide.
#PROJ-4567
Commit Message Checklist
- Starts with 3-character prefix (intention + risk)
- Subject line is < 75 characters
- Uses present participle (e.g., "Adding", "Fixing", "Refactoring")
- Optional body explains the "why" not the "what"
- Ends with JIRA ticket reference
Tips
- Be Honest About Risk: If you're not sure, use a higher risk level
- Keep Commits Focused: One intention per commit when possible
- Write for Your Future Self: Your commit history tells a story
- Aim for Lowercase: The more you can prove safety, the faster you can ship
- Don't Guess: If you can't verify, mark it risky
References
- Original Arlo's Commit Notation: Arlo Belshee's Blog
- Related: Conventional Commits