<service>: <change-type> | <module/domain>: <summary>
<body (optional)>
Example:
auth: secure | jwt: rotate signing keys
Add rotation strategy for refresh tokens
Automatically rotates every 7 days
- Service must be one word (e.g.,
authnotauth-service) - Change Type must be one word (e.g.,
addnotadd-feature) - Module/Domain must be one word (e.g.,
jwtnotjwt-handler)
If none of the predefined change-types fit your change, add one meaningful word:
payment: reconcile | ledger: sync failed transactions
inventory: recount | stock: manual inventory audit
order: cancel | fulfillment: handle customer request
For project-level files like env,ci/cdm,.. (not specific to any service), use root
If the first line isn't enough, add more details:
- Why this change was necessary
- What problem it solves
- Side effects or important notes
The exact name of the microservice:
auth- Authenticationpayment- Payment Processingnotification- Notificationsgateway- API Gatewayinventory- Inventory Managementorder- Order Management
For project-level files (not specific to any service), use root:
root- Project-level configuration, infrastructure, or setup files- Docker Compose, .gitignore, .env files
- CI/CD pipelines, Makefiles, scripts
- Project-wide documentation
| Type | Usage |
|---|---|
add |
Adding new feature, endpoint, or file |
update |
Regular changes, updating part of behavior |
refactor |
Changing internal structure without changing external behavior |
remove |
Removing code, feature, file, or endpoint |
| Type | Usage |
|---|---|
fix |
Bug fix |
improve |
Improving quality or readability |
optimize |
Optimizing speed and performance |
stabilize |
Increasing reliability, preventing crashes |
| Type | Usage |
|---|---|
infra |
Infrastructure changes (Docker, K8s, CI/CD) |
config |
Configuration, environment, or secrets changes |
migration |
Database schema or migration changes |
deps |
Adding/removing/updating dependencies |
| Type | Usage |
|---|---|
secure |
Security patches, hardening |
audit |
Security logging, audit trail |
| Type | Usage |
|---|---|
contract |
API contract, DTO, or schema changes |
event |
Event, topic, or pub/sub changes |
integration |
Integration with external or internal services |
| Type | Usage |
|---|---|
docs |
Documentation changes |
test |
Adding or updating tests |
tooling |
Linters, formatters, git hooks, dev tools |
The important part that changed. This can be:
- Technical layers:
jwt,cache,queue,repository - External services:
stripe,twilio,sendgrid - Business entities:
stock,invoice,order,user - Architecture components:
api,worker,scheduler,webhook - Project-level components (when using
root):docker-compose,env,gitignore,makefile,ci-cd
Examples:
auth: update | jwt: rotate access token lifetime→ JWT changedpayment: add | stripe: refund endpoint→ Stripe integration changedinventory: fix | stock: incorrect reservation logic→ Stock logic changedorder: refactor | repository: split query methods→ Repository pattern changednotification: optimize | sms: reduce provider latency→ SMS provider changedroot: infra | docker-compose: add services configuration→ Docker Compose addedroot: config | env: add environment variables template→ .env template addedroot: config | gitignore: exclude build artifacts→ .gitignore added
Clear, concise, no extra explanation, simple language.
The first line of the commit must be 100% sufficient.
A team lead reading only the first line should understand:
- ✅ Which service
- ✅ What type of change
- ✅ Which component
- ✅ What nature of change
See Example.md for complete examples with body content.