git-commit-message

name

git-commit-message

description

Writing conventions for Git commit messages in slf4j-toys — content only, not staging or pushing. Use whenever composing a commit message: the Conventional Commits header format (type(scope): summary), body structure, commit types and scopes, test-coverage mention, and AI attribution trailer. For staging/push/force-push mechanics and when to commit, see `trunk-based-development`; for passing a multi-line message through PowerShell, see `powershell`.

Git Commit Message Guidelines for slf4j-toys

This skill covers only the content of a commit message — not how to stage, commit, or push (see trunk-based-development) and not PowerShell string mechanics for passing a multi-line -m argument (see powershell). A well-structured commit message lets someone reconstruct why a change was made from git log alone, without re-reading the diff.

Format

Commit messages must follow Conventional Commits:

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

<detailed body explaining what changed and why>

<test coverage information>

Co-Authored-By: <Assistant Name> <Model> <contact address>

• Header — <type>(<scope>): <summary>, summary in imperative mood ("implement", not "implemented"). Keep it a single scannable line; there's no strict character cap enforced in this project (type(scope): prefixes routinely push real headers here past 70 characters), but tighten the wording if you're running long without adding meaning. See Types and Scopes below.
• Body — a high-level paragraph of what changed and why, then a Changes: bullet list of technical changes. Group related changes, include quantitative detail ("86 test cases", "4 tests updated"), name specific classes/methods for traceability. Wrap body text at 72 characters.
• Test coverage line — state what was actually run and its result (e.g., "All 1710 Meter tests pass, confirming backward compatibility"). Don't write this from assumption — run the relevant tier from run-test first.
• Attribution — required on every AI-generated commit; see AI attribution below.
• Scope discipline — one concern per commit. Split unrelated changes into separate commits rather than bundling them.

Commit Types

Type	When to use
feat	New functionality, capability, or API
fix	Fixing a defect or incorrect behavior
refactor	Restructuring code without changing behavior
perf	Optimizing performance or resource usage
test	Adding/updating tests, no production code change
docs	Documentation, comments, README
style	Formatting/whitespace, no logic change
chore	Build scripts, dependencies, tooling
ci	GitHub Actions, build pipelines, automation
revert	Undoing a previous commit

Scopes

Common scopes in this project: meter, watcher, reporter, logger, test, build, ci.

AI attribution

Name the actual assistant and model that generated the commit in the trailer shown in Format above — not a fixed placeholder tool name. For Claude Code, that's the harness default: Co-Authored-By: Claude Sonnet 5 <[e-mail]>. If the commit is generated by GitHub Copilot specifically, follow .github/copilot-instructions.md's override instead (Co-authored-by: GitHub Copilot using <model name>). Apply the same convention consistently to any PR description opened for this commit (see git-pull-request).

Complete example

feat(meter): implement idempotent termination behavior

Meter termination methods (ok, reject, fail) now properly handle repeated
termination attempts by preserving the first termination state.

Changes:
- MeterValidator.validateStopPrecondition() now returns boolean instead of void
  - Returns false when meter already stopped (blocks re-termination)
  - Returns true otherwise (allows termination with warnings)
- Meter.commonOk(), reject(), fail() methods now check validation result
  - Early return when meter already stopped, preserving first termination
- Updated 86 test cases to verify idempotent behavior
  - MeterValidatorTest: 4 tests updated to capture boolean return
  - MeterLogBugTest: 6 tests updated for exception handling

All 1710 Meter tests pass, confirming backward compatibility.

Co-Authored-By: Claude Sonnet 5 <[e-mail]>

Related Documentation

• git-pull-request skill — PR title/description conventions for the same change
• trunk-based-development skill — staging, pushing, force-push rules, and when to commit
• powershell skill — passing multi-line commit messages through PowerShell
• Conventional Commits Specification
• AGENTS.md — project AI agent guidelines
• .github/copilot-instructions.md — AI attribution standards