git-conventions

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:

feat: add user authentication

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

Closes #123

Breaking change:

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:

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:

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 "

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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# 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, merge to main
# Deploy from main

Trunk-Based Development

Single main branch:

• Short-lived feature branches (< 2 days)
• Frequent integration to main
• Feature flags for incomplete features
• Continuous integration

Workflow:

# Create short-lived branch
git checkout -b update-api-docs
git push -u origin update-api-docs

# Make small, incremental changes
git commit -m "docs: update API endpoint documentation"
git push origin update-api-docs

# Immediately create PR and merge (same day)
# Main branch always deployable with feature flags

Pull Request Conventions

PR Title Format

Use Conventional Commits format:

feat(auth): add OAuth2 provider support
fix(api): resolve rate limiting edge case
docs: update installation guide

PR Description Template

## Summary
Brief description of changes and motivation.

## Changes
- Bullet list of specific changes
- Reference architecture decisions
- Note any breaking changes

## Testing
- Unit tests added/updated
- Integration tests passed
- Manual testing performed

## Screenshots (if applicable)
[Add screenshots for UI changes]

## Related Issues
Closes #123
Refs #456

## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] Changelog updated
- [ ] Breaking changes documented
- [ ] Code reviewed by team

Review Guidelines

Reviewer checklist:

• Code follows style guide
• Commit messages follow conventions
• Tests are comprehensive
• Documentation is updated
• No security vulnerabilities
• Performance considerations addressed
• Breaking changes are justified

Changelog Management

Keep a Changelog Format

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- User authentication with JWT tokens
- API rate limiting middleware

### Changed
- Updated database schema for better performance

### Deprecated
- Old authentication endpoint (use /api/v2/auth instead)

### Removed
- Legacy XML API support

### Fixed
- Memory leak in cache implementation
- Race condition in concurrent requests

### Security
- Patch for SQL injection vulnerability

## [1.2.0] - 2024-03-15

### Added
- Real-time notifications system
- User profile customization

### Fixed
- Login redirect loop issue
- Session timeout handling

## [1.1.0] - 2024-02-01

### Added
- Search functionality
- Export to CSV feature

### Changed
- Improved UI responsiveness

Automated Changelog

Use tools like:

• conventional-changelog - Generate changelog from commits
• release-please - Automated releases and changelog
• semantic-release - Fully automated version management

Best Practices

1. Commit Often: Small, focused commits are easier to review and revert
2. Write Clear Messages: Future you will thank present you
3. One Concern Per Commit: Each commit should address one logical change
4. Test Before Committing: Ensure code works before committing
5. Reference Issues: Link commits to issue tracker
6. Review Your Own Changes: Use git diff --staged before committing
7. Keep History Clean: Rebase feature branches to keep linear history
8. Sign Your Commits: Use GPG signing for verified commits
9. Use .gitignore Properly: Never commit sensitive or generated files
10. Document Conventions: Keep team conventions in repository docs

Team Workflow Examples

Small Team (2-5 developers)

# Simplified workflow
- Direct commits to main (with PR reviews)
- Feature branches for major changes
- Tags for releases
- Linear history preferred

Medium Team (5-20 developers)

# Git Flow variant
- Protected main and develop branches
- Feature branches required
- Release branches for versions
- Hotfix workflow for emergencies
- Squash merge for clean history

Large Team (20+ developers)

# Trunk-based with feature flags
- Protected main branch
- Very short-lived feature branches
- Feature flags for incomplete work
- Automated testing and deployment
- Multiple daily integrations

Resources

Additional guides and templates are available in the assets/ directory:

• templates/ - Commit message and PR templates
• examples/ - Real-world workflow examples
• tools/ - Git hooks and automation scripts

See references/ directory for:

• Conventional Commits specification
• Semantic Versioning documentation
• Git Flow and GitHub Flow guides
• Keep a Changelog standards