Part 2: Branching Strategies and Workflows

Introduction

When I first started working with a team on a production TypeScript microservice, we didn't have a clear branching strategy. One developer would push directly to main, another would create feature branches with random names like my-changes or fix, and a third would work on a branch for weeks without merging. The result? Merge conflicts, broken deployments, and a lot of frustration.

After experiencing this chaos firsthand, I learned that choosing the right branching strategy is crucial for team productivity and code quality. In this part, I'll share the three main branching strategies I've used in production: Git Flow, GitHub Flow, and Trunk-Based Development—along with real examples of when each works best.

What Is a Branching Strategy?

A branching strategy is a set of rules and conventions that a team follows for creating, naming, and merging branches. It defines:

• When to create branches

• How to name branches

• What types of branches exist

• How and when branches get merged

• Who can merge to which branches

Think of it as the "traffic rules" for your codebase—without them, you get chaos.

Git Flow: The Traditional Approach

Git Flow is a branching model created by Vincent Driessen in 2010. It's structured and comprehensive, designed for projects with scheduled releases.

Branch Types in Git Flow

1. Main Branches (permanent):

• main (or master): Production-ready code

• develop: Integration branch for features

2. Supporting Branches (temporary):

• feature/*: New features

• release/*: Prepare for production release

• hotfix/*: Emergency production fixes

Git Flow Workflow

Here's how I used Git Flow when working on a scheduled-release e-commerce platform:

Starting a Feature

# Always start from develop
git checkout develop
git pull origin develop

# Create feature branch
git checkout -b feature/product-recommendations

# Work on the feature
# ... write code, make commits ...

git add src/services/recommendation.service.ts
git commit -m "feat: implement collaborative filtering for recommendations"

git add tests/recommendation.test.ts
git commit -m "test: add recommendation service unit tests"

# Push feature branch
git push -u origin feature/product-recommendations

Completing a Feature

# Update develop
git checkout develop
git pull origin develop

# Merge feature (usually done via Pull Request on GitHub)
git merge feature/product-recommendations

# Push to develop
git push origin develop

# Delete feature branch
git branch -d feature/product-recommendations
git push origin --delete feature/product-recommendations

Creating a Release

# When ready to release, create release branch from develop
git checkout develop
git pull origin develop

git checkout -b release/v1.5.0

# Update version numbers, changelogs, etc.
npm version 1.5.0
git add package.json package-lock.json
git commit -m "chore: bump version to 1.5.0"

# Bug fixes only on release branch
git add src/utils/price-calculator.ts
git commit -m "fix: correct tax calculation for EU countries"

# Push release branch
git push -u origin release/v1.5.0

Finishing a Release

# Merge to main
git checkout main
git pull origin main
git merge release/v1.5.0
git tag -a v1.5.0 -m "Release version 1.5.0"
git push origin main --tags

# Merge back to develop
git checkout develop
git pull origin develop
git merge release/v1.5.0
git push origin develop

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

Handling Hotfixes

# Critical bug in production!
git checkout main
git pull origin main

# Create hotfix branch
git checkout -b hotfix/payment-gateway-timeout

# Fix the bug
git add src/services/payment.service.ts
git commit -m "fix: increase payment gateway timeout to 30s"

# Test the fix
npm test

# Merge to main
git checkout main
git merge hotfix/payment-gateway-timeout
git tag -a v1.5.1 -m "Hotfix: payment gateway timeout"
git push origin main --tags

# Merge to develop
git checkout develop
git merge hotfix/payment-gateway-timeout
git push origin develop

# Delete hotfix branch
git branch -d hotfix/payment-gateway-timeout
git push origin --delete hotfix/payment-gateway-timeout

Git Flow: Real-World Example

In my e-commerce project with quarterly releases:

main (v1.4.0)
├── hotfix/payment-gateway-timeout → v1.4.1
└── develop
    ├── feature/product-recommendations
    ├── feature/wishlist
    ├── feature/advanced-search
    └── release/v1.5.0 → main (v1.5.0)

Pros and Cons of Git Flow

Pros:

• Clear separation between development and production code

• Excellent for scheduled releases (quarterly, monthly)

• Hotfixes can be deployed without deploying unfinished features

• Well-documented and widely understood

Cons:

• Complex with many branches to manage

• Overhead for continuous deployment scenarios

• Merge conflicts can be frequent

• Not ideal for fast-moving projects

When I Use Git Flow:

• Projects with scheduled release cycles

• Products requiring extensive QA/testing before release

• Teams with dedicated release managers

• When production stability is critical

GitHub Flow: Simplified for Continuous Deployment

GitHub Flow is a lightweight branching strategy created by GitHub. It's designed for teams that deploy continuously.

The Simple Rules

1. main branch is always deployable

2. Create descriptive feature branches from main

3. Commit to your feature branch and push regularly

4. Open a Pull Request when ready

5. After review and CI passes, merge to main

6. Deploy immediately after merging

GitHub Flow Workflow

This is my preferred workflow for microservices with continuous deployment:

Working on a Feature

# Start from main
git checkout main
git pull origin main

# Create feature branch with descriptive name
git checkout -b add-email-verification

# Make changes and commit
git add src/services/email-verification.service.ts
git commit -m "feat: add email verification service"

git add src/controllers/auth.controller.ts
git commit -m "feat: integrate email verification in registration flow"

git add tests/email-verification.test.ts
git commit -m "test: add email verification tests"

# Push frequently
git push -u origin add-email-verification

Creating a Pull Request

On GitHub:

1. Click "Compare & pull request"

2. Write clear description:

## What This PR Does
Adds email verification to the user registration flow.

## Changes
- New `EmailVerificationService` with token generation
- Updated `AuthController` to send verification emails
- Added verification endpoint `/auth/verify/:token`
- Comprehensive unit tests

## Testing
- ✅ Unit tests pass
- ✅ Manual testing with SendGrid sandbox
- ✅ Error scenarios tested

## Screenshots
[Verification email screenshot]

Closes #145

1. Request reviews from team members

2. Ensure CI/CD checks pass

Merging and Deploying

# After approval, merge via GitHub
# GitHub automatically deploys to production (via GitHub Actions)

# Locally, clean up
git checkout main
git pull origin main
git branch -d add-email-verification

GitHub Flow: Real-World Example

In my TypeScript microservices with CI/CD:

# Monday
git checkout -b fix-user-session-timeout
# ... work, commit, push, PR, merge, deploy

# Tuesday
git checkout -b add-rate-limiting
# ... work, commit, push, PR, merge, deploy

# Wednesday
git checkout -b update-payment-webhook
# ... work, commit, push, PR, merge, deploy

# Main branch is deployed 3 times this week

Branch Protection Rules on GitHub

For GitHub Flow, I set up these protections on main:

# On GitHub: Settings → Branches → Add rule

Branch name pattern: main

Protection rules:
☑ Require pull request reviews before merging
  - Required approvals: 1
☑ Require status checks to pass before merging
  - build
  - test
  - lint
☑ Require branches to be up to date before merging
☑ Include administrators
☐ Allow force pushes
☐ Allow deletions

Pros and Cons of GitHub Flow

Pros:

• Simple and easy to understand

• Perfect for continuous deployment

• Fast iteration and deployment

• Minimal overhead

• Great for small to medium teams

Cons:

• No dedicated release branches

• Harder to maintain multiple versions

• Requires robust CI/CD and testing

• Not suitable for scheduled releases

When I Use GitHub Flow:

• Microservices with continuous deployment

• Web applications deployed multiple times per day

• Teams practicing DevOps/SRE

• When speed of delivery is critical

Trunk-Based Development: Modern CI/CD Approach

Trunk-Based Development (TBD) is a branching strategy where developers work in short-lived feature branches (or directly on trunk) and merge frequently to a single branch called "trunk" (usually main).

Core Principles

1. Short-lived branches: Feature branches live for hours or days, not weeks

2. Frequent integration: Merge to trunk at least daily

3. Feature flags: Hide incomplete features behind toggles

4. Comprehensive automated testing: Trust in CI/CD pipeline

5. Small, incremental changes: Avoid large batches

Trunk-Based Development Workflow

Here's how I implement TBD in a high-velocity TypeScript API:

Small, Frequent Changes

# Morning: Add database migration
git checkout main
git pull origin main
git checkout -b add-user-preferences-table

# Small change - just the migration
npx prisma migrate dev --name add_user_preferences

git add prisma/migrations/
git commit -m "feat: add user preferences table migration"
git push -u origin add-user-preferences-table

# Create PR, quick review, merge within 1-2 hours

Using Feature Flags

// src/services/recommendation.service.ts
import { FeatureFlags } from './feature-flags';

export class RecommendationService {
  async getRecommendations(userId: string): Promise<Product[]> {
    // New algorithm behind feature flag
    if (await FeatureFlags.isEnabled('new-recommendation-algorithm', userId)) {
      return this.getMLBasedRecommendations(userId);
    }
    
    // Old algorithm (safe fallback)
    return this.getRuleBasedRecommendations(userId);
  }
  
  private async getMLBasedRecommendations(userId: string): Promise<Product[]> {
    // New implementation - can be merged even if not complete
    // Enabled only for internal users during development
  }
  
  private async getRuleBasedRecommendations(userId: string): Promise<Product[]> {
    // Existing implementation
  }
}

# Merge incomplete feature safely
git add src/services/recommendation.service.ts
git commit -m "feat: add ML-based recommendations (behind feature flag)"
git push -u origin add-ml-recommendations

# PR, review, merge - feature is in production but disabled

Enabling Features Gradually

// src/config/feature-flags.ts
export const featureFlags = {
  'new-recommendation-algorithm': {
    enabled: true,
    // Rollout strategy
    rollout: {
      percentage: 10, // 10% of users
      userIds: ['internal-user-1', 'internal-user-2'], // Always enabled for testing
    }
  }
};

Trunk-Based Development: Real-World Example

In my payment processing microservice:

# Day 1 - Morning
git checkout -b add-payment-method-model
# Add Prisma model, merge in 1 hour

# Day 1 - Afternoon  
git checkout -b add-payment-method-service
# Add service layer (behind feature flag), merge in 2 hours

# Day 2 - Morning
git checkout -b add-payment-method-controller
# Add API endpoint (behind feature flag), merge in 1 hour

# Day 2 - Afternoon
git checkout -b add-payment-method-tests
# Add comprehensive tests, merge in 2 hours

# Day 3
# Enable feature flag for internal testing
# Monitor metrics, fix bugs if any

# Day 4
# Gradually roll out: 10% → 25% → 50% → 100%

All changes are in production immediately, but feature is controlled via flags.

Pros and Cons of Trunk-Based Development

Pros:

• Fastest integration and feedback

• Minimal merge conflicts

• Forces small, incremental changes

• Excellent for high-performing teams

• Natural fit for continuous deployment

Cons:

• Requires excellent test automation

• Needs mature CI/CD pipeline

• Requires feature flag infrastructure

• Can be intimidating for new developers

• Incomplete features in production code (mitigated by flags)

When I Use Trunk-Based Development:

• High-velocity teams with strong testing culture

• Microservices with robust CI/CD

• When deploying multiple times per day

• Teams practicing DevOps/SRE

• When feature flags infrastructure is in place

Choosing the Right Strategy

From my experience, here's how to choose:

Git Flow

Choose when:

• Scheduled releases (quarterly, monthly)

• Multiple versions in production (e.g., mobile apps)

• Extensive manual QA required

• Traditional enterprise environment

Example: Enterprise e-commerce platform with quarterly releases

GitHub Flow

Choose when:

• Continuous deployment to single environment

• Web applications or APIs

• Small to medium team size

• Good automated testing coverage

Example: SaaS web application with daily deployments

Trunk-Based Development

Choose when:

• High-velocity continuous deployment

• Mature CI/CD and testing infrastructure

• Feature flag system available

• Experienced development team

Example: Microservices architecture with multiple deployments per day

Branch Naming Conventions

Regardless of strategy, use clear naming conventions:

My Standard Convention

# Feature branches
feature/user-authentication
feature/payment-integration
feature/email-notifications

# Bug fixes
fix/null-pointer-in-payment-service
fix/session-timeout-issue
bugfix/incorrect-tax-calculation

# Hotfixes (Git Flow)
hotfix/critical-security-patch
hotfix/payment-gateway-timeout

# Release branches (Git Flow)
release/v1.5.0
release/v2.0.0-beta

# Experimental/spike branches
experiment/graphql-migration
spike/redis-caching

# Refactoring
refactor/extract-payment-service
refactor/simplify-auth-middleware

# Documentation
docs/api-documentation
docs/deployment-guide

# Chores/maintenance
chore/upgrade-dependencies
chore/update-ci-pipeline

Naming Best Practices

# Bad
git checkout -b my-branch
git checkout -b temp
git checkout -b fix
git checkout -b john-changes

# Good
git checkout -b feature/add-product-search
git checkout -b fix/payment-webhook-validation
git checkout -b refactor/user-service-architecture

Working with Pull Requests

My Pull Request Workflow

1. Keep PRs Small and Focused

# Bad: Large PR with multiple unrelated changes
git checkout -b update-everything
# Changed 47 files across multiple features

# Good: Small, focused PRs
git checkout -b add-email-service
# Changed 3 files, single purpose

2. Write Descriptive PR Descriptions

## Summary
Add email notification service using SendGrid

## Changes
- New `EmailService` class with template support
- Integration with SendGrid API
- Email templates for user registration and password reset
- Comprehensive unit and integration tests

## Type of Change
- [x] New feature
- [ ] Bug fix
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [x] Unit tests pass locally
- [x] Integration tests pass locally
- [x] Manual testing completed
- [x] Tested in staging environment

## Screenshots
[Screenshot of welcome email]

## Checklist
- [x] Code follows project style guidelines
- [x] Self-reviewed the code
- [x] Added tests for new functionality
- [x] Updated documentation
- [x] No console.log or debugging code

## Related Issues
Closes #234
Related to #189

## Deployment Notes
Requires `SENDGRID_API_KEY` environment variable in production

3. Request Specific Reviewers

# On GitHub, request reviews from:
# - Someone familiar with this area of code
# - A senior developer for architectural decisions
# - Someone who will learn from reviewing this code

Handling Merge Conflicts

Conflicts are inevitable. Here's how I handle them:

# Update your feature branch with latest main
git checkout feature/user-profile
git fetch origin
git merge origin/main

# Conflict! Git shows:
# CONFLICT (content): Merge conflict in src/services/user.service.ts
# Automatic merge failed; fix conflicts and then commit the result.

# Open the file and look for conflict markers

// src/services/user.service.ts
export class UserService {
  async getUser(id: string): Promise<User> {
<<<<<<< HEAD
    // Your changes
    return await this.prisma.user.findUnique({
      where: { id },
      include: { profile: true, posts: true }
    });
=======
    // Changes from main
    return await this.prisma.user.findUnique({
      where: { id },
      include: { profile: true }
    });
>>>>>>> origin/main
  }
}

# Manually resolve: keep both includes
# Remove conflict markers and fix the code

git add src/services/user.service.ts
git commit -m "merge: resolve conflict in user.service.ts"
git push

Practical Tips from Experience

1. Pull Before You Push

# Always update before starting work
git checkout main
git pull origin main

# Prevents conflicts and ensures you have latest code

2. Push Frequently

# Push at least daily, even if work isn't complete
git push origin feature/my-feature

# Benefits:
# - Code is backed up
# - Team can see your progress
# - Easier to get early feedback

3. Commit Often, Push Less Often

# Make small, logical commits as you work
git add src/utils/helper.ts
git commit -m "feat: add date formatting helper"

git add tests/helper.test.ts
git commit -m "test: add tests for date helper"

# Then push when you reach a good stopping point
git push

4. Rebase to Keep History Clean (Advanced)

# Instead of merge, you can rebase to keep linear history
git checkout feature/my-feature
git rebase main

# If conflicts, resolve and continue
git rebase --continue

# Force push (careful!)
git push --force-with-lease

Warning: Only rebase branches that you own and haven't been shared with others.

Conclusion

Choosing the right branching strategy is crucial for team productivity and code quality. In this part, we covered:

• Git Flow: Traditional approach with multiple branch types, perfect for scheduled releases

• GitHub Flow: Simplified workflow for continuous deployment

• Trunk-Based Development: Modern approach with short-lived branches and feature flags

• Branch naming conventions and PR best practices

• Handling merge conflicts and practical tips

From my experience:

• Start with GitHub Flow if you're unsure—it's simple and effective

• Move to Trunk-Based Development as your testing and CI/CD mature

• Use Git Flow if you have scheduled releases and need separation between development and production

In Part 3, we'll explore Monorepo vs Polyrepo strategies, examining real-world examples from microservices projects and discussing how to choose between these architectural approaches.

---

Key Takeaways:

• Branching strategy must match your deployment frequency

• Small, focused PRs are easier to review and merge

• Automate everything you can (CI/CD, testing)

• Feature flags enable trunk-based development

• Good commit messages and branch names improve collaboration

Remember: The best branching strategy is the one your team actually follows!