git-workflow-standards

name	git-workflow-standards
description	Automatically applies when working with git. Ensures conventional commits, branch naming, PR templates, release workflow, and version control best practices.
category	velocity

Git Workflow Standards

When working with git, follow these patterns for consistent, professional version control.

Trigger Keywords: git, commit, branch, pull request, PR, merge, release, version control, conventional commits, semantic versioning

Agent Integration: Used by backend-architect, devops-engineer, release-manager

✅ Correct Pattern: Conventional Commits

# Format: <type>(<scope>): <description>
#
# Types:
# - feat: New feature
# - fix: Bug fix
# - docs: Documentation only
# - style: Code style (formatting, semicolons)
# - refactor: Code restructuring
# - perf: Performance improvement
# - test: Adding tests
# - build: Build system changes
# - ci: CI configuration changes
# - chore: Other changes (dependencies, etc.)

# Examples:

# Feature commits
feat(auth): add JWT authentication
feat(api): add user profile endpoint
feat: implement password reset flow

# Bug fix commits
fix(database): resolve connection pool leak
fix(api): correct status code for validation errors
fix: handle null values in user input

# Documentation commits
docs(readme): update installation instructions
docs: add API documentation
docs(contributing): add code review guidelines

# Performance commits
perf(query): optimize user search query
perf: reduce memory usage in data processing

# Refactoring commits
refactor(models): simplify user model structure
refactor: extract common validation logic

# Breaking changes (add !)
feat(api)!: change response format to JSON:API spec
fix(auth)!: remove deprecated login endpoint

# With body and footer
feat(payments): add Stripe integration

Implement Stripe payment processing with webhooks
for subscription management.

BREAKING CHANGE: Payment API now requires Stripe account
Closes #123

Branch Naming Convention

# Format: <type>/<short-description>
#
# Types:
# - feature/ - New features
# - bugfix/  - Bug fixes
# - hotfix/  - Urgent production fixes
# - release/ - Release branches
# - docs/    - Documentation changes

# Examples:

# Feature branches
git checkout -b feature/user-authentication
git checkout -b feature/add-search-endpoint
git checkout -b feature/implement-caching

# Bug fix branches
git checkout -b bugfix/fix-login-redirect
git checkout -b bugfix/resolve-memory-leak
git checkout -b bugfix/correct-email-validation

# Hotfix branches (for production)
git checkout -b hotfix/critical-security-patch
git checkout -b hotfix/fix-payment-processing

# Release branches
git checkout -b release/v1.2.0
git checkout -b release/v2.0.0-beta.1

# Documentation branches
git checkout -b docs/update-api-reference
git checkout -b docs/add-deployment-guide

# Include issue number when applicable
git checkout -b feature/123-user-profile
git checkout -b bugfix/456-fix-crash

Pull Request Template

# .github/pull_request_template.md

## Description

Brief description of what this PR does.

Fixes #(issue)

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Changes Made

- Change 1: Description
- Change 2: Description
- Change 3: Description

## Testing

### Test Plan

Describe how you tested these changes:

1. Step 1
2. Step 2
3. Step 3

### Test Results

- [ ] All existing tests pass
- [ ] New tests added and passing
- [ ] Manual testing completed

## Checklist

- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published

## Screenshots (if applicable)

Add screenshots here if UI changes were made.

## Additional Notes

Any additional information that reviewers should know.

## Breaking Changes

If this PR introduces breaking changes, describe them here and update CHANGELOG.md.

Commit Message Template

# .gitmessage

# <type>(<scope>): <subject>
#
# <body>
#
# <footer>

# Types:
# - feat:     New feature
# - fix:      Bug fix
# - docs:     Documentation
# - style:    Formatting
# - refactor: Code restructuring
# - perf:     Performance
# - test:     Tests
# - build:    Build system
# - ci:       CI changes
# - chore:    Other changes
#
# Scope: Component affected (api, database, auth, etc.)
#
# Subject: Imperative, present tense, no period
#
# Body: Explain what and why, not how
#
# Footer: Issue references, breaking changes

# Configure Git to use this template:
# git config commit.template .gitmessage

Release Workflow

# Semantic Versioning: MAJOR.MINOR.PATCH
# - MAJOR: Breaking changes
# - MINOR: New features (backwards compatible)
# - PATCH: Bug fixes (backwards compatible)

# 1. Create release branch
git checkout -b release/v1.2.0

# 2. Update version numbers
# - pyproject.toml
# - __version__ in code
# - CHANGELOG.md

# 3. Update CHANGELOG.md
cat >> CHANGELOG.md << EOF
## [1.2.0] - 2025-01-15

### Added
- New feature 1
- New feature 2

### Changed
- Modified behavior 1

### Fixed
- Bug fix 1
- Bug fix 2

### Security
- Security fix 1
EOF

# 4. Commit version bump
git add .
git commit -m "chore(release): bump version to 1.2.0"

# 5. Merge to main
git checkout main
git merge release/v1.2.0

# 6. Create and push tag
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

# 7. Delete release branch
git branch -d release/v1.2.0
git push origin --delete release/v1.2.0

GitHub Actions for Release

# .github/workflows/release.yml
name: Release

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install build twine

      - name: Build package
        run: python -m build

      - name: Publish to PyPI
        env:
          TWINE_USERNAME: __token__
          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
        run: twine upload dist/*

      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          body: |
            See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details.
          draft: false
          prerelease: false

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
- Features added but not yet released

### Changed
- Changes in existing functionality

### Deprecated
- Soon-to-be removed features

### Removed
- Removed features

### Fixed
- Bug fixes

### Security
- Vulnerability fixes

## [1.2.0] - 2025-01-15

### Added
- JWT authentication for API endpoints
- User profile endpoint with avatar support
- Rate limiting middleware

### Changed
- Updated Pydantic to v2.5.0
- Improved error messages in validation

### Fixed
- Fixed memory leak in database connection pool
- Corrected timezone handling in timestamps

### Security
- Updated dependencies to fix CVE-2024-1234

## [1.1.0] - 2025-01-01

### Added
- Initial API implementation
- Database migrations with Alembic
- User authentication

[Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/repo/releases/tag/v1.1.0

Git Hooks

# .git/hooks/pre-commit
#!/bin/bash
# Pre-commit hook to run linting and tests

echo "Running pre-commit checks..."

# Run linting
echo "Running ruff..."
ruff check .
if [ $? -ne 0 ]; then
    echo "Ruff checks failed. Please fix linting errors."
    exit 1
fi

# Run formatter
echo "Running black..."
black --check .
if [ $? -ne 0 ]; then
    echo "Code formatting issues found. Run: black ."
    exit 1
fi

# Run type checking
echo "Running mypy..."
mypy .
if [ $? -ne 0 ]; then
    echo "Type checking failed. Please fix type errors."
    exit 1
fi

# Run tests
echo "Running tests..."
pytest tests/ -v
if [ $? -ne 0 ]; then
    echo "Tests failed. Please fix failing tests."
    exit 1
fi

echo "All pre-commit checks passed!"
exit 0

# Make executable:
# chmod +x .git/hooks/pre-commit

Pre-commit Configuration

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
      - id: check-merge-conflict

  - repo: https://github.com/psf/black
    rev: 24.1.0
    hooks:
      - id: black
        language_version: python3.11

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.0
    hooks:
      - id: ruff
        args: [--fix, --exit-non-zero-on-fix]

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        additional_dependencies: [types-all]

# Install: pre-commit install
# Run manually: pre-commit run --all-files

GitIgnore Template

# .gitignore for Python projects

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# Virtual environments
venv/
env/
ENV/
.venv

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# Testing
.pytest_cache/
.coverage
htmlcov/
.tox/

# Environment
.env
.env.local
.env.*.local

# Logs
*.log

# Database
*.db
*.sqlite3

# OS
.DS_Store
Thumbs.db

# Project specific
/data/
/tmp/

❌ Anti-Patterns

# ❌ Vague commit messages
git commit -m "fix stuff"
git commit -m "update code"
git commit -m "changes"

# ✅ Better: Descriptive commits
git commit -m "fix(auth): resolve JWT token expiration issue"
git commit -m "feat(api): add pagination to user list endpoint"


# ❌ Committing to main directly
git checkout main
git commit -m "quick fix"  # Bad practice!

# ✅ Better: Use feature branch
git checkout -b bugfix/fix-issue
git commit -m "fix: resolve issue"
# Then create PR


# ❌ Large commits with mixed changes
git add .
git commit -m "add feature and fix bugs and update docs"

# ✅ Better: Separate commits
git add feature.py
git commit -m "feat: add new feature"
git add bugfix.py
git commit -m "fix: resolve bug"
git add docs/
git commit -m "docs: update documentation"


# ❌ No branch naming convention
git checkout -b my-changes
git checkout -b fix
git checkout -b update-stuff

# ✅ Better: Consistent naming
git checkout -b feature/add-authentication
git checkout -b bugfix/fix-validation-error

Best Practices Checklist

• ✅ Use conventional commit format
• ✅ Follow branch naming convention
• ✅ Create descriptive PR descriptions
• ✅ Keep commits small and focused
• ✅ Write commits in imperative mood
• ✅ Reference issues in commits
• ✅ Use semantic versioning
• ✅ Maintain CHANGELOG.md
• ✅ Set up pre-commit hooks
• ✅ Review your own code before requesting review
• ✅ Keep PR size manageable (<400 lines)
• ✅ Squash/rebase before merging

Auto-Apply

When working with git:

1. Use conventional commit format: type(scope): description
2. Create branch with type prefix: feature/, bugfix/
3. Write descriptive PR descriptions with checklist
4. Update CHANGELOG.md for releases
5. Tag releases with semantic versions
6. Set up pre-commit hooks
7. Keep commits focused and atomic

Related Skills

• code-review-framework - For PR reviews
• python-packaging - For releases
• dependency-management - For version management