Conventional Commits

Overview

Conventional Commits is a specification for commit messages that provides a lightweight convention on top of commit history. The Agent Platform uses Conventional Commits to automate versioning, changelog generation, and release notes.

Specification

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Structure

1. Type (required): Describes the kind of change
2. Scope (optional): Describes what is affected
3. Description (required): Short summary of the change
4. Body (optional): Longer explanation
5. Footer (optional): Breaking changes, issue references

Example

feat(auth): add OAuth2 authentication support

Implements OAuth2 authentication flow with support for
authorization code and client credentials grants.

BREAKING CHANGE: API key authentication is deprecated.
Clients must migrate to OAuth2.

Closes #106

Commit Types

The Agent Platform uses these standard commit types:

Note: In the Agent Platform's release branch model, all commits result in PATCH bumps. MINOR/MAJOR bumps occur when creating new release branches.

Type Details

feat: New Features

Use feat: for new functionality or capabilities.

Examples:

git commit -m "feat: add OAuth2 authentication"
git commit -m "feat(api): implement rate limiting"
git commit -m "feat(cli): add auth command"
git commit -m "feat(sdk): support async operations"

When to use:

• Adding new endpoints
• Implementing new features
• Adding new options/parameters
• Introducing new capabilities

fix: Bug Fixes

Use fix: for correcting incorrect behavior.

Examples:

git commit -m "fix: resolve memory leak in agent runtime"
git commit -m "fix(auth): correct token validation"
git commit -m "fix(api): handle null values properly"
git commit -m "fix(sdk): prevent race condition"

When to use:

• Fixing bugs
• Correcting errors
• Resolving edge cases
• Patching security vulnerabilities

docs: Documentation

Use docs: for documentation changes only.

Examples:

git commit -m "docs: update API documentation"
git commit -m "docs(readme): add installation guide"
git commit -m "docs(api): clarify authentication flow"
git commit -m "docs: fix typos in migration guide"

When to use:

• Updating documentation files
• Fixing documentation errors
• Adding code examples
• Improving explanations

refactor: Code Refactoring

Use refactor: for code changes that neither fix bugs nor add features.

Examples:

git commit -m "refactor: simplify authentication logic"
git commit -m "refactor(api): extract validation to separate module"
git commit -m "refactor(db): optimize query structure"
git commit -m "refactor: rename variables for clarity"

When to use:

• Restructuring code
• Improving code quality
• Simplifying logic
• Renaming for clarity

perf: Performance Improvements

Use perf: for changes that improve performance.

Examples:

git commit -m "perf: optimize database queries"
git commit -m "perf(api): add response caching"
git commit -m "perf(agent): reduce memory footprint"
git commit -m "perf: implement lazy loading"

When to use:

• Improving speed
• Reducing resource usage
• Optimizing algorithms
• Implementing caching

test: Tests

Use test: for adding or updating tests.

Examples:

git commit -m "test: add OAuth2 integration tests"
git commit -m "test(api): add rate limiting tests"
git commit -m "test: increase coverage to 90%"
git commit -m "test(unit): add edge case tests"

When to use:

• Adding new tests
• Updating existing tests
• Fixing failing tests
• Improving test coverage

chore: Maintenance

Use chore: for maintenance tasks.

Examples:

git commit -m "chore: update dependencies"
git commit -m "chore(deps): bump axios to 1.6.0"
git commit -m "chore: configure ESLint"
git commit -m "chore(ci): update Node version"

When to use:

• Updating dependencies
• Configuring tools
• Maintaining build scripts
• Updating CI/CD

Scopes

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

Agent Platform Scopes

Common scopes in the Agent Platform:

Using Scopes

Single scope:

git commit -m "feat(auth): add OAuth2 support"

Multiple scopes (use /):

git commit -m "feat(api/auth): implement JWT tokens"

No scope (affects multiple areas):

git commit -m "feat: add distributed tracing"

Breaking Changes

Breaking changes MUST be indicated in commits using one of two methods:

Method 1: Exclamation Mark

Add ! after type/scope:

git commit -m "feat!: redesign authentication API"

git commit -m "feat(auth)!: change token format"

Method 2: BREAKING CHANGE Footer

Include BREAKING CHANGE: in footer:

git commit -m "feat(auth): redesign authentication API

BREAKING CHANGE: The /auth endpoint now requires OAuth2
tokens instead of API keys. Update your integration to
use the new OAuth2 flow.

Closes #110"

Breaking Change Best Practices

1. Describe the breaking change clearly

   BREAKING CHANGE: API key authentication removed.
   Use OAuth2 instead. See migration guide: https://...
   

2. Provide migration instructions

   BREAKING CHANGE: /auth endpoint changed.
   
   Before:
     POST /auth { apiKey: "..." }
   
   After:
     POST /auth { accessToken: "..." }
   

3. Link to documentation

   BREAKING CHANGE: Authentication redesigned.
   See migration guide: https://docs.agent-platform.io/migrate/v0.3
   

Commit Body

The commit body provides additional context and explanation.

Structure

<type>(<scope>): <description>

<why the change was made>

<what the change does>

<any additional context>

<footer>

Example with Body

git commit -m "feat(auth): add OAuth2 authentication support

The previous API key authentication was simple but not
secure enough for production use. OAuth2 provides:
- Industry standard security
- Token expiration and refresh
- Fine-grained permissions

This commit implements OAuth2 with support for:
- Authorization code flow
- Client credentials flow
- Refresh tokens

The old API key method is deprecated but still works
for backward compatibility.

Closes #106
See: https://docs.agent-platform.io/auth/oauth2"

Commit Footers

Footers provide metadata about the commit.

Common Footers

Multiple Footers

git commit -m "feat(auth): add OAuth2 support

Implements OAuth2 authentication flow.

Closes #106
Refs #110
Changelog: added
Reviewed-by: @team-lead"

Examples by Scenario

Scenario 1: Simple Feature

git commit -m "feat(api): add rate limiting

Implements token bucket rate limiting for API endpoints.
Default: 100 requests per minute.

Closes #120"

Scenario 2: Bug Fix

git commit -m "fix(agent): prevent memory leak

The agent runtime was not releasing resources after
task completion. Added proper cleanup in finally block.

Fixes #107"

Scenario 3: Breaking Change

git commit -m "feat(auth)!: replace API keys with OAuth2

BREAKING CHANGE: API key authentication is removed.
All clients must migrate to OAuth2.

Migration guide:
1. Register OAuth2 client in settings
2. Update authentication flow:
   - Before: X-API-Key header
   - After: Authorization: Bearer <token>
3. See: https://docs.agent-platform.io/migrate/oauth2

Closes #110"

Scenario 4: Performance Improvement

git commit -m "perf(db): optimize query with indexes

Query performance was degrading with large datasets.
Added indexes on frequently queried columns:
- user_id
- created_at
- status

Query time reduced from 2.5s to 50ms.

Closes #130"

Scenario 5: Documentation

git commit -m "docs(api): add OAuth2 authentication guide

Added comprehensive guide covering:
- OAuth2 flow diagrams
- Code examples (curl, Node.js, Python)
- Token refresh process
- Error handling

Closes #115"

Scenario 6: Multiple Issues

git commit -m "feat(cli): add auth and config commands

Added two new commands:
- auth: Manage authentication (login, logout, status)
- config: Manage configuration (get, set, list)

Both commands follow consistent CLI patterns.

Closes #125
Closes #126"

Scenario 7: Revert

git commit -m "revert: feat(auth): add OAuth2 support

This reverts commit abc123def456.

OAuth2 implementation causing issues in production.
Reverting to investigate and fix before re-deploying.

Refs #150"

Validation

Using commitlint

Installation:

npm install --save-dev @commitlint/cli @commitlint/config-conventional

Configuration (commitlint.config.js):

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat',
        'fix',
        'docs',
        'style',
        'refactor',
        'perf',
        'test',
        'chore',
        'revert',
        'ci'
      ]
    ],
    'scope-enum': [
      2,
      'always',
      [
        'auth',
        'api',
        'cli',
        'sdk',
        'db',
        'ci',
        'docs',
        'agent',
        'core',
        'config'
      ]
    ],
    'subject-case': [2, 'never', ['upper-case', 'pascal-case', 'start-case']],
    'subject-empty': [2, 'never'],
    'subject-full-stop': [2, 'never', '.'],
    'header-max-length': [2, 'always', 100],
    'body-leading-blank': [2, 'always'],
    'body-max-line-length': [2, 'always', 100],
    'footer-leading-blank': [2, 'always']
  }
};

Usage:

# Validate last commit
echo "$(git log -1 --pretty=%B)" | npx commitlint

# Validate commit message
echo "feat: add new feature" | npx commitlint

# Validate range
npx commitlint --from HEAD~10 --to HEAD

Git Hook with Husky

Setup:

npm install --save-dev husky
npx husky init
echo 'npx --no-install commitlint --edit $1' > .husky/commit-msg
chmod +x .husky/commit-msg

Test:

# Invalid commit (will fail)
git commit -m "added feature"

# Valid commit (will succeed)
git commit -m "feat: add new feature"

CI/CD Validation

# .gitlab-ci.yml
validate-commits:
  stage: validate
  image: node:20-alpine
  before_script:
    - npm install -g @commitlint/cli @commitlint/config-conventional
  script:
    - |
      # Validate commits in MR
      git fetch origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME
      COMMITS=$(git log origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME..HEAD --format=%H)

      INVALID=0
      for commit in $COMMITS; do
        MESSAGE=$(git log --format=%B -n 1 $commit)
        echo "Validating: $commit"
        echo "$MESSAGE"
        if ! echo "$MESSAGE" | commitlint; then
          INVALID=1
        fi
        echo "---"
      done

      if [ $INVALID -eq 1 ]; then
        echo ""
        echo " Some commits do not follow Conventional Commits"
        echo ""
        echo "Format: <type>(<scope>): <description>"
        echo ""
        echo "Valid types: feat, fix, docs, style, refactor, perf, test, chore, ci, revert"
        echo ""
        echo "Examples:"
        echo "  feat(auth): add OAuth2 support"
        echo "  fix(api): resolve memory leak"
        echo "  docs: update README"
        echo ""
        exit 1
      fi

      echo " All commits are valid"
  only:
    - merge_requests

Best Practices

DO

1. Use present tense

    feat: add OAuth2 support
    feat: added OAuth2 support

2. Keep description concise

    feat: add OAuth2 authentication
    feat: add OAuth2 authentication with authorization code flow and refresh tokens

3. Use lowercase

    feat: add oauth2 support
    feat: Add OAuth2 Support

4. No period at end

    feat: add oauth2 support
    feat: add oauth2 support.

5. Be specific with scope

    feat(auth): add oauth2 support
    feat: add oauth2 support to authentication

6. Use body for context

   git commit -m "feat(auth): add oauth2 support
   
   Implements OAuth2 with authorization code and
   client credentials flows. Replaces API key auth."

7. Link issues

   git commit -m "fix(api): resolve memory leak
   
   Fixes #107"

DON'T

1. Don't use past tense

    feat: added oauth2 support
    feat: add oauth2 support

2. Don't use capital letters

    Feat: Add OAuth2 Support
    feat: add oauth2 support

3. Don't end with period

    feat: add oauth2 support.
    feat: add oauth2 support

4. Don't be vague

    fix: fix bug
    fix(api): resolve null pointer exception

5. Don't include file names

    feat: add oauth2.js
    feat(auth): add oauth2 support

6. Don't use WIP commits

    WIP: working on oauth2
    feat(auth): add oauth2 support

Common Mistakes

Mistake 1: Wrong Type

 chore: add new feature
 feat: add new feature

Mistake 2: Missing Scope

 feat: fix authentication bug
 fix(auth): resolve token validation issue

Mistake 3: Too Long Description

 feat: add OAuth2 authentication with authorization code flow, client credentials, and refresh token support
 feat(auth): add OAuth2 authentication

Implements OAuth2 with multiple grant types:
- Authorization code flow
- Client credentials
- Refresh tokens

Mistake 4: Not Marking Breaking Changes

 feat: change authentication API
 feat!: change authentication API

BREAKING CHANGE: API key authentication removed.
Use OAuth2 instead.

Mistake 5: Combining Multiple Changes

 feat: add OAuth2 and fix memory leak
 Separate commits:
   feat(auth): add OAuth2 support
   fix(agent): resolve memory leak

Tools and Resources

Editor Integration

VS Code - Conventional Commits extension:

{
  "conventionalCommits.scopes": [
    "auth",
    "api",
    "cli",
    "sdk",
    "db",
    "ci",
    "docs",
    "agent",
    "core"
  ]
}

IntelliJ/WebStorm - Git Commit Template plugin

Vim - vim-conventional-commits plugin

Git Aliases

Add to .gitconfig:

[alias]
  cf = "!f() { git commit -m \"feat: $1\"; }; f"
  cx = "!f() { git commit -m \"fix: $1\"; }; f"
  cd = "!f() { git commit -m \"docs: $1\"; }; f"
  cc = "!f() { git commit -m \"chore: $1\"; }; f"

Usage:

git cf "add OAuth2 support"  # † feat: add OAuth2 support
git cx "resolve memory leak"  # † fix: resolve memory leak

Commit Message Template

Create .gitmessage:

# <type>(<scope>): <subject>
#
# <body>
#
# <footer>
#
# Types: feat, fix, docs, style, refactor, perf, test, chore, ci, revert
# Scopes: auth, api, cli, sdk, db, ci, docs, agent, core, config
#
# Examples:
#   feat(auth): add OAuth2 support
#   fix(api): resolve memory leak
#   docs: update README

Configure:

git config commit.template .gitmessage

Resources

• Conventional Commits Specification
• commitlint Documentation
• Semantic Release
• Angular Commit Guidelines

See Also

• Semantic Versioning
• Automated Version Bumping
• Changelog Generation
• GitLab Releases
• Release Branches