git-conventions

What this skill does

# Git Conventions Skill

This skill provides comprehensive guidance on git conventions, workflow best practices, and standardized commit formats to maintain clean, readable repository history.

## When to Use

Activate this skill when:
- Writing commit messages following standards
- Establishing team git workflows
- Setting up branch naming conventions
- Implementing Conventional Commits
- Creating changelog automation
- Code review for git hygiene
- Onboarding team members on git practices

## Conventional Commits

### Format

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

[optional body]

[optional footer(s)]
```

### Commit Types

**Primary Types:**
- **feat**: New feature for the user
- **fix**: Bug fix for the user
- **docs**: Documentation only changes
- **style**: Code style changes (formatting, missing semi-colons, etc)
- **refactor**: Code change that neither fixes a bug nor adds a feature
- **perf**: Performance improvements
- **test**: Adding or correcting tests
- **build**: Changes to build system or dependencies
- **ci**: Changes to CI configuration files and scripts
- **chore**: Other changes that don't modify src or test files
- **revert**: Reverts a previous commit

### Examples

**Simple commit:**
```bash
feat: add user authentication

Implement JWT-based authentication system with refresh tokens.
Includes middleware for protected routes.

Closes #123
```

**Breaking change:**
```bash
feat!: redesign API response format

BREAKING CHANGE: API now returns data in camelCase instead of snake_case.
Migration guide available in docs/migration-v2.md.

Refs: #456
```

**With scope:**
```bash
fix(auth): resolve token expiration edge case

Token validation now properly handles timezone offsets.
Adds retry logic for expired tokens within 5-minute grace period.
```

**Multiple paragraphs:**
```bash
refactor(database): optimize query performance

- Add indexes on frequently queried columns
- Implement connection pooling
- Cache common queries with Redis
- Reduce N+1 queries in user associations

Performance improved by 60% in production testing.

Reviewed-by: Jane Doe <[email protected]>
Refs: #789
```

### Commit Message Rules

1. **Subject line:**
   - Use imperative mood ("add" not "added" or "adds")
   - No capitalization of first letter
   - No period at the end
   - Maximum 50 characters (soft limit)
   - Separate from body with blank line

2. **Body:**
   - Wrap at 72 characters
   - Explain what and why, not how
   - Use bullet points for multiple items
   - Reference issues and PRs

3. **Footer:**
   - Breaking changes start with "BREAKING CHANGE:"
   - Reference issues: "Closes #123", "Fixes #456", "Refs #789"
   - Co-authors: "Co-authored-by: Name <email>"

## Branch Naming Conventions

### Format Pattern

```
<type>/<issue-number>-<short-description>
```

### Branch Types

**Common prefixes:**
- `feature/` or `feat/` - New features
- `fix/` or `bugfix/` - Bug fixes
- `hotfix/` - Urgent production fixes
- `release/` - Release preparation
- `docs/` - Documentation updates
- `refactor/` - Code refactoring
- `test/` - Test additions or fixes
- `chore/` - Maintenance tasks
- `experimental/` or `spike/` - Proof of concepts

### Examples

```bash
# Feature branches
feature/123-user-authentication
feat/456-add-payment-gateway
feature/oauth-integration

# Bug fix branches
fix/789-resolve-memory-leak
bugfix/login-redirect-loop
fix/456-null-pointer-exception

# Hotfix branches
hotfix/critical-security-patch
hotfix/production-database-issue

# Release branches
release/v1.2.0
release/2024-Q1

# Documentation branches
docs/api-reference-update
docs/123-add-contributing-guide

# Refactor branches
refactor/database-layer
refactor/456-simplify-auth-flow

# Experimental branches
experimental/graphql-api
spike/performance-optimization
```

### Branch Naming Rules

1. **Use hyphens** for word separation (not underscores)
2. **Lowercase only** (avoid capitals)
3. **Keep it short** but descriptive (max 50 characters)
4. **Include issue number** when applicable
5. **Avoid special characters** except hyphens and forward slashes
6. **No trailing slashes**
7. **Be consistent** within your team

## Protected Branch Strategy

### Main Branches

**main/master:**
- Production-ready code
- Always deployable
- Protected with required reviews
- No direct commits
- Merge only from release or hotfix branches

**develop:**
- Integration branch for features
- Pre-production testing
- Protected with CI checks
- Merge target for feature branches

**staging:**
- Pre-production environment
- QA testing branch
- Mirror of production with new features

### Protection Rules

```yaml
# Example GitHub branch protection
main:
  require_pull_request_reviews:
    required_approving_review_count: 2
    dismiss_stale_reviews: true
    require_code_owner_reviews: true

  require_status_checks:
    strict: true
    contexts:
      - continuous-integration
      - code-quality
      - security-scan

  enforce_admins: true
  require_linear_history: true
  allow_force_pushes: false
  allow_deletions: false
```

## Semantic Versioning

### Version Format

```
MAJOR.MINOR.PATCH[-prerelease][+build]
```

**Examples:**
- `1.0.0` - Initial release
- `1.2.3` - Minor update with patches
- `2.0.0-alpha.1` - Pre-release alpha
- `1.5.0-rc.2+20240321` - Release candidate with build metadata

### Version Increment Rules

**MAJOR (X.0.0):**
- Breaking changes
- API incompatibilities
- Major redesigns
- Removal of deprecated features

**MINOR (x.Y.0):**
- New features (backward compatible)
- Deprecated features (still functional)
- Substantial internal changes

**PATCH (x.y.Z):**
- Bug fixes
- Security patches
- Performance improvements
- Documentation updates

### Git Tags for Versions

```bash
# Create annotated tag
git tag -a v1.2.3 -m "Release version 1.2.3

- Add user authentication
- Fix memory leak in cache
- Improve API performance"

# Push tags to remote
git push origin v1.2.3

# Push all tags
git push --tags

# Create pre-release tag
git tag -a v2.0.0-beta.1 -m "Beta release for v2.0.0"

# Delete tag
git tag -d v1.2.3
git push origin :refs/tags/v1.2.3
```

## Workflow Patterns

### Git Flow

**Branch structure:**
- `main` - Production releases
- `develop` - Next release development
- `feature/*` - New features
- `release/*` - Release preparation
- `hotfix/*` - Emergency fixes

**Feature workflow:**
```bash
# Start feature
git checkout develop
git pull origin develop
git checkout -b feature/123-new-feature

# Work on feature
git add .
git commit -m "feat: implement user authentication"

# Finish feature
git checkout develop
git pull origin develop
git merge --no-ff feature/123-new-feature
git push origin develop
git branch -d feature/123-new-feature
```

**Release workflow:**
```bash
# Start release
git checkout develop
git checkout -b release/v1.2.0

# Prepare release (bump version, update changelog)
git commit -m "chore: prepare release v1.2.0"

# Merge to main
git checkout main
git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"

# Merge back to develop
git checkout develop
git merge --no-ff release/v1.2.0

# Cleanup
git branch -d release/v1.2.0
```

**Hotfix workflow:**
```bash
# Start hotfix from main
git checkout main
git checkout -b hotfix/critical-bug

# Fix and commit
git commit -m "fix: resolve critical security vulnerability"

# Merge to main
git checkout main
git merge --no-ff hotfix/critical-bug
git tag -a v1.2.1 -m "Hotfix v1.2.1"

# Merge to develop
git checkout develop
git merge --no-ff hotfix/critical-bug

# Cleanup
git branch -d hotfix/critical-bug
```

### GitHub Flow

**Simplified workflow:**
- `main` - Always deployable
- `feature/*` - All changes in feature branches

**Workflow:**
```bash
# Create feature branch
git checkout -b feature/add-logging
git push -u origin feature/add-logging

# Make changes and commit
git commit -m "feat: add structured logging"
git push origin feature/add-logging

# Open pull request on GitHub
# After review and CI passes, merg