| name | conventional-commits |
| description | Guide for writing conventional commit messages. Use when committing changes, writing commit messages, or reviewing commit history. |
| license | BSD-3-Clause |
| metadata | {"author":"axone.xyz","version":"1.0"} |
Conventional Commits
Commit Message Format
<type>(<scope>): <verb> <subject>
One line only. No body. No footer (except for breaking changes).
Subject Line Rules
- Imperative mood, present tense
- Short, dense, unambiguous
- Describes the intent, not the implementation
- One line only
- No capitalization at start
- No period at end
Verb Selection
⚠️ Avoid weak verbs: add, remove, change, update, modify
Use precise, action-oriented verbs:
| Verb | Use When |
|---|
enforce | Adding constraints or rules |
introduce | Bringing in new concepts/APIs |
implement | Building out functionality |
prevent | Blocking undesired behavior |
fix | Correcting bugs |
refactor | Restructuring without behavior change |
clarify | Improving readability/naming |
align | Making consistent with standards |
tighten | Strengthening validation/constraints |
harden | Security or robustness improvements |
validate | Input/state verification |
handle | Managing edge cases |
support | Enabling new use cases |
ensure | Guaranteeing invariants |
document | Documentation work |
Type
| Type | Description | Triggers |
|---|
feat | New feature | Minor version bump |
fix | Bug fix | Patch version bump |
docs | Documentation only | No release |
style | Formatting, whitespace | No release |
refactor | Code restructuring | No release |
perf | Performance improvement | Patch version bump |
test | Adding/updating tests | No release |
build | Build system, dependencies | No release |
ci | CI/CD configuration | No release |
chore | Maintenance tasks | No release |
Scope
- Mandatory when it adds clarity
- Short, meaningful, domain or component oriented
- Use contract names without
axone- prefix: gov, logic
- Other examples:
workflow, dependabot, README, make, deps
- If unsure, omit it
Examples
See examples for comprehensive good and bad examples.
Quick reference:
feat(gov): introduce quadratic voting mechanism
fix(handlers): prevent overflow in vote counting
refactor(state): clarify storage key naming
test(gov): validate error paths for unauthorized access
build(deps): enforce abstract-sdk 0.26.1
Granularity
Rule: One commit = one intention
| Instead of... | Prefer... |
|---|
| One big mixed commit | Multiple focused commits |
feat: implement X and fix Y | Two separate commits |
| Tests bundled with feature | Separate test: commit |
| Build changes with feature | Separate build: commit |
What to Avoid
- ❌ Generic messages hiding what changed
- ❌ Explanations or rationale in the message
- ❌ Marketing language or inflated wording
- ❌ Multiple intentions in one commit
- ❌ Vague subjects like "improve", "update", "fix issue"
Breaking Changes
Use ! after type/scope:
feat(msg)!: restructure ExecuteMsg variants
refactor(api)!: enforce stricter validation schema
Commit Linting
Commits are validated using commitlint. Ensuring lint passes is mandatory.
Validate locally:
npm i -g @commitlint/cli @commitlint/config-conventional
echo "feat(gov): introduce voting mechanism" | commitlint --extends @commitlint/config-conventional
