Commit message specification

Commit format for superbuild-workflow, aligned with LibesSys repository policy (adapted from esysdox-ops). Enforced locally via gitlint and pre-commit (commit-msg hook).

Goals

• Readable history (git log --oneline)
• Consistent intent via type and optional scope
• Explicit AI assistance and breaking changes
• Block policy-breaking messages before they land on protected branches

Message structure

<title line>

<optional body>

<optional footers>

• Blank line between title and body
• Blank line between body and footers
• Title ≤ 72 characters
• Body/footer lines ≤ 100 characters

Title line

[WIP: ]<type>[<scope>][!]: <subject>

Allowed types

Type	Use for
build	Build or toolchain policy docs (CMake/Conan workflow)
chore	Repo hygiene, hooks, submodule pointers
ci	GitLab CI or automation
docs	Documentation and templates
feat	New policy, templates, or workflow capability
fix	Corrections to policy, adapters, or docs
perf	Performance-related policy (rare)
refactor	Restructure without semantic policy change
revert	Revert a prior commit
style	Formatting only
test	Tests only (rare in this repo)

Recommended scopes

docs, cursor, templates, repo, migration, governance, hooks

Rules: lowercase; characters a-z, 0-9, ., _, /, -.

Subject style

• Imperative mood: Add migration checklist, not Added…
• Start with uppercase after :
• No trailing period

Examples:

feat(migration): Add legacy superbuild migration specification
docs: Record confirmed migration decisions (Conan 2, macOS)
fix(cursor): Align repo-layout adapter with repository-layout doc
chore(hooks): Add pre-commit and gitlint for commit messages

Footers

AI: (optional)

Value	Meaning
yes	AI-assisted
no	No AI assistance
perplexity	Primarily Perplexity
copilot	Primarily GitHub Copilot
mixed	Multiple tools or substantial human edit

At most one AI: footer per commit.

BREAKING CHANGE:

Required when the title includes ! after type/scope.

Co-authored-by:

Standard Git trailer when appropriate.

WIP commits

WIP: prefix allowed on topic branches only — not on develop, master, main, release/*, or hotfix/*.

Git author

Commits must list the human operator as author, even when Cursor or other AI helped. Record AI help via AI: footer and/or Co-authored-by: Cursor <cursoragent@cursor.com>. Do not use a bot address as sole Author:.

Validation

Rule	Value
Title max length	72
Body line max length	100
Title regex	See .gitlint
AI: values	yes, no, perplexity, copilot, mixed
WIP: on protected branches	Forbidden

Setup

pip install pre-commit
pre-commit install
pre-commit install --hook-type commit-msg

See development-workflow.md and commit-checklist.md.