docs(core): expand git conventions and add commit message template
## Why The existing git.md was thin — missing atomicity, working-state, and trailer guidance that belong in any professional git workflow. No commit message template existed, making the expected format implicit and inconsistent across sessions. ## Impact - git.md is now the canonical reference for commit hygiene rules - commits.md provides a structured template (Why / Implementation Notes / Impact / Git Trailers) that agents and humans can follow - AGENTS.md cross-references commits.md so it is discoverable at session start Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
79
core/instructions/commits.md
Normal file
79
core/instructions/commits.md
Normal file
@@ -0,0 +1,79 @@
|
||||
```markdown
|
||||
# <type>(<scope>): <concise summary>
|
||||
# Required.
|
||||
#
|
||||
# Purpose:
|
||||
# - Quickly communicates the intent when scanning `git log`.
|
||||
# - Follow Conventional Commits for consistency and tooling.
|
||||
# - Describe the intended outcome, not the implementation.
|
||||
#
|
||||
# Examples:
|
||||
# feat(auth): support OAuth device flow
|
||||
# fix(cache): prevent stale session reuse
|
||||
# refactor(api): simplify request validation
|
||||
|
||||
## Why
|
||||
<!--
|
||||
Explain why this change exists.
|
||||
|
||||
This is the most valuable part of the commit because the code diff
|
||||
already shows WHAT changed. Future maintainers (human or AI) often
|
||||
need to understand WHY the change was made.
|
||||
|
||||
Include, where applicable:
|
||||
- Problem being solved
|
||||
- User or business need
|
||||
- Bug or root cause
|
||||
- Important context that is not visible in the code
|
||||
|
||||
Omit if the reason is immediately obvious.
|
||||
-->
|
||||
|
||||
## Implementation Notes
|
||||
<!--
|
||||
Capture decisions that are difficult to infer from the code.
|
||||
|
||||
Useful information includes:
|
||||
- Why this approach was chosen
|
||||
- Important assumptions or invariants
|
||||
- Constraints imposed by external systems
|
||||
- Tradeoffs or intentional compromises
|
||||
- Non-obvious implementation details
|
||||
- Workarounds or temporary solutions
|
||||
|
||||
Do NOT describe the diff ("renamed X", "added Y", etc.).
|
||||
The code already documents that.
|
||||
Omit if there is nothing worth preserving.
|
||||
-->
|
||||
|
||||
## Impact
|
||||
<!--
|
||||
Document effects that future developers should know.
|
||||
|
||||
Examples:
|
||||
- Behavior changes
|
||||
- Breaking changes
|
||||
- Performance implications
|
||||
- Security considerations
|
||||
- Migration or deployment requirements
|
||||
- Compatibility concerns
|
||||
- Follow-up work or known limitations
|
||||
|
||||
Omit if there are no noteworthy impacts.
|
||||
-->
|
||||
|
||||
---
|
||||
# References (Git Trailers)
|
||||
# Structured metadata for traceability and tooling.
|
||||
# Use only the trailers that apply.
|
||||
|
||||
Fixes:
|
||||
Refs:
|
||||
ADR:
|
||||
RFC:
|
||||
Design:
|
||||
Co-authored-by:
|
||||
Reviewed-by:
|
||||
Signed-off-by:
|
||||
BREAKING CHANGE:
|
||||
```
|
||||
@@ -1,10 +1,13 @@
|
||||
# Git conventions
|
||||
|
||||
- Never skip hooks with `--no-verify`. Hooks are the automated QA gate; bypassing them breaks the pipeline.
|
||||
- Never force-push main or master.
|
||||
- Commit messages explain why, not what. Written for both humans and changelog generators.
|
||||
- Never force-push `main` or `master`.
|
||||
- Keep commits atomic. Each commit should represent one logical, independently reviewable and reversible change.
|
||||
- Ensure every commit leaves the repository in a working state (buildable/testable where practical).
|
||||
- Commit messages explain **why**, not **what**. The diff already documents what changed.
|
||||
- Never commit secrets, credentials, or environment-specific config.
|
||||
- Use conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`
|
||||
- Use Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`, etc.).
|
||||
- Reference related issues, ADRs or design documents using Git trailers when applicable.
|
||||
|
||||
## Submodules
|
||||
|
||||
|
||||
Reference in New Issue
Block a user