Git Commit Message Standards

Overview

AzmX follows Conventional Commits specification for standardized, automated-friendly commit messages that enable semantic versioning, automated changelog generation, and clear project history.

Conventional Commits Format

Structure

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Message Flow

graph TD
    A[Write Commit Message] --> B{Follows Convention?}
    B -->|No| C[Commitlint Rejects]
    B -->|Yes| D[Parse Type & Scope]

    D --> E{Type Analysis}
    E -->|feat| F[MINOR Version Bump]
    E -->|fix| G[PATCH Version Bump]
    E -->|BREAKING CHANGE| H[MAJOR Version Bump]
    E -->|docs, style, etc| I[No Version Change]

    F --> J[Generate Changelog Entry]
    G --> J
    H --> J
    I --> K[Commit Accepted]

    J --> K
    C --> L[Developer Fixes Message]
    L --> A

    style F fill:#4ecdc4
    style G fill:#45b7d1
    style H fill:#ff6b6b
    style K fill:#00b894
    style C fill:#ff6b6b

Commit Types

Primary Types

feat: New Features

# Examples
feat(auth): add JWT token authentication
feat(dashboard): implement user analytics widget
feat(api): add pagination to user endpoints

fix: Bug Fixes

# Examples
fix(login): resolve validation error message
fix(payment): handle gateway timeout gracefully
fix(ui): correct mobile responsive layout

docs: Documentation

# Examples
docs(api): update authentication endpoint guide
docs(readme): add installation instructions
docs(contributing): update pull request process

Secondary Types

style: Code Formatting

# Examples (no functionality change)
style(frontend): fix ESLint formatting issues
style(backend): apply Black formatting
style(css): organize import statements

refactor: Code Restructuring

# Examples (no functionality change)
refactor(database): optimize user query performance
refactor(components): extract reusable button component
refactor(services): simplify authentication logic

test: Testing

# Examples
test(api): add integration tests for user endpoints
test(components): add unit tests for login form
test(e2e): add checkout flow automation tests

chore: Maintenance

# Examples
chore(deps): update Django to version 5.2
chore(build): configure webpack optimization
chore(ci): update GitHub Actions workflow

Specialized Types

perf: Performance Improvements

# Examples
perf(database): add indexes for user queries
perf(frontend): implement lazy loading for images
perf(api): optimize response caching strategy

build: Build System Changes

# Examples
build(webpack): add production optimization
build(docker): optimize container image size
build(npm): update package.json scripts

ci: Continuous Integration

# Examples
ci(github): add automated testing workflow
ci(deploy): update production deployment script
ci(quality): integrate SonarQube analysis

revert: Reverting Changes

# Examples
revert: "feat(payment): add Stripe integration"

This reverts commit 1234567.

Scope Guidelines

Frontend Scopes

# Component-based
feat(button): add loading state animation
fix(navbar): resolve mobile menu toggle
style(form): update input field styling

# Feature-based
feat(auth): implement password reset flow
fix(dashboard): correct analytics calculation
refactor(settings): simplify user preferences

Backend Scopes

# Module-based
feat(users): add user profile endpoints
fix(orders): resolve payment processing bug
refactor(auth): simplify JWT token handling

# Service-based
feat(email): add notification service
fix(database): resolve connection pooling issue
perf(cache): optimize Redis key management

Infrastructure Scopes

# System-based
feat(docker): add multi-stage build optimization
fix(nginx): resolve SSL certificate configuration
ci(k8s): update deployment manifests

# Tool-based
chore(terraform): update AWS resource definitions
build(webpack): optimize bundle splitting
test(cypress): add end-to-end test coverage

Breaking Changes

Indication Methods

Method 1: Exclamation Mark

feat!: redesign authentication API
fix!: change user ID format from integer to UUID
refactor!: remove deprecated payment methods

feat(api): add new authentication endpoints

BREAKING CHANGE: The authentication API has been completely redesigned.
Old endpoints /auth/login and /auth/logout are no longer supported.
Use /api/v2/auth/signin and /api/v2/auth/signout instead.

Breaking Change Examples

# API Changes
feat!: update user API to use UUIDs instead of integers

BREAKING CHANGE: User IDs are now UUIDs. Update all client code
to handle string IDs instead of integers.

# Configuration Changes
chore!: update environment variable naming convention

BREAKING CHANGE: Environment variables now use AZMX_ prefix.
Update your .env files:
- DB_HOST -> AZMX_DB_HOST
- API_KEY -> AZMX_API_KEY

# Database Schema Changes
feat!: normalize user profile data structure

BREAKING CHANGE: User profile data moved to separate table.
Run migration script before deploying:
python manage.py migrate --run-syncdb

Multi-line Commit Messages

Structure Template

<type>[scope]: <short description>

<longer description explaining the motivation for the change
and contrasting this with previous behavior>

<footer with issue references, breaking changes, etc.>

Detailed Example

feat(payment): implement Stripe payment integration

This adds comprehensive Stripe payment processing including:
- Credit card payment handling
- Subscription management
- Webhook processing for payment events
- Proper error handling for failed payments

The implementation uses Stripe's latest API version and follows
their security best practices for handling sensitive payment data.

Closes #123
Reviewed-by: @backend-lead
Co-authored-by: @payment-specialist

Multi-change Example

refactor(auth): improve JWT token handling and validation

- Extract token validation to separate service
- Add comprehensive error handling for expired tokens
- Implement automatic token refresh mechanism
- Add unit tests for all authentication scenarios
- Update API documentation with new error codes

This refactoring improves security and maintainability while
maintaining backward compatibility with existing clients.

Fixes #456
Relates to #789

Team-Specific Conventions

Role-Based Prefixes

# Frontend Team
frontend/feat(dashboard): add user analytics component
frontend/fix(ui): resolve mobile responsive issues

# Backend Team
backend/feat(api): implement rate limiting
backend/fix(database): optimize query performance

# DevOps Team
devops/feat(ci): add automated deployment pipeline
devops/fix(monitoring): resolve alert configuration

# AI/ML Team
ml/feat(model): improve recommendation accuracy
ai/fix(training): resolve data preprocessing issue

Project-Specific Scopes

# E-commerce Project
feat(cart): add item quantity validation
feat(checkout): implement guest checkout flow
feat(inventory): add stock level tracking

# CRM Project
feat(contacts): add bulk contact import
feat(deals): implement pipeline automation
feat(reports): add sales analytics dashboard

# Analytics Project
feat(tracking): add event data collection
feat(dashboard): implement real-time metrics
feat(export): add data export functionality

Automation Integration

Commitlint Configuration

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat', 'fix', 'docs', 'style', 'refactor',
        'test', 'chore', 'perf', 'build', 'ci', 'revert'
      ],
    ],
    'scope-enum': [
      2,
      'always',
      [
        // Frontend
        'ui', 'components', 'pages', 'routing', 'state',
        // Backend
        'api', 'database', 'auth', 'models', 'services',
        // Infrastructure
        'docker', 'k8s', 'terraform', 'ci', 'monitoring',
        // General
        'deps', 'config', 'security', 'performance'
      ],
    ],
    'subject-case': [2, 'never', ['sentence-case', 'start-case', 'pascal-case', 'upper-case']],
    'subject-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'subject-max-length': [2, 'always', 72],
    'body-leading-blank': [1, 'always'],
    'body-max-line-length': [2, 'always', 100],
    'footer-leading-blank': [1, 'always'],
  },
}

Semantic Release Integration

{
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "conventionalcommits",
        "releaseRules": [
          { "type": "feat", "release": "minor" },
          { "type": "fix", "release": "patch" },
          { "type": "perf", "release": "patch" },
          { "type": "revert", "release": "patch" },
          { "type": "docs", "scope": "README", "release": "patch" },
          { "type": "style", "release": false },
          { "type": "chore", "release": false },
          { "type": "refactor", "release": "patch" },
          { "type": "test", "release": false },
          { "type": "build", "release": "patch" },
          { "type": "ci", "release": false }
        ]
      }
    ]
  ]
}

Quality Guidelines

Good Commit Messages ✅

# Clear and descriptive
feat(auth): add two-factor authentication support
fix(payment): resolve Stripe webhook timeout issue
docs(api): update user authentication endpoints

# Proper scope and context
refactor(database): optimize user query performance
test(components): add unit tests for login form
chore(deps): update React to version 18.2

# Breaking changes clearly marked
feat!: migrate to new user authentication system

BREAKING CHANGE: The /auth/login endpoint now requires
email instead of username. Update all client applications.

Poor Commit Messages ❌

# Too vague
fix: bug fix
feat: new feature
update: changes

# No context
fix login
add button
remove code

# Inconsistent format
Fixed the login bug
adding new feature for users
Update documentation

# Missing type
user authentication improvements
payment gateway integration
database optimization

Automated Changelog Generation

Generated Changelog Example

## [1.3.0](https://github.com/azmx/project/compare/v1.2.0...v1.3.0) (2025-01-20)

### ✨ Features
* **auth**: add two-factor authentication ([#123](https://github.com/azmx/project/pull/123)) ([abc1234](https://github.com/azmx/project/commit/abc1234))
* **dashboard**: implement user analytics widget ([#124](https://github.com/azmx/project/pull/124)) ([def5678](https://github.com/azmx/project/commit/def5678))
* **api**: add pagination to user endpoints ([#125](https://github.com/azmx/project/pull/125)) ([ghi9012](https://github.com/azmx/project/commit/ghi9012))

### 🐛 Bug Fixes
* **payment**: resolve Stripe webhook timeout ([#126](https://github.com/azmx/project/pull/126)) ([jkl3456](https://github.com/azmx/project/commit/jkl3456))
* **ui**: correct mobile responsive layout ([#127](https://github.com/azmx/project/pull/127)) ([mno7890](https://github.com/azmx/project/commit/mno7890))

### 🚀 Performance Improvements
* **database**: add indexes for user queries ([#128](https://github.com/azmx/project/pull/128)) ([pqr1234](https://github.com/azmx/project/commit/pqr1234))

### 📖 Documentation
* **api**: update authentication endpoint guide ([#129](https://github.com/azmx/project/pull/129)) ([stu5678](https://github.com/azmx/project/commit/stu5678))

Tools and Utilities

Git Aliases for Conventional Commits

# Add to ~/.gitconfig
[alias]
    # Conventional commit shortcuts
    feat = "!f() { git commit -m \"feat: $1\"; }; f"
    fix = "!f() { git commit -m \"fix: $1\"; }; f"
    docs = "!f() { git commit -m \"docs: $1\"; }; f"
    style = "!f() { git commit -m \"style: $1\"; }; f"
    refactor = "!f() { git commit -m \"refactor: $1\"; }; f"
    test = "!f() { git commit -m \"test: $1\"; }; f"
    chore = "!f() { git commit -m \"chore: $1\"; }; f"

    # Scoped commit shortcuts
    featui = "!f() { git commit -m \"feat(ui): $1\"; }; f"
    fixapi = "!f() { git commit -m \"fix(api): $1\"; }; f"
    docsapi = "!f() { git commit -m \"docs(api): $1\"; }; f"

Commit Message Templates

# ~/.gitmessage template
# <type>[optional scope]: <description>
#
# [optional body]
#
# [optional footer(s)]
#
# Types: feat, fix, docs, style, refactor, test, chore, perf, build, ci, revert
# Scopes: auth, api, ui, database, config, deps, security
#
# Examples:
# feat(auth): add JWT token authentication
# fix(payment): resolve gateway timeout issue
# docs(api): update user endpoint documentation

Semantic Versioning for Leads - Version management integration
Git Workflow - Basic Git workflow with GitHub Flow
Git Branching Strategy - Advanced GitFlow strategy
Pre-commit Hooks - Automated commit validation

Last Updated: 2025-01-20 Tools Required: commitlint, semantic-release, Git aliases Team Contacts: Tech Leads for scope definitions, DevOps for automation setup