Commit Conventions

Git commit message guidelines

📋 Overview

We follow Conventional Commits specification for clear, semantic commit messages that support automated changelog generation and version management.

📝 Commit Message Format

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Components

Type: The kind of change Scope: The area of the codebase affected (optional) Subject: Short description (imperative mood) Body: Detailed explanation (optional) Footer: Breaking changes, issue references (optional)

🏷️ Types

Primary Types

Type Selection Guide

# Adding new functionality
feat: add project filtering

# Fixing a bug
fix: resolve session timeout issue

# Improving performance
perf: optimize database queries

# Refactoring without behavior change
refactor: simplify auth logic

# Documentation
docs: update API reference

# Tests
test: add project creation tests

# Dependencies, configs
chore: update dependencies

🎯 Scopes

Scopes indicate which part of the codebase is affected:

Common Scopes

# Applications
web         # Web frontend
api         # API server

# Packages
database    # @izri/database
trpc        # @izri/trpc
auth        # @izri/auth
shared      # @izri/shared

# Features
projects    # Project management
tests       # Test execution
analysis    # Repository analysis
org         # Organizations

# Infrastructure
docker      # Docker configuration
ci          # CI/CD
deps        # Dependencies

Examples with Scopes

feat(projects): add project filtering
fix(auth): resolve session timeout
docs(api): update tRPC documentation
refactor(database): optimize query performance
test(web): add component tests
chore(deps): update to React 19

✍️ Subject Guidelines

Rules

1. Use imperative mood: "add feature" not "added feature"
2. No capitalization: Start with lowercase
3. No period: Don't end with .
4. Max 72 characters: Keep it concise
5. Be descriptive: But not verbose

Good Examples

✅ feat: add project filtering
✅ fix: resolve database connection timeout
✅ refactor: simplify project query logic
✅ docs: update installation instructions

Bad Examples

❌ Added new feature          # Past tense
❌ Fix bug                   # Too vague
❌ feat: Added Project Filter # Capitalized
❌ fix: resolve the issue where the database connection was timing out frequently # Too long

📖 Body

Use the body to explain:

• What changed
• Why it changed
• How it affects behavior

Format

• Wrap at 72 characters
• Separate from subject with blank line
• Use bullet points for multiple points

Example

feat(projects): add advanced filtering

Add support for filtering projects by:
- Language (TypeScript, Python, Go)
- Framework (React, Vue, FastAPI)
- Date range

This improves user experience when managing
many projects and enables better organization.

🔗 Footer

Use footer for:

• Breaking changes: BREAKING CHANGE: description
• Issue references: Closes #123, Fixes #456
• Other metadata: Reviewed-by:, Refs:

Breaking Changes

feat(database)!: change project schema

Rename 'repo' field to 'repository' for consistency.

BREAKING CHANGE: Projects table 'repo' field renamed to 'repository'.
Update all queries to use new field name.

Issue References

fix(auth): resolve session timeout

Fixes #123
Closes #456

📋 Complete Examples

Feature Addition

feat(tests): add test execution API

Implement tRPC endpoint for running tests:
- Support unit, integration, and E2E tests
- Queue tests for async execution
- Store results in database

Closes #234

Bug Fix

fix(api): prevent duplicate project creation

Add unique constraint check before inserting
new project. Returns existing project if
repository URL already exists for user.

Fixes #456

Breaking Change

feat(auth)!: migrate to Better Auth

Replace custom auth with Better Auth library
for improved security and OAuth support.

BREAKING CHANGE: 
- Session structure changed
- Old sessions invalidated
- Users must re-authenticate
- Update auth middleware imports

Closes #789

Documentation

docs(contributing): add code style guide

Add comprehensive code style documentation:
- TypeScript conventions
- React patterns
- Testing guidelines
- File organization

Refactoring

refactor(projects): simplify query logic

Extract common query patterns into reusable
functions. No behavior changes.

Multiple Changes

feat(web): improve project dashboard

- Add real-time updates via WebSocket
- Implement project sorting and filtering
- Add pagination for large project lists
- Improve loading states

Closes #123, #124, #125

🔄 Reverting Commits

revert: feat(tests): add test execution API

Revert commit abc1234 due to performance issues.

This reverts commit abc1234567890.

🛠️ Tools & Automation

Commitlint

Check commit messages automatically:

# Install
pnpm add -D @commitlint/cli @commitlint/config-conventional

# Configure
echo "module.exports = { extends: ['@commitlint/config-conventional'] }" > commitlint.config.js

# Use in git hook
npx commitlint --edit $1

Commitizen

Interactive commit message builder:

# Install
pnpm add -D commitizen cz-conventional-changelog

# Use
pnpm cz
# or
git cz

Husky + Commitlint

Enforce commit conventions:

# Install husky
pnpm add -D husky

# Set up
npx husky install

# Add commit-msg hook
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'

✅ Commit Checklist

Before committing:

• Message follows conventional format
• Type is appropriate
• Scope is accurate (if used)
• Subject is descriptive and concise
• Imperative mood used
• No capitalization or period in subject
• Body explains context (if needed)
• Breaking changes documented
• Issues referenced

🎯 Tips

Atomic Commits

Make commits focused and atomic:

# ✅ Good: Separate commits
git commit -m "feat(projects): add filtering UI"
git commit -m "feat(projects): add filtering API"
git commit -m "test(projects): add filtering tests"

# ❌ Bad: Everything in one commit
git commit -m "feat(projects): add filtering feature with UI, API, and tests"

Commit Frequency

# ✅ Commit logical units of work
# Each commit should be a complete, working change

# ❌ Don't commit half-finished work
# Unless using WIP commits (not for main branch)

WIP Commits

For work-in-progress (on feature branches only):

git commit -m "wip: implementing project filtering"

# Squash before merging to main
git rebase -i main

📊 Changelog Generation

Commits following this convention enable automated changelog generation:

# Generate changelog
npx conventional-changelog -p angular -i CHANGELOG.md -s

# Release with automatic version bump
npx standard-version

Changelog Output

## [1.2.0](2024-01-15)

### Features

* **projects**: add advanced filtering (#234)
* **tests**: add test execution API (#456)

### Bug Fixes

* **auth**: resolve session timeout (#789)
* **api**: prevent duplicate project creation

### BREAKING CHANGES

* **auth**: Users must re-authenticate after upgrade

🔗 Related Documentation

• Code Style: Code style guide
• Pull Requests: PR process
• Testing: Testing guidelines

Next: Pull Request Process →