Git Workflow - GitHub Flow Implementation

⭐ PRIMARY WORKFLOW - Use this for most development tasks. For scheduled releases, see Git Branching Strategy (GitFlow).

Overview

AzmX follows GitHub Flow - a simple, branch-based workflow optimized for continuous deployment and our 15-person engineering team.

Pull Requests in the Bigger Picture

This document focuses on steps 2-5 of your complete development lifecycle. Pull requests are part of a larger flow from task assignment to QA approval.

Your complete development lifecycle:

Task assigned → IN PROGRESS
Create branch (from ClickUp or manually) ← Git workflow starts here
Develop & test locally
Create PR → Automated: PR READY ✅
Merge PR → Automated: PR MERGED ✅ ← Git workflow completes here
Auto-deploy to dev (5-10 minutes)
Test in dev → READY FOR QA
QA testing → UNDER TESTING
QA approval → DONE

This document covers: Git operations, branch management, and PR process (steps 2-5).

For complete workflow: See GitHub-ClickUp Workflow: Complete Development Lifecycle.

Why GitHub Flow?

Based on 2025 best practices research for teams our size: - Simplicity: Easier to understand and implement than GitFlow - Continuous Deployment: Aligns with our DevOps practices - Team Size: Optimal for mid-sized teams (10-20 developers) - Flexibility: Supports rapid iteration and feature deployment

Workflow Overview

graph LR
    A[main branch] --> B[create feature branch]
    B --> C[develop feature]
    C --> D[open pull request]
    D --> E[discuss & review]
    E --> F[merge to main]
    F --> G[deploy]
    G --> H[delete feature branch]

Branch Strategy

Main Branch

Purpose: Production-ready code
Protection: Always protected, requires PR review
Deployment: Auto-deploy to production on merge
Naming: main (primary branch)

Feature Branches

Source: Created from main
Lifetime: Short-lived (ideally < 1 week)
Purpose: Single feature or bug fix
Naming Convention: See Git Branch Naming for detailed conventions

Commit Message Standards

AzmX follows Conventional Commits specification for standardized commit messages that enable automated versioning and changelog generation.

Quick Reference:

feat(scope): add new feature
fix(scope): resolve bug issue
docs(scope): update documentation

For comprehensive commit message guidelines, see Git Commit Standards.

Pull Request Process

1. Create Pull Request

# Create and switch to feature branch
git checkout -b feature/user-dashboard

# Make changes and commit
git add .
git commit -m "feat(dashboard): add user analytics component"

# Push to remote
git push -u origin feature/user-dashboard

# Create PR through GitHub interface

2. PR Title and Description

## Pull Request Title
feat(dashboard): Add user analytics component

## Description
Implements user analytics dashboard with the following features:
- Real-time data visualization
- Export functionality
- Responsive design for mobile

## Changes
- [x] Create analytics component
- [x] Add data visualization charts
- [x] Implement export functionality
- [x] Add responsive CSS

## Testing
- [x] Unit tests added
- [x] Integration tests passing
- [x] Manual testing completed

## Screenshots
[Add relevant screenshots]

## ClickUp Task
CU-abc123

## Related Issues
Closes #CU-abc123
Related to #CU-def456

Note: For ClickUp integration, use task ID format CU-abc123 and include Closes #CU-abc123 in Related Issues. This automatically links PR to ClickUp task and updates status on merge. See GitHub-ClickUp Workflow.

3. Code Review Requirements

Automated Checks

[ ] All CI/CD tests pass
[ ] SonarQube quality gate passes
[ ] No security vulnerabilities detected
[ ] Code coverage meets threshold

Manual Review Checklist

[ ] Code follows team standards
[ ] Functionality works as expected
[ ] Security considerations addressed
[ ] Performance impact considered
[ ] Documentation updated if needed

Review Assignments

Frontend PRs: Reviewed by Frontend Lead + 1 peer
Backend PRs: Reviewed by Backend Lead + 1 peer
Cross-functional PRs: Reviewed by both leads
Critical fixes: Reviewed by 2+ senior developers

4. Merge Strategy

Merge Types

Squash and Merge: Default for feature branches
Regular Merge: For release branches or collaborative features
Rebase and Merge: For small, clean commits

Auto-merge Conditions

All required checks pass
At least 1 approval from required reviewers
No requested changes pending
Branch is up to date with main

Deployment Workflow

Continuous Deployment Pipeline

graph TB
    A[PR Merged to main] --> B[GitHub Actions Triggered]
    B --> C[Run Tests]
    C --> D[Build Application]
    D --> E[Deploy to Staging]
    E --> F[Run E2E Tests]
    F --> G[Deploy to Production]
    G --> H[Health Checks]
    H --> I[Notify Team]

Environment Strategy

Development: Local development environment
Staging: Auto-deploy from main branch
Production: Auto-deploy after staging validation

Hotfix Process

Critical Production Issues

Create hotfix branch from main
Implement fix with minimal changes
Fast-track review (single approver)
Deploy immediately to production
Post-mortem if needed

# Hotfix workflow
git checkout main
git pull origin main
git checkout -b hotfix/critical-payment-fix

# Make fix
git commit -m "hotfix(payment): fix critical gateway timeout"

# Push and create PR
git push -u origin hotfix/critical-payment-fix
# Create PR with "HOTFIX" label for priority review

Release Management

Semantic Versioning Strategy

AzmX follows Semantic Versioning 2.0.0 for all releases:

Version Format: MAJOR.MINOR.PATCH - MAJOR: Breaking changes (v1.0.0 → v2.0.0) - MINOR: New features, backward compatible (v1.1.0 → v1.2.0) - PATCH: Bug fixes, backward compatible (v1.2.1 → v1.2.2)

# Version examples
v1.0.0    # Initial release
v1.1.0    # Added user dashboard feature
v1.1.1    # Fixed login bug
v2.0.0    # New API with breaking changes

Release Process

GitHub Flow Releases

Frequency: Continuous deployment (multiple per day)
Process: Automatic deployment from main branch
Versioning: Auto-increment patch version for hotfixes

For Complex Projects

For projects requiring structured release management with parallel development, see our comprehensive Git Branching Strategy - GitFlow guide.

Automated Release Notes

Auto-generated from conventional commits:

## v1.2.0 (2025-01-20)

### ✨ Features
- feat(auth): add JWT token authentication (#123)
- feat(dashboard): implement user analytics (#124)

### 🐛 Bug Fixes
- fix(payment): resolve gateway timeout issue (#125)

### 🔧 Maintenance
- chore(deps): update Django to version 5.2 (#126)

### 📖 Documentation
- docs(api): update authentication endpoints (#127)

Git Configuration

Required Git Configuration

# Set up user information
git config --global user.name "Your Name"
git config --global user.email "[email protected]"

# Set up commit signing (optional but recommended)
git config --global commit.gpgsign true
git config --global user.signingkey YOUR_GPG_KEY

# Set up aliases
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.unstage 'reset HEAD --'
git config --global alias.last 'log -1 HEAD'

Pre-commit Hooks

# Install pre-commit
pip install pre-commit

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

  - repo: https://github.com/psf/black
    rev: 23.1.0
    hooks:
      - id: black

  - repo: https://github.com/pycqa/flake8
    rev: 6.0.0
    hooks:
      - id: flake8

# Install hooks
pre-commit install

Conflict Resolution

Merge Conflicts

Pull latest main

git checkout main
git pull origin main
git checkout feature/your-branch
git merge main

Resolve conflicts

# Edit conflicted files
# Remove conflict markers
# Test the resolution
git add .
git commit -m "resolve merge conflicts with main"

Alternative: Rebase

git checkout feature/your-branch
git rebase main
# Resolve conflicts if any
git rebase --continue

Team Collaboration

Shared Branches

For collaborative features involving multiple developers:

# Create shared feature branch
git checkout -b feature/shared-component

# Multiple developers work on sub-branches
git checkout -b feature/shared-component-frontend
git checkout -b feature/shared-component-backend

# Merge sub-branches to shared branch
# Finally merge shared branch to main

Code Review Culture

Best Practices

Constructive feedback: Focus on code, not person
Explain reasoning: Why changes are needed
Suggest solutions: Don't just point out problems
Respond promptly: Review within 24 hours
Learn from reviews: Both reviewer and author

Review Comments

# Good review comments
"Consider using const instead of let here for immutability"
"This could benefit from error handling for the API call"
"Great implementation! Consider adding a unit test for this edge case"

# Avoid
"This is wrong"
"Bad code"
"Change this"

Monitoring and Analytics

Git Metrics

Track team performance: - PR cycle time: Time from creation to merge - Review turnaround: Time to first review - Code quality: SonarQube metrics per PR - Deployment frequency: Daily deployment rate

GitHub Actions Integration

# .github/workflows/ci.yml
name: CI/CD Pipeline
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: |
          python -m pytest
          npm test
      - name: SonarQube analysis
        uses: sonarqube-quality-gate-action@master

Troubleshooting

Common Issues

Large Files

# Remove large file from history
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch path/to/large/file' \
  --prune-empty --tag-name-filter cat -- --all

Reset Branch

# Reset feature branch to match main
git checkout feature/your-branch
git reset --hard origin/main
git push --force-with-lease origin feature/your-branch

Recover Deleted Branch

# Find the commit hash
git reflog

# Recreate branch
git checkout -b recovered-branch COMMIT_HASH