Commit Notation

A commit notation that conveys risk level and intention in the first few characters of each commit message. Based on Arlo's Commit Notation v1, extended by Quatico.

Quick Reference

Risk Levels

Risk Level	Code	Example	Meaning
Known safe	lowercase	r	Provable correctness (tool-verified, type-checked)
Validated	UPPERCASE	R	Test-verified, all known risks addressed
Risky	!!	R!!	Attempted but not fully verified
Broken	**	R**	WIP, may not compile

tip

Lower case means lower risk!

Intentions

Code	Name	Use
F	Feature	Add, change, or extend behavior
B	Bugfix	Repair undesirable behavior
R	Refactoring	Change implementation, not behavior. Includes tool-assisted changes (IDE renames, formatters, linters).
D	Documentation	Changes that communicate, no behavior impact. Includes comment-only changes and formal specifications.
T	Test-only	Alter tests without altering functionality
E	Environment	Dev setup, tooling, non-code changes
WIP	Unknown	Mixed changes, just checking in

Commit Message Format

X: Summary in active voice

TICKET-123

Rules:

• Prefix: Risk level + intention (e.g., F, r, B!!, R**)
• Separator: : or nothing (e.g., F: Add feature or F Add feature)
• Voice: Active ("Add feature") not progressive ("Adding feature")
• Length: Subject line < 75 characters
• Ticket: Last line, blank line before it, NO # prefix (git treats # as comment)

Ticket Numbers

Finding the ticket:

1. Branch name: Look for XXX-123 pattern (e.g., feature/FOO-123-login)
2. Recent commits: Check commits not yet merged to main branch
3. Ask: Is this infrastructure (omit) or does it need a ticket number?

When to omit tickets — infrastructure changes may skip tickets:

• CI/CD fixes
• Dev environment setup
• Release version bumps
• Dependency updates
• Code formatting

Quick Checklist

• Intention identified (F/B/R/D/T/E/*)
• Single intention per commit
• Risk level assessed (lowercase/UPPER/!!/**)
• Active voice summary
• Subject < 75 chars
• Ticket on last line (if applicable)

Risk Level Guidelines

Known Safe (lowercase)

Provable correctness through:

• IDE refactoring with type verification
• Compiler-verified transformations
• Automated tool with known behavior

Validated (UPPERCASE)

Test-verified changes:

• All tests pass after change
• New behavior covered by tests
• For features/bugfixes: change is ≤8 LoC

Risky (!!)

Attempted verification but gaps remain:

• Tests exist but coverage incomplete
• Manual review performed
• Named refactoring without full test suite

Broken (**)

No verification:

• WIP checkpoint
• May not compile
• Switching tasks, need to save state

Known Risks by Intention

Intention	Known Risks
Feature	May alter unrelated feature; may alter this feature unexpectedly; may differ from intended change
Bugfix	Customers may depend on the bug; may alter unrelated feature; may differ from intended fix
Refactoring	May cause a bug; may fix a bug accidentally; may force a test update
Documentation	May mislead future developers; may alter team processes unexpectedly

Core Intentions

Feature (f/F/F!!/F**)

Add, change, or extend one program behavior aspect without altering others.

Code	Known Approaches
f	Examples: Local/focused change validated in DEV (no env-specific behavior); Extensive E2E tests; Text-only changes (i18n) apparent from diff
F	Change ≤8 LoC, fully unit tested, includes new/changed tests
F!!	Partially tested
F**	No automatic tests, or unfinished implementation

Bugfix (b/B/B!!/B**)

Repair one existing, undesirable program behavior without altering any others.

Code	Known Approaches
b	Examples: Local/focused change validated in DEV; E2E tests; Text-only changes; Extend/fix existing test
B	Reviewed with customer rep, ≤8 LoC, original behavior captured in test, includes changed test
B!!	Partially tested
B**	No automatic tests, or unfinished implementation

Refactoring (r/R/R!!/R**)

Change implementation without changing program behavior.

Code	Known Approaches
r	Provable refactoring OR test-supported procedural refactoring within test code
R	Test-supported procedural refactoring
R!!	Named refactoring, but edited code without full test coverage
R**	Remodeled by editing code

Documentation (d/D/D!!/D**)

Change communicates to team members and does not impact program behavior.

Code	Known Approaches
d	Dev-visible docs, not in source file, or verified byte-identical compilation
D	Dev-impacting only, changes compilation or process
D!!	Alters an important process
D**	Trying out a process change for info gathering

Extension Intentions

Test-only (t/T/T!!/T**)

Alter automated tests without altering functionality.

Code	Known Approaches
t	Refactoring purely within test code
T	New test for existing behavior, all tests pass
T!!	New test without running full suite
T**	Incomplete test, WIP

Alternatives: Use F or B depending on what the test validates. Use R for refactoring within test code.

Environment (e/E/E!!/E**)

Non-code changes that affect development setup and tooling.

Code	Known Approaches
e	Config change with no compilation impact
E	Tooling change, verified working
E!!	CI/CD change, not fully tested
E**	Experimenting with build config

Unknown (WIP)

Multiple unrelated changes, just getting it checked in.

Alternative: Require each commit to have exactly one intention.

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 (!!, **) 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

Provable Refactorings

A series of all-lowercase commits can be deployed without regression testing or lengthy PR discussions.

Methods of proof:

• Automated refactoring via tool (knowing tool bugs)
• Scripted manual refactoring, using the compiler to verify each step
• Very highly tested code, with tests providing proof

Small Features and Bug Fixes

Features and bugfixes ≤8 LoC are lower risk because:

1. Only possible when code is well-organized
2. Easy to see possible side effects
3. Easy to code review

Approach: Refactor until the change is easy, then add the feature one piece at a time with tests.

Examples

r Extract calculateTotal method

PROJ-1234

F: Add user authentication

PROJ-2345

B!! Fix null pointer in user service

PROJ-3456

D: Update API documentation

PROJ-4567

Retired Intentions

The following intentions appear in older commits but are no longer used. They were absorbed into existing intentions:

Code	Name	Was	Now use
A	Automated	Tool-assisted changes (IDE renames, formatters, linters)	R
C	Comment	Comment-only changes (not JSDoc/JavaDoc)	D
S	Spec	Formal specifications and design docs	D

References

• Arlo's Commit Notation — the original system by Arlo Belshee
• Conventional Commits — a related (but different) convention
• Extensions (T, E) added by Quatico