Branching Strategy - Industry Standards¶

Date: 2025-11-19 Status: RECOMMENDATION Context: Monorepo branching for data platform

Branch Naming: Industry Standards¶

Standard Branch Names (Git Flow)¶

Branch	Industry Standard	Alternative Names	Usage
Production	`main` or `master`	`production`, `prod`	Production-ready code
Development	`develop` or `development`	`dev`, `staging`	Integration branch
Features	`feature/` or `feat/`	`f/*`	New features
Fixes	`fix/` or `bugfix/`	`hotfix/*`	Bug fixes
Releases	`release/*`	`rel/*`	Release preparation

Most Common Pattern (80% of companies)¶

Git Flow (Standard)¶

main                    ← Production (protected)
├── develop             ← Development (protected)
    ├── feature/feat-a  ← Feature branches
    ├── feature/feat-b
    └── fix/bug-123

Standard names: - main (or master) - Production - develop - Development/staging - feature/* - Features - fix/* - Bug fixes

Note: develop is the standard, NOT dev (though dev works too)

Alternative: Trunk-Based Development¶

Pattern (20% of companies, mostly small teams)¶

main                    ← Only long-lived branch
├── feature/feat-a      ← Short-lived feature branches
└── feature/feat-b

Used by: Small teams, continuous deployment, high maturity

Monorepo Branching: Single Branch vs Per-Project¶

Industry Standard: Single Development Branch ⭐¶

main
└── develop             ← Single branch for ALL projects
    ├── feature/snowflake-bronze-setup
    ├── feature/dbt-condenast-models
    └── fix/airflow-dag-error

Why this is standard: - ✅ Simpler (only 2 long-lived branches: main + develop) - ✅ Easier to manage - ✅ Better for monorepo (everything moves together) - ✅ Less branch confusion - ✅ Industry standard (Google, Facebook, Uber all do this)

Used by: 90% of monorepos

Alternative: Per-Project Branches (NOT recommended)¶

main
├── develop-snowflake   ← Separate per project
├── develop-dbt
├── develop-airflow
└── develop-frontend

Why this is rare: - ❌ Complex merge conflicts - ❌ Hard to coordinate changes across projects - ❌ More branches to maintain - ❌ Confusing for new team members - ❌ Defeats monorepo purpose (atomic cross-project changes)

Used by: <10% of monorepos (usually legacy, trying to migrate)

Recommended for xo-data Monorepo¶

Standard Git Flow with Single Development Branch¶

main
├── develop                              ← Single dev branch
    ├── feature/snowflake-bronze-setup   ← This project
    ├── feature/dbt-condenast-silver
    ├── feature/airflow-dag-update
    └── fix/snowflake-schema-error

Branch Naming Convention¶

Format: {type}/{description}

Types: - feature/ or feat/ - New features - fix/ - Bug fixes - chore/ - Maintenance (dependencies, config) - docs/ - Documentation only - refactor/ - Code refactoring

Examples:

feature/snowflake-bronze-setup
feature/dbt-condenast-models
fix/airflow-dag-timezone-bug
chore/update-dependencies
docs/add-architecture-diagrams
refactor/extract-s3-utils

GitHub Actions: Standard Triggers¶

Industry Pattern¶

on:
  push:
    branches:
      - develop      # Auto-deploy to DEV
      - staging      # Auto-deploy to STAGING (optional)
      - main         # Auto-deploy to PROD (usually requires approval)

Standard: - develop → DEV environment (auto) - staging → STAGING environment (auto) - optional - main → PROD environment (manual approval)

Recommended Workflow for Your Project¶

Current Files (Update Needed)¶

Existing workflow: .github/workflows/snowflake-deploy.yml - Watches: apps/snowflake-schema/operations/** - Triggers: Push to main - Deploys: OPERATIONS database (legacy)

New workflow: .github/workflows/snowflake-bronze-deploy.yml ✅ - Watches: apps/snowflake-bronze/** - Triggers: Push to develop or main - Deploys: *_DEV (develop) or *_PROD (main)

Branch Strategy¶

main branch:
├── Legacy: apps/snowflake-schema/operations/**
│   └── Auto-deploys to OPERATIONS (production)
│
└── New: apps/snowflake-bronze/**
    └── Auto-deploys to *_PROD databases (future)

develop branch:
└── New: apps/snowflake-bronze/**
    └── Auto-deploys to *_DEV databases

Do You Need to Change the Workflow?¶

Your Current Workflow Uses `develop`¶

# .github/workflows/snowflake-bronze-deploy.yml
on:
  push:
    branches:
      - develop      # ✅ This is standard!
      - main

Answer: develop is the industry standard name. You're good! ✅

Alternative Names (If You Prefer)¶

If your team uses different naming:

on:
  push:
    branches:
      - dev          # Common alternative
      - development  # More explicit
      - staging      # Some teams use this
      - main

Recommendation: Stick with develop (most standard)

Monorepo Best Practices¶

1. Single Long-Lived Branches¶

main       ← Protected, production
develop    ← Protected, integration

Don't create: - ❌ develop-snowflake - ❌ develop-dbt - ❌ develop-airflow

2. Project-Specific Feature Branches¶

feature/snowflake-bronze-setup      ← Specific to Snowflake project
feature/dbt-condenast-models        ← Specific to dbt project
feature/airflow-dag-refactor        ← Specific to Airflow project

Why this works: - ✅ Feature branches are short-lived (days/weeks) - ✅ Clear what project they belong to (from name) - ✅ Merge to single develop branch - ✅ Deploy all projects together (monorepo benefit)

3. Path-Based CI/CD Triggers¶

on:
  push:
    branches:
      - develop
    paths:
      - "apps/snowflake-bronze/**"      # Only trigger if this path changes

Why this works: - ✅ Single develop branch - ✅ Workflows only trigger when relevant files change - ✅ No need for separate branches per project

Real-World Examples¶

Google (Monorepo with 2 billion LOC)¶

main branch only (trunk-based development)
├── feature/search-improvement
├── feature/maps-update
└── feature/youtube-feature

Pattern: Single trunk, short-lived feature branches

Uber (Monorepo for data platform)¶

master
└── develop
    ├── feature/data-pipeline-x
    ├── feature/ml-model-y
    └── feature/analytics-z

Pattern: Git flow with single develop branch

Your Team's Pattern (Recommended)¶

main
└── develop                              ← Single integration branch
    ├── feature/snowflake-bronze-setup   ← Your current work
    ├── feature/dbt-setup                ← Future work
    └── feature/airflow-updates          ← Future work

Summary¶

Branch Naming Standard¶

Question	Answer
Is `develop` standard?	✅ Yes (most common)
Alternative names?	`dev`, `development`, `staging` (all work)
Should we use per-project dev branches?	❌ No (use single `develop`)
Feature branch naming?	`feature/{description}` or `feat/{description}`

Recommended Setup¶

# Standard branch structure (what you should have)
main                    # Production (protected)
develop                 # Development (protected)
feature/*               # Feature branches (short-lived)
fix/*                   # Bug fix branches (short-lived)

Your Workflow is Correct ✅¶

on:
  push:
    branches:
      - develop      # ✅ Standard name
      - main         # ✅ Standard name

No changes needed!

Action Items¶

✅ Keep What You Have¶

Your workflow already uses develop - this is perfect!

❓ Check Your Team's Current Practice¶

# See what branches exist
git branch -a

# Check if you have:
# - main or master?
# - develop or dev?

📋 Document Your Team's Standard¶

Create .github/BRANCH_STRATEGY.md:

# Branch Strategy

## Long-Lived Branches
- `main` - Production (protected)
- `develop` - Development (protected)

## Feature Branches
- Format: `feature/{description}`
- Example: `feature/snowflake-bronze-setup`
- Merge to: `develop`

## Deployment
- `develop` branch → DEV environment (auto)
- `main` branch → PROD environment (manual approval)

Final Recommendation¶

For xo-data monorepo: 1. ✅ Use main and develop (standard names) 2. ✅ Single develop branch for all projects 3. ✅ Feature branches like feature/snowflake-bronze-setup 4. ✅ Path-based triggers in GitHub Actions 5. ❌ NO per-project dev branches

Your current workflow is correct! No changes needed.