conventional-commits

# Conventional Commits

This skill provides guidance for writing Git commits that follow the Conventional Commits specification (v1.0.0).

## Purpose

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, which makes it easier to understand project changes and improve collaboration.

## When to Use This Skill

Use this skill when:
- Creating Git commits
- Reviewing commit messages in PRs
- Writing clear, structured commit messages
- Collaborating on projects with multiple contributors

## Commit Message Structure

### Basic Format

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Examples

```
feat: add user authentication
feat(api): add JWT token generation
fix: resolve memory leak in image processor
docs: update README with setup instructions
refactor(database): optimize user query performance
```

## Commit Types

### Primary Types

**feat** - A new feature for the user
```
feat: add export to PDF functionality
feat(api): add webhook signature verification
```

**fix** - A bug fix for the user
```
fix: resolve login redirect loop
fix(api): handle null response from GitHub webhook
```

**docs** - Documentation only changes
```
docs: update API endpoint documentation
docs(readme): add troubleshooting section
```

**style** - Changes that don't affect code meaning (formatting, whitespace)
```
style: format code with StandardRB
style(css): update button padding
```

**refactor** - Code change that neither fixes a bug nor adds a feature
```
refactor: extract user validation to service object
refactor(models): simplify tenant scoping logic
```

**perf** - Performance improvements
```
perf: add database index for user lookups
perf(queries): reduce N+1 queries in artifacts index
```

**test** - Adding or updating tests
```
test: add specs for user authentication
test(integration): add webhook processing tests
```

**chore** - Changes to build process, dependencies, or maintenance
```
chore: update Rails to 7.2.0
chore(deps): bump sidekiq from 7.1.0 to 7.2.0
```

### Additional Types (Less Common)

**build** - Changes to build system or dependencies
```
build: configure Docker for production
build(webpack): update asset compilation settings
```

**ci** - Changes to CI configuration
```
ci: add security scanning to GitHub Actions
ci(tests): run RSpec in parallel
```

**revert** - Reverts a previous commit
```
revert: revert "feat: add export feature"

This reverts commit abc123.
```

## Scope (Optional)

Scope provides additional context about what part of the codebase changed:

```
feat(auth): add two-factor authentication
fix(api): handle rate limit errors
docs(contributing): update PR guidelines
refactor(services): extract common validation logic
```

**Common scope examples:**
- `auth` - Authentication/authorization
- `api` - API endpoints
- `ui` - User interface components
- `database` or `db` - Database models/migrations
- `services` - Service objects
- `jobs` - Background jobs
- `tests` - Test suite
- `deps` - Dependencies
- `config` - Configuration changes
- `docs` - Documentation

Choose scopes that match your project's architecture and domain areas.

## Description

The description is a short summary of the code change:

**Rules:**
- Use imperative, present tense: "add" not "added" or "adds"
- Don't capitalize first letter
- No period (.) at the end
- Keep under 72 characters (ideally under 50)

**Good descriptions:**
```
add user profile page
fix memory leak in file upload
update email templates for notifications
remove deprecated API endpoint
```

**Bad descriptions:**
```
Added user profile page          # Past tense
Fix Memory Leak In File Upload   # Capitalized
Updated email templates.          # Period at end
Lots of changes to the codebase   # Vague
```

## Body (Optional)

The body provides additional context about the change:

**When to include a body:**
- Complex changes needing explanation
- Non-obvious design decisions
- Breaking changes
- Migration instructions

**Format:**
- Separate from description with blank line
- Use imperative mood like description
- Wrap at 72 characters
- Can include multiple paragraphs

**Example:**
```
feat(api): add webhook signature verification

Add HMAC-SHA256 signature verification for all incoming webhooks
to prevent unauthorized access and replay attacks.

The signature is validated using a secret key stored per
installation. Requests with invalid signatures are rejected
with a 401 response.
```

## Footer (Optional)

Footers provide metadata about the commit:

### Breaking Changes

Use `BREAKING CHANGE:` footer for incompatible API changes:

```
feat(api): change authentication endpoint

BREAKING CHANGE: The /auth endpoint now requires a client_id parameter.
Update all API clients to include client_id in authentication requests.
```

Or use `!` after type/scope:

```
feat!: change authentication endpoint
feat(api)!: remove deprecated /login endpoint
```

### Issue References

Reference issues and pull requests:

```
fix(auth): resolve session timeout bug

Fixes #123
Closes #456
Related to #789
```

**Common reference types:**
- `Fixes #123` - Closes the issue
- `Closes #123` - Closes the issue
- `Resolves #123` - Closes the issue
- `Related to #123` - References without closing
- `See also #123` - Additional reference

### Co-authors

Credit multiple contributors:

```
feat: add data export feature

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

## Complete Examples

### Simple Feature

```
feat: add password reset functionality
```

### Feature with Scope

```
feat(api): add rate limiting for endpoints
```

### Bug Fix with Body

```
fix(api): handle rate limit errors from GitHub

When GitHub API returns 429 status, retry the request
with exponential backoff up to 3 attempts before failing.

Fixes #234
```

### Breaking Change

```
feat(api)!: redesign webhook payload structure

BREAKING CHANGE: Webhook payloads now use a nested structure.

Before:
{
  "event": "issue.created",
  "data": {...}
}

After:
{
  "type": "issue",
  "action": "created",
  "payload": {...}
}

Clients must update their webhook handlers to use the new structure.
```

### Refactoring

```
refactor(services): extract validation to concern

Move common validation logic from multiple services into
a shared ValidationConcern module. No behavior changes.
```

### Multiple Footers

```
fix(auth): resolve concurrent login race condition

Add database-level locking to prevent race condition when
multiple login attempts occur simultaneously for the same user.

Fixes #567
Related to #432
Reviewed-by: Jane Doe <jane@example.com>
```

## Best Practices

### Do:
✅ Use present tense imperative mood ("add" not "added")
✅ Keep first line under 50 characters when possible
✅ Reference issues/PRs in footer
✅ Explain "why" in body, not "what" (code shows what)
✅ Break up large changes into multiple commits
✅ Make commits atomic (one logical change per commit)

### Don't:
❌ Use vague descriptions ("fix stuff", "updates")
❌ Combine multiple unrelated changes in one commit
❌ Capitalize first letter of description
❌ End description with period
❌ Use past tense ("added", "fixed")
❌ Commit broken code (each commit should work)

## Summary

Conventional Commits provide:
- ✅ Clear, consistent commit history
- ✅ Better collaboration through explicit intent
- ✅ Easier code review and git history navigation
- ✅ Improved project documentation through structured messages

**Key formula:**
```
<type>(<scope>): <description>

[body]

[footer]
```

For detailed examples and edge cases, see `references/commit-examples.md`.