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
This skill helps you write commit messages following the Conventional Commits specification, adapted to Axone protocol preferences.
When to use this skill
Use this skill when you need to:
- Write commit messages for changes
- Review or improve commit messages
- Structure commits for a pull request
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
Quick Checklist
Before committing, verify:
- [ ] Uses a strong, precise verb
- [ ] Subject describes intent clearly
- [ ] Scope is present if it adds clarity
- [ ] One intention per commit
- [ ] No generic or vague wording
- [ ] Commit message passes linting