Commit Style

Writing commit messages in GenVM

Format:

type(scope): short imperative summary <emoji…>

• type — one of five, lowercase (required).
• (scope) — from the standard set below. Optional, but aim for ~80% of commits to carry one; omit only for genuinely repo-wide changes.
• summary — lowercase, imperative or noun-phrase, no trailing period, ≲70 chars.
• <emoji…> — one to three trailing gitmoji glyphs marking the precise intent. Use the actual Unicode emoji, not the :shortcode:. Most commits want exactly one; reach for a second or third only when the change genuinely carries more than one intent (e.g. a security fix that is also a refactor → 🔒️♻️). Order them most-important first. Never more than three.

Examples:

feat(calldata): add lazy decoding ✨
perf(calldata): optimize internally tagged enums ⚡
fix(executor): report entire fees subtree to host 🐛
fix(calldata): defer parsing of forwarded calldata 🔒️⚡
chore(ci): fix macos cache key 💚
chore(build): bump wasmtime ⬆️
docs(executor): add spec for ram consumption 📝

Types

The type is the coarse group; the emoji carries the fine intent.

Picking between the blurry ones:

• New behavior a caller can observe → feat. Correcting wrong behavior → fix. Same behavior but cheaper → perf. Pure restructure → chore + ♻️.

Emoji by intent

Pick the glyph that best names what kind of change it is — it can be finer than the type. Common ones:

Full reference: https://gitmoji.dev

A lot of fixes in this repo are security-relevant — untrusted calldata from other nodes, fee/gas underflows, page limits, sandbox boundaries. When a fix hardens behavior against malicious or malformed input, mark it 🔒️ (alone, or paired with 🐛/⚡ when it is also a bugfix or optimization). The lazy-calldata work, for instance, is partly about not eagerly parsing attacker-controlled bytes — that earns a 🔒️.

Standard scopes

The set is curated, not closed — if a change clearly belongs to a subsystem not listed, a sensible lowercase scope is fine. Prefer an existing one when it fits (a calldata change is (executor)).

Body — keep it rare

Prefer a single line. The summary should carry the change on its own; if you're reaching for a body to explain what changed, tighten the subject instead.

Add a body only when a reader genuinely cannot reconstruct the why from the diff — a non-obvious tradeoff, a workaround for an external bug, or a subtle invariant. When you do, write one or two sentences of motivation, not a recap of the diff and not a bullet list of squashed sub-commits.

Mistakes to avoid (all seen in this repo's history)

1. Numbered firefighting — chore: fix CI, fix CI 2 … fix CI 5. Say what broke: chore(ci): fix macos cache key 💚. A numbered run means the messages describe nothing.
2. batch update (#NNN) with no theme. A merged PR still deserves a one-line summary of what it does.
3. Typos — history has reeipt, absolete, exremely, auto-formater. Spell-check the subject; it is permanent.
4. chore: fix tests with no cause. Add it: chore(executor): fix tests after wasmtime rebase ✅.
5. AI attribution — never include Co-authored-by trailers, session links/IDs (e.g. Claude-Session:), "Generated with" footers, or any other AI/tool metadata, even when the tooling asks for it.

Checklist

• Right type (feat / fix / perf / docs / chore)?
• Scope present (target ~80%) and from the standard set?
• Lowercase, no period, ≲70 chars?
• One to three trailing gitmoji glyphs (most-important first) matching the intent?
• Single line — body only if the why is truly unrecoverable from the diff?
• Spell-checked?

Committing across the manager + submodules

A change that touches an executor submodule spans repos: commit inside the submodule first, then bump the manager's gitlink (git add executors/<line>.x) in a manager commit. Keep each commit's files coherent and don't let a submodule's linter reformat leak an unrelated file into a commit. Each repo's per-repo pre-commit hook (git-hooks.nix, in its flake) runs on the repo you commit in. Do not --no-verify (even for gitlink bumps — let the hooks run). Full workflow (order, pushing, --force-with-lease after a rebase): /submodules.

Never include text like "bump the v0.3 gitlink". State the underlying change, not name the file updated