Git Workflow - Tectonica-Campaigns-Solutions/Tectonica-Dev-Team-Standards-Practices GitHub Wiki

Git Workflow

Overview

This guide defines our Git workflow standards for team collaboration. It covers branching strategies, commit conventions, pull request processes, and release management to ensure smooth development and deployment cycles.

Table of Contents

Branching Strategy

Main Branches

main (production)
  └── develop (integration)
       ├── feature/user-authentication
       ├── feature/payment-integration
       ├── bugfix/header-alignment
       └── hotfix/critical-security-fix

Branch Types

  1. main

    • Production-ready code
    • Protected branch
    • Deployment triggers on merge
    • Tagged for releases

  2. develop

    • Integration branch
    • Latest development changes
    • Base for feature branches
    • Merged to main for releases

  3. feature/

    • New features or enhancements
    • Created from develop
    • Merged back to develop
    • Deleted after merge

  4. bugfix/

    • Non-critical bug fixes
    • Created from develop
    • Merged back to develop
    • Deleted after merge

  5. hotfix/

    • Critical production fixes
    • Created from main
    • Merged to main AND develop
    • Deleted after merge

  6. release/

    • Release preparation
    • Created from develop
    • Merged to main and develop
    • Used for final testing

Branch Naming Conventions

Format

type/issue-number-brief-description

Examples

# Features
feature/123-user-registration
feature/456-payment-gateway
feature/789-dashboard-redesign

# Bug fixes
bugfix/321-fix-login-error
bugfix/654-mobile-menu-overlap
bugfix/987-form-validation

# Hotfixes
hotfix/111-security-patch
hotfix/222-payment-failure
hotfix/333-data-corruption

# Releases
release/1.2.0
release/2.0.0-beta.1

Rules

  • Use lowercase
  • Separate words with hyphens
  • Include ticket/issue number
  • Keep descriptions brief but clear
  • Max 50 characters total

Commit Standards

Conventional Commits

We follow the Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Commit Types

feat:     # New feature
fix:      # Bug fix
docs:     # Documentation changes
style:    # Code style changes (formatting, semicolons, etc)
refactor: # Code refactoring
perf:     # Performance improvements
test:     # Adding or updating tests
build:    # Build system changes
ci:       # CI configuration changes
chore:    # Other changes (dependencies, tooling)
revert:   # Reverting previous commit

Examples

# Feature commit
feat(auth): add social login with Google OAuth

Implemented Google OAuth integration for user authentication.
Users can now sign in using their Google accounts.

Closes #123

# Bug fix commit
fix(ui): resolve header overlap on mobile devices

Fixed z-index issue causing header to overlap with dropdown menus
on mobile viewports.

Fixes #456

# Breaking change
feat(api): update user endpoint response format

BREAKING CHANGE: Changed user API response structure.
The 'name' field is now split into 'firstName' and 'lastName'.

Migration guide in docs/migrations/v2.md

Commit Message Rules

  1. Subject line

    • Use imperative mood ("add" not "added")
    • Don't capitalize first letter
    • No period at the end
    • Max 50 characters

  2. Body

    • Wrap at 72 characters
    • Explain what and why, not how
    • Use blank line between subject and body

  3. Footer

    • Reference issues and PRs
    • Note breaking changes

Pull Request Process

PR Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix (non-breaking change)
- [ ] New feature (non-breaking change)
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Screenshots
If applicable, add screenshots

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings
- [ ] Tests added/updated
- [ ] All tests passing

## Related Issues
Closes #(issue number)

PR Workflow

  1. Create Feature Branch

    git checkout develop
git pull origin develop
git checkout -b feature/123-new-feature

  2. Make Changes

    # Make your changes
git add .
git commit -m "feat: add new feature"

  3. Keep Branch Updated

    git checkout develop
git pull origin develop
git checkout feature/123-new-feature
git rebase develop

  4. Push Branch

    git push origin feature/123-new-feature

  5. Create Pull Request

    • Use PR template
    • Add reviewers
    • Link related issues
    • Add appropriate labels

  6. Address Review Comments

    # Make requested changes
git add .
git commit -m "fix: address review comments"
git push origin feature/123-new-feature

Code Review Guidelines

For Reviewers

What to Look For

  1. Functionality

    • Does the code do what it's supposed to?
    • Are edge cases handled?
    • Is error handling appropriate?

  2. Code Quality

    • Is the code readable and maintainable?
    • Does it follow our style guide?
    • Are there any code smells?

  3. Performance

    • Are there any obvious performance issues?
    • Is pagination implemented for lists?
    • Are queries optimized?

  4. Security

    • Is user input validated?
    • Are there any security vulnerabilities?
    • Is authentication/authorization correct?

  5. Testing

    • Are tests included?
    • Do tests cover the main scenarios?
    • Are tests meaningful?

Review Comments

// ❌ Bad review comment
"This is wrong"

// ✅ Good review comment
"Consider using `useMemo` here to prevent recalculation on every render:
```suggestion
const expensiveValue = useMemo(() => calculateValue(data), [data]);

This would improve performance when the component re-renders.

For Authors

  1. Respond to all comments
  2. Explain decisions when needed
  3. Update PR description if scope changes
  4. Request re-review after changes
  5. Don't take feedback personally

Main Branch Protection Policy

Protection Rules Configuration

Navigate to Settings → Branches → Add rule and configure:

Branch name pattern: main

Protect matching branches:
  ✅ Require a pull request before merging
    ✅ Require approvals: 2
    ✅ Dismiss stale pull request approvals when new commits are pushed
    ✅ Require review from CODEOWNERS
    ✅ Restrict who can dismiss pull request reviews
    
  ✅ Require status checks to pass before merging
    ✅ Require branches to be up to date before merging
    Required status checks:
      - build
      - test
      - lint
      - security-scan
      - coverage
      
  ✅ Require conversation resolution before merging
  
  ✅ Require signed commits
  
  ✅ Require linear history
  
  ✅ Include administrators
  
  ✅ Restrict who can push to matching branches
    Allowed actors:
      - release-bot
      - senior-developers team
      
  ❌ Allow force pushes (Never enable)
  ❌ Allow deletions (Never enable)

Additional Security Settings

# .github/CODEOWNERS
# Global owners
* @company/senior-developers

# Frontend code
/src/components/ @company/frontend-team
/src/pages/ @company/frontend-team
/src/styles/ @company/frontend-team

# Backend/API code
/src/api/ @company/backend-team
/src/lib/auth/ @company/security-team

# Infrastructure
/.github/ @company/devops-team
/docker/ @company/devops-team
/scripts/ @company/devops-team

# Documentation
*.md @company/documentation-team
/docs/ @company/documentation-team

Automated Protection Checks

# .github/workflows/protection-checks.yml
name: Branch Protection Checks

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

jobs:
  verify-pr:
    runs-on: ubuntu-latest
    steps:
      - name: Check PR size
        uses: actions/github-script@v7
        with:
          script: |
            const pr = context.payload.pull_request;
            const { additions, deletions, changed_files } = pr;
            
            if (additions + deletions > 1000) {
              core.setFailed('PR too large. Please break into smaller PRs.');
            }
            
            if (changed_files > 50) {
              core.setFailed('Too many files changed. Please break into smaller PRs.');
            }
      
      - name: Verify commit signatures
        if: github.event.pull_request.head.repo.full_name == github.repository
        run: |
          git verify-commit HEAD~${{ github.event.pull_request.commits }}..HEAD
      
      - name: Check for merge commits
        run: |
          if git log --format=%P -n 1 HEAD | grep -q " "; then
            echo "::error::Merge commits are not allowed. Please rebase your branch."
            exit 1
          fi
      
      - name: Validate branch naming
        run: |
          BRANCH="${{ github.head_ref }}"
          if ! echo "$BRANCH" | grep -qE '^(feature|bugfix|hotfix|release)/[0-9]+-[a-z0-9-]+$'; then
            echo "::error::Branch name doesn't follow naming convention: type/issue-number-description"
            exit 1
          fi

  security-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Check for secrets
        uses: trufflesecurity/trufflehog@main
        with:
          path: ./
          base: ${{ github.event.pull_request.base.sha }}
          head: ${{ github.event.pull_request.head.sha }}
      
      - name: Check dependencies
        run: |
          npm audit --audit-level=high
          
  require-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Check test coverage for new files
        run: |
          # Get list of new/modified JS/TS files
          FILES=$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }} | grep -E '\.(js|jsx|ts|tsx)$' | grep -v test | grep -v spec)
          
          # Check each file has a corresponding test
          for file in $FILES; do
            test_file="${file%.*}.test.${file##*.}"
            spec_file="${file%.*}.spec.${file##*.}"
            
            if [[ ! -f "$test_file" && ! -f "$spec_file" ]]; then
              echo "::warning::No test file found for $file"
            fi
          done

Emergency Override Process

For critical hotfixes that need to bypass protection:

  1. Create Override Request

    # Create issue using template
gh issue create \
  --title "Branch Protection Override: Critical Hotfix" \
  --body-file .github/ISSUE_TEMPLATE/protection-override.md \
  --label "emergency,override"

  2. Temporary Rule Adjustment

    • Two senior developers must approve
    • DevOps team temporarily adjusts rules
    • Changes are logged and audited
    • Rules are restored immediately after merge

  3. Post-Merge Requirements

    • Incident report filed
    • Root cause analysis conducted
    • Process improvement implemented

Merge Strategies

Merge Methods

  1. Squash and Merge (Preferred for features)

    • Creates clean history
    • One commit per feature
    • Easier to revert

  2. Rebase and Merge (For clean commits)

    • Preserves commit history
    • Requires clean commits
    • Good for documentation changes

  3. Create Merge Commit (For releases)

    • Preserves full history
    • Shows merge points
    • Used for release branches

Merge Rules

develop → feature:
  - Rebase feature on develop
  - Resolve conflicts locally
  - Force push after rebase

feature → develop:
  - Squash and merge via PR
  - Delete branch after merge
  - Ensure CI passes

develop → main:
  - Create release branch first
  - Merge via PR
  - Tag after merge
  - No direct commits

hotfix → main:
  - Merge via PR
  - Also merge to develop
  - Tag after merge
  - Immediate deployment

Release Management

Version Numbering

We follow Semantic Versioning:

MAJOR.MINOR.PATCH

1.0.0
│ │ │
│ │ └── Patch: Bug fixes
│ └──── Minor: New features (backwards compatible)
└────── Major: Breaking changes

Release Process

  1. Create Release Branch

    git checkout develop
git pull origin develop
git checkout -b release/1.2.0

  2. Update Version

    # Update package.json
npm version minor

# Update changelog
npm run changelog

git add .
git commit -m "chore: bump version to 1.2.0"

  3. Test Release

    • Run full test suite
    • Deploy to staging
    • Perform QA testing
    • Fix any issues found

  4. Merge to Main

    # Create PR from release to main
# After approval and merge:
git checkout main
git pull origin main
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

  5. Back-merge to Develop

    git checkout develop
git merge main
git push origin develop

Changelog Generation

# Install conventional-changelog
npm install -D conventional-changelog-cli

# Generate changelog
npx conventional-changelog -p angular -i CHANGELOG.md -s

# Or add to package.json
{
  "scripts": {
    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
  }
}

Hotfix Process

Emergency Fix Workflow

  1. Create Hotfix Branch

    git checkout main
git pull origin main
git checkout -b hotfix/critical-bug

  2. Fix Issue

    # Make minimal changes
git add .
git commit -m "fix: resolve critical security vulnerability"

  3. Test Fix

    • Run affected tests
    • Test in production-like environment
    • Verify fix resolves issue

  4. Merge to Main

    # Create PR to main
# Fast-track review
# Merge and tag
git tag -a v1.1.1 -m "Hotfix: security vulnerability"

  5. Merge to Develop

    git checkout develop
git merge hotfix/critical-bug
git push origin develop

Git Configuration

Global Configuration

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

# Set default branch
git config --global init.defaultBranch main

# Enable color output
git config --global color.ui auto

# Set default editor
git config --global core.editor "code --wait"

# Configure line endings
git config --global core.autocrlf input  # macOS/Linux
git config --global core.autocrlf true   # Windows

# 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'
git config --global alias.visual '!gitk'

Project Configuration

# .gitignore
node_modules/
.next/
.env.local
.env.*.local
.DS_Store
*.log
coverage/
.vscode/*
!.vscode/extensions.json
.idea/

# .gitattributes
* text=auto
*.js text eol=lf
*.jsx text eol=lf
*.ts text eol=lf
*.tsx text eol=lf
*.json text eol=lf
*.md text eol=lf

Common Workflows

Starting New Feature

# 1. Update local develop
git checkout develop
git pull origin develop

# 2. Create feature branch
git checkout -b feature/123-user-profile

# 3. Work on feature
# ... make changes ...
git add .
git commit -m "feat(profile): add user avatar upload"

# 4. Keep branch updated
git fetch origin
git rebase origin/develop

# 5. Push to remote
git push origin feature/123-user-profile

# 6. Create pull request

Updating Feature Branch

# Option 1: Rebase (preferred)
git checkout feature/my-feature
git fetch origin
git rebase origin/develop

# Option 2: Merge
git checkout feature/my-feature
git fetch origin
git merge origin/develop

Undoing Changes

# Undo last commit (keep changes)
git reset --soft HEAD~1

# Undo last commit (discard changes)
git reset --hard HEAD~1

# Undo specific commit
git revert <commit-hash>

# Discard local changes
git checkout -- <file>
git restore <file>  # Git 2.23+

# Clean untracked files
git clean -fd

Stashing Work

# Save current work
git stash save "WIP: feature description"

# List stashes
git stash list

# Apply latest stash
git stash pop

# Apply specific stash
git stash apply stash@{2}

# Delete stash
git stash drop stash@{1}

Cherry-picking

# Apply specific commit to current branch
git cherry-pick <commit-hash>

# Cherry-pick without committing
git cherry-pick -n <commit-hash>

# Cherry-pick range
git cherry-pick <start-hash>..<end-hash>

Best Practices Checklist

Daily Workflow

  • Pull latest changes before starting work
  • Create feature branch from develop
  • Make atomic commits
  • Write clear commit messages
  • Push changes regularly

Before Creating PR

  • Rebase on latest develop
  • Run tests locally
  • Review own changes
  • Update documentation
  • Check for console logs

Code Review

  • Respond to all comments
  • Test reviewer suggestions
  • Update PR description if needed
  • Request re-review after changes
  • Thank reviewers

Release Process

  • Version bumped correctly
  • Changelog updated
  • All tests passing
  • Stakeholders notified
  • Deployment verified

Related Pages

⚠️ **GitHub.com Fallback** ⚠️