Version: v0.2.1
Semantic Commit Notation (SCN) defines a compact visual language for versioning meaning-level changes in text-based projects such as; manifestos, specifications, charters, or any document whose content evolves through iteration.
Where Arlo’s Commit Notation describes code changes by behavioral risk, Semantic Commit Notation classifies document changes by editorial magnitude, i.e. how much the meaning or structure of a text was transformed.
Each commit expresses a single semantic event, a meaningful, coherent change to the text.
A commit answers three questions:
- Magnitude – How much meaning changed?
- Scope – Where did it happen?
- Summary – What changed and why?
| Symbol | Meaning | Magnitude | Description | Typical Use |
|---|---|---|---|---|
. |
Cosmetic | Very Minor | Pure formatting or spacing adjustments | Fix punctuation, line breaks, or markdown |
~ |
Refinement | Minor | Adding clarity or tone improvement | Simplify sentences, improve phrasing |
! |
Revision | Moderate | A rewrite or change in meaning | Reframe argument, rewrite paragraph |
+ |
Expansion | Major | An addition or structural reorganization | Add a new section or merge principles |
^ |
Meta / Infrastructure | Meta / Tooling | Non-editorial changes | Linting, automation, repository tools |
* |
Release | Release | Coherent published version | Releasing latest changes publicly |
* v0.3.0 – Add glossary and update definitions
^ release: add changelog automation
+ glossary: introduce key terms section
! definitions: clarify "component" for consistency
~ introduction: simplify first paragraph for readability
. styleguide: fix heading capitalization
^ lint: add markdown link checker
* v0.2.0 – Rewrite ethics section for accuracy
This history shows the document maturing as meaning deepens, structure expands, and meta work quietly maintains the system.
See more symbol examples.
The first symbol of each commit conveys the magnitude of change,
turning your git log into a visual map of how the document’s meaning evolved.
| Symbol | Meaning | Suggested Color |
|---|---|---|
+ |
Major addition or restructure | 🔴 Red |
! |
Moderate rewrite | 🟠 Orange |
~ |
Minor refinement | 🟡 Yellow |
. |
Cosmetic / mechanical | 🟢 Green |
^ |
Meta / infra | 🔵 Cyan |
* |
Release milestone | ⚪ White |
Together, they reveal where meaning shifted, where it was refined, and where commits were purely mechanical or meta.
Meta commits support the project without changing its meaning. Only these
scopes are valid for the meta symbol (^):
| Scope | Description | Example |
|---|---|---|
meta |
Repository maintenance or configuration | ^ meta: update contributor guide |
infra |
Build or CI environment changes | ^ infra: adjust Makefile targets |
lint |
Validation or rule updates | ^ lint: improve markdown validator |
release |
Automation related to version bumping | ^ release: improve changelog generator |
A * commit marks a coherent, publishable semantic state. It has no scope
or intent — only a version and short descriptor.
Examples
v0.12.0 – Refine Adoption clarity and update FAQ
v0.11.3 – Clarify Evaluation and restructure README
v0.10.1 – Initial version
Each release acts as a chapter heading in the document’s history. A reproducible point of meaning.
Arlo’s Commit Notation introduced the concept of describing code changes by behavioral risk instead of file lists or conventional verbs.
Semantic Commit Notation extends that spirit to textual meaning, capturing editorial magnitude rather than behavioral change.
Inspired by Arlo Belshee’s Commit Notation.
Install the helper scripts from /tools:
git scn— shows a symbol-first, colorized commit loggit heat— groups commits by magnitude into a semantic heatmap
These scripts make history instantly scannable for patterns of meaning evolution.
© 2025 Brandon Toone. This specification is licensed under CC BY 4.0.