I write commit messages using a structured, domain‑driven commit style designed for clarity, traceability, and long‑term maintainability. My commit messages should use plain language, be concise, expressive, and easy to skim.
Note
Commit bodies summarize conceptual changes. Bullets clarify the summary, with context, without clutter. Bullets distill. They don't list every detail.
- Summary
A good commit message:
- starts with a clear, imperative header
- uses plain, easy-to-understand language
- uses semantic bullets to describe what changed
- orders bullets by importance
- groups related changes
- uses sub‑items when helpful
- wraps file names and code objects in backticks (ex:
`someObjectName`) - uses domain vocabulary
- documents invariants when relevant
The goal is to keep the commit history clean, expressive, and easy to follow.
Note
Markdown Formatting Commit messages use Markdown formatting. They should be easy to read in plain text or rendered Markdown. They use semantics and syntax (2.1 and 2.7) that still render in Markdown.
All commit text: headers, bullets, and sub‑items, should be written in clear, intention‑revealing plain language. Avoid noise, meaningless jargon, and unnecessary ceremony. Write for future maintainers.
Summary Lines may include prefixes that encode additional information.
Prefixes are separated with a -
[link] - [status] - [summary]
When working in environments with issue tracking, Commit summaries will often begin with the link text.
Status prefixes indicate when work is incomplete, or when the commit represents work in a non-standard state.
- WIP - Work in Progress - a commit with untested or in progress changes.
- Bullets
The bullet system is the core of this project’s commit‑message DSL.
Bullets communicate the type, importance, and structure of the change.
They make commits skimmable, predictable, and easy to reason about months or years later.
Bullets are a core component of this DSL, but they are still optional. Bullets that repeat information without contributing clarity should be omitted.
The following subsections define:
- how bullets work,
- how they should be used,
- how they should be ordered,
- and how they should be grouped.
Commit bodies use a semantic bullet system:
+Added*Changed / Updated / Improved - Note: Can be used to clarify, or highlight, when something hasn't changed.-Removed
Bullets are indented by two spaces for clean Markdown rendering.
Example:
+ added isDefault to permissions checks, added tests
* UI disables for default box now, w/ tests
- remove JSON stringify/parse
Use past‑tense or neutral phrasing in bullets.
As stated in rule 1.1, each Bullet Text entry should be written in plain language.
Bullet text for semantic bullets with meaning + and -
must clearly state that meaning in the text.
+bullets must use additive language.-bullets must use subtractive language.
If the change cannot be written as an addition or removal using natural language,
then a * bullet must be used instead.
Bullets should be ordered by importance and impact:
- Production‑meaningful changes
(logic, behavior, domain rules, UI behavior, sagas, reducers, etc.) - Test changes
(new tests, updated tests, reorganized tests) - Documentation changes
(comments, inline docs, README updates) - Formatting or incidental changes
(spacing, reorganizing imports, renames that don’t affect behavior)
This ordering keeps the most important information at the top and makes commits easier to skim.
Group bullets by conceptual area to keep commits readable.
Typical groups include:
- Domain logic
- UI changes
- Permission rules
- Tests
- Documentation
- Miscellaneous cleanup
Example:
* Create/Update forces WRITE access for Owner
* boxListSaga checks for Owned when getting boxList
+ add tests for boxRules permissions helpers
+ add tests for roles has*Access helpers
Use sub‑items when a single bullet covers multiple related changes, especially when referencing multiple files or multiple steps in a refactor.
Example:
* VariantOverrides for enqueueSnackBar finally work
* -> *.d.ts
* switched to a `type` from AlertBarTypes
Sub‑items should be indented consistently for readability.
These conventions support clarity, brevity, and intention‑revealing commit messages.
They apply across all commit text, including bullets.
Mention file names only when they clarify the change.
Wrap file names and code objects (functions, classes, helpers, constants, etc.) in backticks:
* cleanup `verifyDateField` helper
* `DocumentDetails.tsx` reorganized
* `verifyDateField.ts` simplified
This improves clarity without cluttering the commit.
Use the project’s domain language consistently:
- box, user box, default box, personal box
- collection, child collection, item
- permissions, roles, access levels
- saga, test table, helpers
AlertBar,AlertView,BoxMembersList,BoxForm
Commit messages double as domain documentation.
Use arrows to show renames or conceptual transitions:
* AlertMessage (data) -> Alert
* AlertMessage (component) -> AlertView
This format is compact and unambiguous.
When a commit reinforces or proves a domain rule, state the rule explicitly in the header or bullets.
Examples:
* Only 1 USER box per user.
* Collection updates preserve contained item[]
* Create/Update forces WRITE access for Owner
This makes the commit history a reliable reference for domain behavior.
These rules constrain how AI should interpret and generate commit messages.
They preserve the DSL’s clarity, scope, and conceptual focus.
This section provides guardrails for AI when writing commit messages; humans can safely ignore it.
- The summary expresses the conceptual change.
- Bullets support the summary; they do not replace it.
- Bullets must be distilled, not detailed.
- Bullets must not include implementation specifics.
- Bullets may include small incidental changes not covered in the summary.
- Bullets must be short, conceptual, and non‑verbose.
- Bullets must be under 80 characters long.
- Bullets may wrap visually, but continuation lines must be aligned with the bullet text. When wrapping lines, break at natural phrase boundaries for maximum readability.
- Merge tightly coupled changes into single bullets with sub-items (e.g., adding shared utility, updating consumers, removing duplicates).
- Omit incidental changes that don't contribute to understanding the commit's purpose.