Commit message specification

Commit format for docs-portal, aligned with LibESys repository policy (adapted from esysdox-ops and superbuild-workflow). 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	Docusaurus build config, site packaging, deploy prep
chore	Repo hygiene, hooks, dependency bumps
ci	GitLab CI or publish automation
docs	Portal or common documentation
feat	New workflow section, sync tooling, site capability
fix	Corrections to portal config, sync, or published docs
perf	Build or site performance (rare)
refactor	Restructure without semantic change
revert	Revert a prior commit
style	Formatting only
test	Tests only (rare in this repo)

Recommended scopes

portal, docusaurus, sync, superbuild, common, hooks, ci, repo

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

Subject style

• Imperative mood: Bootstrap docs portal, not Bootstrapped…
• Start with uppercase after :
• No trailing period

Examples:

feat: Bootstrap ai workflows docs portal
docs(portal): Document sync and publishing model
feat(superbuild): Sync workflow docs and extend sidebar
chore(hooks): Add pre-commit and gitlint for commit messages
ci: Add GitLab Pages build job

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

./scripts/setup-dev.sh
# Windows:
# .\scripts\setup-dev.ps1

Or manually:

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

See Development workflow and Commit checklist.