Skip to content

commit-style.md

Latest commit

 

History

History
110 lines (79 loc) · 4.12 KB

commit-style.md

File metadata and controls

110 lines (79 loc) · 4.12 KB
Raw

Commit Style

Relavium uses Conventional Commits. Commits are part of the durable, auditable record (the same value the git-native workflows principle places on the YAML files), so a commit message explains what changed and why, scoped to the package it touched.

Format

<type>(<scope>): <summary>

<body — what and why, wrapped ~72 cols>

Refs: ADR-XXXX

Co-Authored-By: Claude <noreply@anthropic.com>
  • The summary is imperative mood, lower-case, no trailing period, ≤ ~72 chars ("add fallback-chain runner", not "Added the fallback chain runner.").
  • The body is optional for trivial changes, expected for anything non-obvious; it explains the reasoning, not a restatement of the diff.

Types

feat, fix, refactor, perf, test, docs, chore, build, ci. A breaking change appends ! after the scope (feat(core)!: …) and explains the break in the body under a BREAKING CHANGE: line.

Scope per package

The scope is the package or app the change lives in, using the short workspace name (see project-structure.md):

llm, core, shared, db, mcp, ui, cli, desktop, vscode, api, portal, docs, repo (root tooling / config).

  • One scope per commit; a change spanning packages is usually two commits. If genuinely atomic, pick the primary scope and name the rest in the body.
  • Adapter-level work names the layer in the summary, not a vendor scope (feat(llm): add anthropic streaming adapter).

Reference ADRs

When a commit implements or changes a decision, reference the ADR so history links back to the reasoning:

  • Refs: ADR-0011 in a trailer (or inline in the body) for the decision a change implements.
  • A commit that supersedes a decision says so and names the new ADR; it never silently contradicts an Accepted ADR (that needs an ADR, per architectural-principles.md).

Co-Authored-By trailer

This is the canonical home for the AI co-author trailer; the skills (standards-check, commit-and-pr) cite this rule rather than redefine it. A commit produced with AI assistance ends with a Co-Authored-By trailer on the last line:

Co-Authored-By: Claude <noreply@anthropic.com>

Use the actual assisting tool: Claude <noreply@anthropic.com> or Codex <noreply@openai.com>. A model-versioned name may follow the same tool prefix and corresponding email. Never claim Claude authored a Codex-assisted change (or the reverse). Conformance checks accept either truthful family: Co-Authored-By: (Claude.*<noreply@anthropic.com>|Codex.*<noreply@openai.com>). Other assisting tools need an explicit documented identity rather than a forged existing trailer. This applies to new commits; published historical subjects and trailers are not rewritten.

Examples

feat(llm): add OpenAI-compatible adapter shared by openai + deepseek

Single adapter over the OpenAI Chat Completions wire format; DeepSeek
selected via custom baseURL. No vendor type crosses the @relavium/llm
seam. Streaming tool-arg fragments are reassembled at tool_call_end.

Refs: ADR-0011

fix(core): classify provider 429 as retryable in fallback runner

A rate limit before content commits now advances to the next provider
instead of failing the run. Each attempt is reported; usage is recorded
only when supplied, without turning an estimate into actual spend.

Refs: ADR-0011

docs(docs): index the seven new engineering standards

Rules

  • Don't bundle unrelated changes; don't commit generated/formatting churn with logic.
  • Commit messages are English, like all docs.
  • Use the canonical event/term vocabulary in messages too (cost:updated, sequenceNumber), never the legacy dotted names.