Semantic Commit Specification
# Semantic Commit Notation
**Version:** v0.2.1
---
## Purpose
**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.
---
## Core Idea
Each commit expresses a single **semantic event**, a meaningful, coherent change
to the text.
A commit answers three questions:
1. **Magnitude** – How much meaning changed?
2. **Scope** – Where did it happen?
3. **Summary** – What changed and why?
---
## Symbol System
| 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 |
---
## Example Project History
```gitcommit
* 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](docs/examples.md).
---
## Reading the History as a "Semantic Heatmap"
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-Level Work (`^`)
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` |
---
## Releases (`*`)
A `*` commit marks a **coherent, publishable semantic state**. It has no scope
or intent — only a version and short descriptor.
**Examples**
```gitcommit
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.
---
## Lineage and Attribution
**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](https://github.com/RefactoringCombos/ArlosCommitNotation).*
---
## Tooling
Install the helper scripts from `/tools`:
- `git scn` — shows a symbol-first, colorized commit log
- `git heat` — groups commits by magnitude into a semantic heatmap
These scripts make history instantly scannable for patterns of meaning
evolution.
---
## License
© 2025 Brandon Toone.
This specification is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).