Skip to content

commits.md

Latest commit

 

History

History
178 lines (130 loc) · 5.12 KB

commits.md

File metadata and controls

178 lines (130 loc) · 5.12 KB
Raw

Commit Recipe

Standards metadata

  • ID: reference.recipes.commits
  • Role: reference
  • Level: REFERENCE
  • Applies when: A contributor needs examples for staging or formatting a commit.
  • Does not apply when: Commit process or history authority is being decided.
  • Requires: workflow.commit
  • Specializes: none
  • Verification: Commit consolidation dispositions and link checks.
  • Canonical owner: reference/recipes/commits.md

This recipe illustrates the Commit Workflow. It does not grant history-rewrite authority or override project-specific commit types, scopes, footers, or line-length conventions.

Conventional Shape

<type>(<scope>): <imperative description>

[optional rationale and material contract effects]

[optional footer(s)]

Common types include:

Type Typical use
feat New externally observable capability
fix Correctness defect
refactor Structure change without intended behavior change
test Test-only change
docs Documentation-only change
perf Measured performance improvement
build Build system or dependency mechanism
ci Automation pipeline
chore Maintenance not represented by a more precise type

Use project-defined types when they differ. A scope names the affected owned area and is omitted when no accurate scope exists.

Subject And Body

Prefer a specific imperative subject:

fix(session): rotate identifier after authentication
docs(router): add contract evolution route
test(parser): cover truncated frame diagnostic

Use the body for rationale, constraints, and material tradeoffs:

fix(session): rotate identifier after authentication

Preserving the anonymous identifier allowed session fixation. Generate a new
identifier only after credentials are accepted and invalidate the prior one.

Keep verification commands and tool output in the plan ledger, pull request, or completion record.

Footers

Use repository-supported footers when applicable:

BREAKING CHANGE: The response envelope now requires a version field.
Fixes #234
Co-authored-by: Name <name@example.com>
Agent: bounded-slice-agent

Do not invent a footer that downstream tooling does not understand.

Staging Commands

Inspect and stage the declared write set:

git status --short
git add path/to/source path/to/focused-test
git diff --cached --check
git diff --cached

Interactive staging can separate independent hunks:

git add -p

Broad staging commands are appropriate only when the complete resulting index is reviewed and exactly matches the declared write set.

Branch Review Commands

After the project resolves an explicit intended base, read-only commands can inspect the branch:

git log --graph --oneline --decorate <base-ref>..HEAD
git diff --stat <base-ref>...HEAD

These commands report history. They do not authorize amend, reset, rebase, squash, or commit dropping.

Before an authorized worktree cleanup removes a registration that may be a detached head's only root, record the exact OID and verify its selected retained or recovery ref. This repository provides a reference verifier for an explicit four-column oid, commit_disposition, reference, and authority TSV:

python3 tools/verify_git_reachability.py \
  --repository . \
  --manifest path/to/protected-oids.tsv

Use retained when the OID must be an ancestor of the named full ref, archived when the ref must resolve to that exact OID, and discard-authorized only with an exact authority record and no ref. Run the same manifest after mutation. git fsck --no-dangling checks object integrity; it is not a substitute for this reachability comparison.

Integration Examples

After the Commit workflow selects a mechanism and the project names the target, read-only checks can confirm whether complete-branch fast-forward is possible:

git merge-base --is-ancestor <target-ref> <proposal-ref>
git log --oneline <target-ref>..<proposal-ref>

When the accepted complete proposal descends from current target authority, the integration owner can use the project-authorized equivalent of:

git merge --ff-only <proposal-ref>

If a complete private branch requires fresh admission and authorized rebase, reverify it after conflicts are resolved before fast-forwarding. Preserve a merge commit only when topology has durable value. Use cherry-pick only for an accepted selective change, backport, or recovery, and record the source and accepted replacement commits. These examples illustrate selected mechanisms; they do not authorize rewriting or cleanup.

Example Messages

feat(search): add typo-tolerant matching

Rank matches within the accepted edit-distance limit while preserving exact
matches first.

fix(api): serialize concurrent state updates

Move mutation behind the canonical state owner so simultaneous requests cannot
publish conflicting revisions.

Fixes #127

refactor(date): centralize display formatting

Replace five equivalent formatters with the existing locale-aware owner. No
observable format changes are intended.