Conventions

Conventional Commits

Standardized commit message format for clear and meaningful version control history.

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Standard Commit Types

Core Types (from Conventional Commits spec):

feat - New feature for the user
fix - Bug fix for the user
docs - Documentation only changes
style - Code style changes (formatting, white-space, semicolons, etc.)
refactor - Code change that neither fixes a bug nor adds a feature
perf - Code change that improves performance
test - Adding missing tests or correcting existing tests
build - Changes that affect the build system or external dependencies
ci - Changes to CI configuration files and scripts
chore - Other changes that don’t modify src or test files

Extended Commit Types

Additional Types for comprehensive project management:

wip - Work in progress (avoid in main branches)
deps - Dependency updates (alternative to chore(deps))
revert - Reverts a previous commit
merge - Merge commits (when not using fast-forward)
release - Release/version bump commits
security - Security fixes or improvements
i18n - Internationalization and localization
a11y - Accessibility improvements

Scopes

Scopes provide additional contextual information about what part of the codebase is affected.

Common Scope Patterns:

feat(api): add user endpoint
fix(auth): resolve token expiration
docs(readme): update installation steps
style(button): adjust padding
refactor(utils): simplify date formatting
perf(images): implement lazy loading
test(auth): add login flow tests
build(vite): update configuration
ci(github): add test workflow
chore(deps): update dependencies

Scope Guidelines:

✅ Use consistent, descriptive scopes ✅ Keep scopes short (single word or hyphenated) ✅ Use lowercase ✅ Group related changes under same scope ✅ Common scopes: api, ui, auth, db, cli, config

❌ Don’t use overly generic scopes (misc, other, stuff) ❌ Don’t use file names as scopes (use feature/module instead) ❌ Don’t mix multiple unrelated scopes in one commit

Breaking Changes

Breaking changes MUST be indicated in the commit message.

Method 1: Add ! after type/scope

feat!: remove deprecated API endpoints
feat(api)!: change response format

Method 2: Add BREAKING CHANGE: footer

feat(api): improve error handling

BREAKING CHANGE: Error responses now return RFC 7807 format instead of custom format.
Migration guide: https://docs.example.com/migration/v2

Multi-line Commit Messages

Use the body to explain what and why, not how.

Structure:

<type>[scope]: <short description>

<blank line>

<detailed explanation of the change>
- Why the change was necessary
- What problem it solves
- Any side effects or considerations

<blank line>

<footer(s)>

Example:

fix(auth): prevent token refresh race condition

Users were experiencing intermittent authentication failures when
multiple API calls triggered simultaneous token refresh attempts.

This fix implements a mutex lock to ensure only one token refresh
can occur at a time, with other requests waiting for the result.

- Added token refresh queue
- Implemented exponential backoff for retries
- Added unit tests for concurrent scenarios

Fixes: #234
Refs: #189

Commit Footers

Footers provide additional metadata and references.

Common Footers:

Issue References:

Fixes: #123
Closes: #456, #789
Resolves: #234
Refs: #567
Related: #890

Co-authorship:

Co-authored-by: Jane Doe <jane@example.com>
Co-authored-by: John Smith <john@example.com>

Review and Approval:

Reviewed-by: Alice Johnson <alice@example.com>
Approved-by: Bob Wilson <bob@example.com>
Signed-off-by: Developer Name <dev@example.com>

Breaking Changes:

BREAKING CHANGE: Description of the breaking change and migration path

Other Metadata:

See-also: #123
Depends-on: #456
Ticket: JIRA-123
PR: #789

Detailed Examples

Simple Feature:

feat(dashboard): add user activity chart

Feature with Scope and Details:

feat(analytics): add real-time visitor tracking

Implemented WebSocket-based real-time analytics dashboard that
displays current visitors, page views, and user actions.

- Added WebSocket server endpoint
- Created real-time chart component
- Implemented connection recovery logic

Closes: #123

Bug Fix with Breaking Change:

fix(api)!: correct user permissions logic

Previous implementation incorrectly granted admin permissions to
regular users under certain conditions. This fix enforces proper
permission checking but requires clients to update their
authentication flow.

BREAKING CHANGE: Authentication tokens now include explicit permission
claims. Clients must verify these claims before showing admin UI.

Migration guide: /docs/migration/v3-auth.md

Fixes: #456
Security: CVE-2025-1234

Performance Improvement:

perf(images): implement progressive image loading

Replaced immediate full-resolution image loading with progressive
enhancement strategy:

1. Show blur placeholder immediately
2. Load low-resolution preview
3. Load full resolution when in viewport

Results:
- 60% faster initial page load
- 40% reduction in bandwidth for above-fold content
- Improved Lighthouse performance score from 78 to 94

Refs: #789

Dependency Update:

deps: update astro to v4.2.0

Updated Astro framework to latest version for security patches
and performance improvements.

Notable changes:
- Fixed View Transitions memory leak
- Improved dev server startup time
- Added new experimental features

Full changelog: https://github.com/withastro/astro/releases/v4.2.0

Closes: #234

Refactoring:

refactor(auth): migrate to OAuth 2.1

Modernized authentication system to use OAuth 2.1 specification,
removing deprecated grant types and improving security posture.

Changes:
- Removed implicit grant flow
- Implemented PKCE for all flows
- Updated token refresh mechanism
- Migrated from JWT to opaque tokens

No user-facing changes, fully backward compatible.

Refs: #567

Internationalization:

i18n: add Japanese translations

Added complete Japanese translation for the application including:
- UI strings
- Error messages
- Email templates
- Documentation

Translated by: Yuki Tanaka <yuki@example.com>
Reviewed-by: Hiro Sato <hiro@example.com>

Closes: #890

Security Fix:

security(auth): fix JWT signature verification bypass

Critical security fix for JWT validation vulnerability that could
allow attackers to bypass authentication.

Impact: High
CVSS Score: 8.1
Affected versions: < 2.3.5

Details: https://security.example.com/advisories/2025-001

Fixes: #999
Security: CVE-2025-5678

Revert:

revert: feat(api): add rate limiting

This reverts commit abc123def456.

Reverting due to performance issues in production. The rate limiting
implementation caused 30% increase in response times under load.

Will re-implement with improved caching strategy.

Refs: #1001

Best Practices

Do’s:

✅ Write commits in imperative mood (“add feature” not “added feature”) ✅ Keep subject line under 72 characters ✅ Use body to explain what and why, not how ✅ Separate subject from body with blank line ✅ Use bullet points in body for multiple changes ✅ Reference issues and PRs in footer ✅ Make atomic commits (one logical change per commit) ✅ Use breaking change indicators for incompatible changes

Don’ts:

❌ Don’t use vague descriptions (“fix stuff”, “update things”) ❌ Don’t combine unrelated changes in one commit ❌ Don’t use generic types (chore for everything) ❌ Don’t skip the description ❌ Don’t include file names in subject (use scope instead) ❌ Don’t use past tense (“fixed bug” → “fix bug”) ❌ Don’t end subject line with period

Commit Granularity

Too Small (avoid):

fix: typo
fix: another typo
fix: one more typo

→ Should be: fix(docs): correct typos in API documentation

Too Large (avoid):

feat: complete redesign and new features

→ Should be split into multiple commits, each with specific changes

Just Right:

feat(ui): add dark mode toggle
fix(auth): resolve session timeout issue
refactor(api): simplify error handling

Tooling and Automation

Commitizen

Interactive CLI tool for writing standardized commit messages.

Installation:

bun add -D commitizen cz-conventional-changelog

Configuration (package.json):

{
  "scripts": {
    "commit": "cz"
  },
  "config": {
    "commitizen": {
      "path": "cz-conventional-changelog"
    }
  }
}

Usage:

git add .
bun run commit

Commitizen will prompt you through:

Select type
Enter scope (optional)
Write short description
Write longer description (optional)
List breaking changes (optional)
Reference issues (optional)

commitlint

Validates commit messages against conventional commit format.

Installation:

bun add -D @commitlint/cli @commitlint/config-conventional

Configuration (commitlint.config.js):

export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'build',
        'ci',
        'chore',
        'revert',
        'wip',
        'deps',
        'release',
        'security',
        'i18n',
        'a11y'
      ]
    ],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-max-length': [2, 'always', 72],
    'body-max-line-length': [2, 'always', 100]
  }
};

Usage:

echo "feat: add feature" | bunx commitlint

Husky

Git hooks to enforce commit conventions.

Installation:

bun add -D husky
bunx husky init

Setup commit-msg hook:

echo "bunx commitlint --edit \$1" > .husky/commit-msg
chmod +x .husky/commit-msg

Now every commit will be validated automatically.

standard-version

Automated versioning and CHANGELOG generation.

Installation:

bun add -D standard-version

Configuration (package.json):

{
  "scripts": {
    "release": "standard-version",
    "release:minor": "standard-version --release-as minor",
    "release:major": "standard-version --release-as major"
  }
}

Usage:

bun run release        # Auto-detect version bump
bun run release:minor  # Force minor version bump
bun run release:major  # Force major version bump

Automatically:

Determines version bump from commits
Updates version in package.json
Generates/updates CHANGELOG.md
Creates git tag
Commits changes

semantic-release

Fully automated version management and package publishing.

Installation:

bun add -D semantic-release @semantic-release/changelog @semantic-release/git

Configuration (.releaserc.json):

{
  "branches": ["main"],
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    "@semantic-release/npm",
    "@semantic-release/git",
    "@semantic-release/github"
  ]
}

CI Integration (GitHub Actions):

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bun install
      - run: bunx semantic-release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

conventional-changelog

Generate changelogs from commit messages.

Installation:

bun add -D conventional-changelog-cli

Configuration (package.json):

{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
    "changelog:all": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0"
  }
}

Usage:

bun run changelog      # Update changelog with latest changes
bun run changelog:all  # Regenerate entire changelog

IDE Integration

VS Code

Extension: Conventional Commits

Settings (.vscode/settings.json):

{
  "conventionalCommits.autoCommit": false,
  "conventionalCommits.scopes": [
    "api",
    "ui",
    "auth",
    "db",
    "cli",
    "config"
  ],
  "conventionalCommits.showEditor": true
}

JetBrains IDEs

Plugin: Conventional Commit

Configure custom types and scopes in plugin settings.

References

Conventional Branch

Git branch naming conventions for organized workflow and clear intent.

Format

<type>/<description>
<type>/<scope>-<description>
<type>/<ticket>-<description>
<type>/<ticket>-<scope>-<description>

Standard Branch Types

Permanent Branches:

main - Primary production-ready branch
master - Alternative name for primary branch (use main preferred)
develop - Integration branch for features (Git Flow)
staging - Pre-production testing branch

Temporary Branches:

feature/ or feat/ - New functionality
bugfix/ or fix/ - Bug fixes for development
hotfix/ - Critical production fixes
release/ - Release preparation
chore/ - Maintenance tasks
docs/ - Documentation only changes
refactor/ - Code refactoring
perf/ - Performance improvements
test/ - Test additions or updates
build/ - Build system changes
ci/ - CI/CD pipeline changes
style/ - Code style changes

Extended Branch Types

Additional Types for comprehensive workflows:

experiment/ - Experimental features or proof of concepts
spike/ - Research or investigation tasks
wip/ - Work in progress (not ready for review)
security/ - Security fixes or improvements
deps/ - Dependency updates
revert/ - Reverting previous changes
migration/ - Data or code migrations
i18n/ - Internationalization work
a11y/ - Accessibility improvements

Branch Naming Conventions

Character Rules:

✅ Use lowercase letters (a-z) ✅ Use numbers (0-9) ✅ Use hyphens (-) to separate words ✅ Use forward slash (/) to separate type from description

❌ Avoid spaces ❌ Avoid special characters (@, #, $, %, etc.) ❌ Avoid consecutive hyphens or slashes ❌ Avoid leading/trailing punctuation ❌ Avoid uppercase letters (unless part of ticket ID)

Description Guidelines:

✅ Be descriptive yet concise ✅ Use present tense (“add” not “added”) ✅ Separate words with hyphens ✅ Keep total branch name under 50-60 characters ✅ Include ticket/issue numbers when relevant

❌ Don’t use vague descriptions (“fix-bug”, “update”) ❌ Don’t include commit hashes ❌ Don’t use developer names ❌ Don’t duplicate type in description

Ticket Integration

With Issue Numbers:

feature/123-user-authentication
fix/456-login-timeout
hotfix/789-security-patch

With Ticket Systems:

feature/JIRA-123-add-dashboard
fix/GH-456-api-error
hotfix/SEC-789-xss-vulnerability

Grouped by Scope:

feature/auth-social-login
feature/auth-two-factor
fix/ui-button-spacing
fix/ui-modal-overflow

Branch Patterns

Simple Pattern

<type>/<description>

Examples:

feature/dark-mode
fix/header-alignment
docs/api-reference
chore/dependencies

With Scope

<type>/<scope>-<description>

Examples:

feature/auth-login-page
fix/api-timeout-handling
refactor/ui-button-component
perf/db-query-optimization

With Ticket

<type>/<ticket>-<description>

Examples:

feature/123-user-dashboard
fix/456-memory-leak
hotfix/789-security-patch

With Ticket and Scope

<type>/<ticket>-<scope>-<description>

Examples:

feature/123-auth-oauth-integration
fix/456-api-rate-limiting
refactor/789-db-connection-pool

Numbered Branches

For sequential or parallel work:

<type>/<description>-<number>
<type>/<description>-v<version>

Examples:

experiment/new-architecture-1
experiment/new-architecture-2
feature/payment-gateway-v1
feature/payment-gateway-v2
spike/performance-investigation-1

Branch Lifecycle

Creating Branches

From main/develop:

# Feature branch
git checkout -b feature/user-profile main

# Bugfix from develop
git checkout -b fix/login-error develop

# Hotfix from main (production)
git checkout -b hotfix/critical-security-fix main

Naming Based on Origin:

Features/bugs → from develop or main
Hotfixes → always from main (production)
Release branches → from develop

Updating Branches

Keep branch updated with base:

# Update from main
git checkout feature/my-feature
git pull origin main --rebase

# Or merge if preferred
git merge main

Frequency:

Update daily for long-running branches
Update before creating PR
Update after resolving conflicts

Merging Branches

Feature/Bugfix → develop/main:

# Via Pull Request (recommended)
gh pr create --base main --head feature/my-feature

# Direct merge (if permitted)
git checkout main
git merge --no-ff feature/my-feature
git push origin main

Hotfix → main and develop:

# Merge to main first
git checkout main
git merge --no-ff hotfix/security-fix
git tag -a v1.2.3 -m "Security fix"
git push origin main --tags

# Then backport to develop
git checkout develop
git merge --no-ff hotfix/security-fix
git push origin develop

Deleting Branches

After successful merge:

# Delete local branch
git branch -d feature/my-feature

# Delete remote branch
git push origin --delete feature/my-feature

# Or via GitHub CLI
gh pr merge 123 --delete-branch

Bulk cleanup:

# Delete all merged branches
git branch --merged | grep -v "\*\|main\|develop" | xargs -n 1 git branch -d

# Delete remote tracking branches that no longer exist
git fetch --prune

Real-World Examples

E-commerce Application

feature/cart-add-to-cart
feature/cart-checkout-flow
feature/payment-stripe-integration
fix/product-image-loading
fix/cart-quantity-validation
hotfix/payment-processing-error
release/v2.0.0
chore/update-dependencies
docs/api-endpoints

SaaS Platform

feature/auth-sso-saml
feature/billing-subscription-management
feature/analytics-dashboard
fix/auth-token-expiration
fix/billing-invoice-generation
hotfix/database-connection-pool
refactor/api-error-handling
perf/query-optimization
security/implement-rate-limiting

Content Management System

feature/editor-rich-text
feature/media-library
feature/user-roles-permissions
fix/editor-autosave
fix/media-upload-validation
i18n/add-french-translation
a11y/keyboard-navigation
migration/v1-to-v2-content

Open Source Project

feature/123-plugin-system
feature/456-theme-customization
fix/789-memory-leak
fix/1011-broken-links
docs/contributing-guidelines
docs/installation-guide
ci/github-actions-workflow
test/integration-tests

Branch Strategies

Git Flow

main (production)
├── develop (integration)
│   ├── feature/user-auth
│   ├── feature/dashboard
│   └── bugfix/api-error
├── release/v1.2.0
└── hotfix/security-patch

Branch Flow:

Features: develop → feature/* → develop
Releases: develop → release/* → main + develop
Hotfixes: main → hotfix/* → main + develop

GitHub Flow

main (production)
├── feature/user-profile
├── feature/notifications
├── fix/login-issue
└── hotfix/critical-bug

Branch Flow:

All branches from main
All branches back to main
Deploy from main

GitLab Flow

main (production)
├── pre-production
│   ├── feature/new-ui
│   └── fix/api-timeout
└── staging

Branch Flow:

Features: main → feature/* → staging → pre-production → main
Environment branches are long-lived

Best Practices

Do’s:

✅ Create branches from latest main/develop ✅ Use descriptive, meaningful names ✅ Include ticket numbers when available ✅ Keep branches short-lived (days, not months) ✅ Update frequently from base branch ✅ Delete branches after merging ✅ Use consistent naming across team ✅ Follow team conventions strictly

Don’ts:

❌ Don’t work directly on main/develop ❌ Don’t create branches from feature branches (unless necessary) ❌ Don’t use personal names in branches ❌ Don’t let branches diverge too far from base ❌ Don’t reuse old branch names ❌ Don’t keep stale branches indefinitely ❌ Don’t use ambiguous names

Anti-Patterns

Vague Names:

❌ fix/bug
❌ feature/new-stuff
❌ update/things
❌ temp
❌ wip

Too Long:

❌ feature/implement-user-authentication-with-oauth2-and-jwt-tokens-and-refresh-token-rotation

→ Better: feature/oauth2-authentication

Wrong Type:

❌ feature/fix-login-bug    # Should be fix/
❌ fix/add-new-feature      # Should be feature/
❌ chore/critical-security  # Should be hotfix/ or security/

Personal Branches:

❌ john/working-on-auth
❌ dev-team-refactor
❌ my-changes

Reused Names:

❌ Reusing feature/user-auth after it was already merged

→ Better: feature/user-auth-improvements or feature/user-auth-v2

Automation and Tooling

Branch Protection Rules

GitHub Settings:

main:
  - Require pull request reviews (2 approvals)
  - Require status checks to pass
  - Require branches to be up to date
  - Require conversation resolution
  - Do not allow bypassing settings
  - Restrict pushes to specific users/teams

Configuration:

# Via GitHub CLI
gh api repos/:owner/:repo/branches/main/protection \
  --method PUT \
  --field required_pull_request_reviews='{"required_approving_review_count":2}' \
  --field enforce_admins=true

Git Aliases

Useful aliases (~/.gitconfig):

[alias]
  # Create feature branch
  feat = "!f() { git checkout -b feature/$1 main; }; f"

  # Create fix branch
  fix = "!f() { git checkout -b fix/$1 develop; }; f"

  # Create hotfix branch
  hotfix = "!f() { git checkout -b hotfix/$1 main; }; f"

  # Update branch from main
  update = "!git pull origin main --rebase"

  # List branches by date
  branches = "!git branch --sort=-committerdate"

  # Delete merged branches
  cleanup = "!git branch --merged | grep -v '\\*\\|main\\|develop' | xargs -n 1 git branch -d"

Usage:

git feat user-authentication
git fix login-timeout
git hotfix security-patch
git update
git cleanup

Branch Naming Validation

Pre-push hook (.git/hooks/pre-push):

#!/usr/bin/env bash

current_branch=$(git symbolic-ref --short HEAD)

# Allow permanent branches
if [[ "$current_branch" =~ ^(main|master|develop|staging)$ ]]; then
  exit 0
fi

# Validate branch name format
if ! [[ "$current_branch" =~ ^(feature|feat|fix|bugfix|hotfix|release|chore|docs|refactor|perf|test|build|ci|style|experiment|spike|wip|security|deps|revert|migration|i18n|a11y)/[a-z0-9-]+$ ]]; then
  echo "❌ Invalid branch name: $current_branch"
  echo ""
  echo "Branch names must follow the pattern:"
  echo "  <type>/<description>"
  echo ""
  echo "Valid types:"
  echo "  feature, fix, hotfix, release, chore, docs, refactor,"
  echo "  perf, test, build, ci, style, experiment, spike, etc."
  echo ""
  echo "Example: feature/user-authentication"
  exit 1
fi

exit 0

Make executable:

chmod +x .git/hooks/pre-push

GitHub Actions Integration

Branch naming check (.github/workflows/branch-naming.yml):

name: Branch Naming

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  check-branch-name:
    runs-on: ubuntu-latest
    steps:
      - name: Check branch name
        run: |
          BRANCH="${{ github.head_ref }}"

          if [[ ! "$BRANCH" =~ ^(feature|feat|fix|bugfix|hotfix|release|chore|docs|refactor|perf|test|build|ci|style)/[a-z0-9-]+$ ]]; then
            echo "❌ Invalid branch name: $BRANCH"
            echo "Branch names must follow: <type>/<description>"
            exit 1
          fi

          echo "✅ Branch name is valid: $BRANCH"

References

Semantic Versioning (SemVer)

Version numbering system that conveys meaning about changes in each release.

Format: MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Version Increments:

MAJOR (1.0.0) - Incompatible API changes, breaking changes
MINOR (0.1.0) - New features, backward-compatible additions
PATCH (0.0.1) - Bug fixes, backward-compatible fixes

Pre-release versions:

1.0.0-alpha - Alpha release
1.0.0-beta - Beta release
1.0.0-rc.1 - Release candidate

Examples:

0.1.0 - Initial development
1.0.0 - First stable release
1.1.0 - New features added
1.1.1 - Bug fixes
2.0.0 - Breaking changes

Reference: semver.org

Keep a Changelog

Structured changelog format for documenting all notable changes in a project.

Principles:

Changelogs are for humans, not machines
One entry per version
Group changes by type
Latest version first
Release dates included

Change Types:

Added - New features
Changed - Changes to existing functionality
Deprecated - Soon-to-be removed features
Removed - Removed features
Fixed - Bug fixes
Security - Security vulnerability fixes

Example Format:

## [1.0.0] - 2025-01-15

### Added
- User authentication system
- Dashboard analytics

### Fixed
- Login timeout issue
- API response caching

### Changed
- Updated UI design system

Reference: keepachangelog.com

Code Style

Consistent code formatting and conventions for maintainable codebases.

Style Guides:

Tools:

Prettier - Code formatting
ESLint - Code linting and style enforcement