Conventional Commits
Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. It provides an easy set of rules for creating an explicit commit history, making it easier to write automated tools on top of.
What are Conventional Commits?
Format Structure
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Basic Examples
bash
# Simple feature addition
feat: add user authentication
# Bug fix with scope
fix(auth): resolve login redirect issue
# Breaking change
feat!: change API response format
# With body and footer
feat(api): add user profile endpoint
Implement GET /api/users/:id endpoint to retrieve user profile information.
Includes validation for user ID and proper error handling.
Closes #123
Commit Types
Primary Types
| Type | Description | Example |
|---|---|---|
feat | New feature | feat: add shopping cart |
fix | Bug fix | fix: resolve payment processing error |
docs | Documentation | docs: update API documentation |
style | Code style changes | style: fix indentation in components |
refactor | Code refactoring | refactor: extract validation logic |
test | Adding/updating tests | test: add unit tests for calculator |
chore | Maintenance tasks | chore: update dependencies |
Additional Types
| Type | Description | Example |
|---|---|---|
perf | Performance improvements | perf: optimize database queries |
ci | CI/CD changes | ci: add automated testing workflow |
build | Build system changes | build: update webpack configuration |
revert | Revert previous commit | revert: undo feature X implementation |
Practical Examples
Setting Up a Project
bash
# Create example project
mkdir conventional-commits-demo
cd conventional-commits-demo
git init
# Initial commit
echo "# Conventional Commits Demo" > README.md
git add README.md
git commit -m "chore: initial project setup"
# Add package.json
cat > package.json << EOF
{
"name": "conventional-commits-demo",
"version": "1.0.0",
"description": "Demo project for conventional commits",
"main": "index.js",
"scripts": {
"start": "node index.js",
"test": "node test.js",
"lint": "eslint ."
},
"keywords": ["demo", "conventional-commits"],
"author": "Your Name",
"license": "MIT"
}
EOF
git add package.json
git commit -m "feat: add package.json with project configuration"
Feature Development Examples
bash
# Add main application file
cat > index.js << EOF
const express = require('express');
const app = express();
const port = process.env.PORT || 3000;
app.get('/', (req, res) => {
res.json({ message: 'Hello, World!' });
});
app.listen(port, () => {
console.log(`Server running on port ${port}`);
});
module.exports = app;
EOF
git add index.js
git commit -m "feat(server): add basic Express.js server
Implement basic HTTP server with Express.js framework.
Includes health check endpoint and configurable port.
Closes #1"
# Add user routes
mkdir routes
cat > routes/users.js << EOF
const express = require('express');
const router = express.Router();
// Mock user data
const users = [
{ id: 1, name: 'John Doe', email: 'john@example.com' },
{ id: 2, name: 'Jane Smith', email: 'jane@example.com' }
];
// GET /users
router.get('/', (req, res) => {
res.json(users);
});
// GET /users/:id
router.get('/:id', (req, res) => {
const user = users.find(u => u.id === parseInt(req.params.id));
if (!user) {
return res.status(404).json({ error: 'User not found' });
}
res.json(user);
});
module.exports = router;
EOF
git add routes/
git commit -m "feat(api): add user management endpoints
Implement REST API endpoints for user operations:
- GET /users - list all users
- GET /users/:id - get user by ID
Includes proper error handling for non-existent users."
# Update main server to use routes
cat > index.js << EOF
const express = require('express');
const userRoutes = require('./routes/users');
const app = express();
const port = process.env.PORT || 3000;
app.use(express.json());
app.use('/api/users', userRoutes);
app.get('/', (req, res) => {
res.json({
message: 'API Server',
version: '1.0.0',
endpoints: {
users: '/api/users'
}
});
});
app.listen(port, () => {
console.log(`Server running on port ${port}`);
});
module.exports = app;
EOF
git add index.js
git commit -m "feat(server): integrate user routes with main application
Connect user management routes to the main Express application.
Update root endpoint to provide API documentation."
Bug Fix Examples
bash
# Fix a bug in user route
cat > routes/users.js << EOF
const express = require('express');
const router = express.Router();
// Mock user data
const users = [
{ id: 1, name: 'John Doe', email: 'john@example.com' },
{ id: 2, name: 'Jane Smith', email: 'jane@example.com' }
];
// GET /users
router.get('/', (req, res) => {
res.json(users);
});
// GET /users/:id
router.get('/:id', (req, res) => {
const userId = parseInt(req.params.id);
// Fix: Add validation for invalid ID
if (isNaN(userId) || userId < 1) {
return res.status(400).json({ error: 'Invalid user ID' });
}
const user = users.find(u => u.id === userId);
if (!user) {
return res.status(404).json({ error: 'User not found' });
}
res.json(user);
});
module.exports = router;
EOF
git add routes/users.js
git commit -m "fix(api): add validation for user ID parameter
Resolve issue where invalid user IDs (non-numeric, negative)
were not properly validated, causing unexpected behavior.
Fixes #15"
Documentation Examples
bash
# Add API documentation
cat > API.md << EOF
# API Documentation
## Base URL
## Endpoints
### GET /
Returns API information and available endpoints.
### GET /api/users
Returns list of all users.
**Response:**
```json
[
{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
}
]
GET /api/users/:id
Returns specific user by ID.
Parameters:
id(number): User ID
Response:
json
{
"id": 1,
"name": "John Doe",
"email": "john@example.com"
}
Error Responses:
400: Invalid user ID404: User not found EOF
git add API.md git commit -m "docs: add comprehensive API documentation
Include endpoint descriptions, request/response examples, and error handling documentation for the user API."