Commit conventions

The existing history is the spec. git log --oneline is the best reference available; this page only names the patterns it already follows.

Shape

type(scope): what changed, specifically

The scope is optional and names the crate or area — lang, core, graph, policy, cli, prose, meta. Types in use:

Commit descriptions

This is the rule that matters. A commit should say what is now true that was not true before. Specifically, it should be enough that someone scanning the log can tell whether this commit is the one they are looking for.

Compare:

fix(graph): harden qualpath resolution. package-index dirs, keyword roots,
            drop-on-miss, no file-stem inflation

against fix(graph): fix bugs. Both are accurate, though only one of them is findable.

More from the log:

port(crypto): bind DSSE signature to exact wire payload bytes, not the trimmed form
fix(cli): exit 141 on a closed stdout pipe instead of panicking
feat(show): resolve a unit address, not just a content_id
fix(init): report only the dotfiles it actually rewrote

Each names a specific behaviour and, where it helps, the thing it replaced. The X, not Y construction does a lot of work. It tells you the old behaviour too, which is what you actually want when bisecting.

Write bodies if necessary

Skip it for anything self-evident; but write one when the change has a reason that is not visible in the diff.

ci: fail the build when the generated CLI reference is stale

docs/src/reference/cli.md is generated from the binary's own --help, so a
renamed flag or a new subcommand silently invalidates it. It had drifted
13 commits before anyone noticed.

Runs in the existing test job after the build, reusing target/debug/vidi
rather than paying the tree-sitter compile again, and only on Linux since
the page is byte-identical on every host.

The first paragraph is the reason; while the second is the choice and its justification.

Wrap bodies at 72 characters.

Version and profile rotations

A change that rotates profileVersion, SCOPE_MODEL_VERSION or a grammar pin must say so in the subject, because it restales every review under the old rules:

port(lang): vidi-scope-4 — out-of-node modifier/decorator/trait-header hashing
            (SCOPE_MODEL 3->4, goldens re-blessed)

The 3->4 and the note that goldens were re-blessed are not decoration. They are how someone reading the log later knows why every hash moved.

Next

Start contributing!