Commit Style

Источник: dev/fera/community/COMMIT-STYLE.md (read-only; сгенерировано scripts/sync-docs.mjs)

Commit Style

Conventions for commit messages across all repositories in the the-fera org. Machine-parseable history, human-readable reasoning.

Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Types

Type	Meaning
feat	new feature
fix	bug fix
perf	performance improvement — requires a benchmark reference
refactor	code change that neither fixes nor adds anything
docs	documentation only
test	adding or correcting tests
build	build system, CI, dependencies
chore	maintenance, tooling, repo hygiene

Scope (optional)

The module or crate the change touches: storage, ui, protocol, trust, … Use the short module names from the design corpus.

Subject

• Imperative mood: “add”, not “added” / “adds” — when applied, the commit does the thing.
• ≤ 72 characters.
• No trailing period.
• Lowercase (matching the Rust ecosystem’s convention).

Body (optional, encouraged)

The body explains why the change is needed — the diff already says what happened. What problem does this solve? What constraint does it respect? If the change implements a decision recorded in the design corpus (ADR/OQ), reference it: (ADR-020), (OQ-024).

Footers

• Refs: #123 — the issue/PR this relates to.
• Breaking-Api: / Breaking-Abi: — marks an API-edition or ABI-version bump (see the version model; the axes are independent).

Project-specific rules

1. Every behavioral change ships with a test, or a justification for its absence in the body. Runtime behavior is pinned by tests, not by review vigilance.
2. perf: commits must reference a reproducible benchmark — before/after numbers, scene name (fera-scene-v0), hardware class. No benchmark, no merge. (Falsifier-first optimization policy, OQ-024.)
3. New persisted fields require an audit-table entry (ADR-031) in the same commit — the encryption-tier assignment is part of the change, not a follow-up.
4. No second implementation of a trait merges without its contract test suite (ADR-014) — the contract tests come first.

Examples

fix(storage): drain in-flight calls before epoch flip

The old code freed the pointer table immediately on hot-swap,
dropping calls that had already resolved the table but not yet
executed. Now the flip installs the new epoch and the old one is
freed only after every actor loop reports a quiescent point.
(ADR-020 ERB addendum, OQ-024)

perf(media): pre-decode sticker frames into the mmap cache

fera-scene-v0, 50 concurrent 512x512@30fps stickers:
frame-advance p99 18ms -> 4ms warm. Ryzen 7 7840U, NVMe.

feat(protocol)!: typestate login lifecycle

Breaking-Api: login now consumes the client (move semantics),
returns ProtocolClient<Authenticated> instead of mutating in place.