Skip to content

Updated Branching Strategy

Workflow Overview

graph TD
    A[feat/*] -->|Auto-PR| B(dev)
    C[fix/*] -->|Auto-PR| B
    B -->|Manual PR| D[main]

    D -->|Production| E[ghcr.io/org/repo:version]
    D -->|Latest| F[ghcr.io/org/repo:latest]
    B -->|Staging| G[ghcr.io/org/repo:version-stg]
    B -->|Staging Latest| H[ghcr.io/org/repo:latest-stg]
    A -->|Feature| I[ghcr.io/org/repo:commit-sha]
    C -->|Fix| I
  1. Main Branch (main):
  2. Production-ready code
  3. Protected - no direct pushes
  4. Only accepts PRs from dev branch

  5. Merge triggers:

    • Production image build (ghcr.io/org/repo:version)
    • Latest tag update (ghcr.io/org/repo:latest)
    • Version tag (semver)

  6. Development Branch (dev):

  7. Staging environment
  8. Accepts PRs from feat/* and fix/* branches

  9. Merge triggers:

    • Staging image build (ghcr.io/org/repo:version-stg)
    • Auto-PR creation to main

  10. Feature Branches (feat/*):

  11. Created from dev branch
  12. Push triggers:
    • Auto-PR to dev
    • CI tests

  13. Naming: feat/description (e.g., feat/user-auth)

  14. Fix Branches (fix/*):

  15. Created from dev branch
  16. Push triggers:
    • Auto-PR to dev
    • CI tests
  17. Can use -automerge suffix for critical fixes
  18. Naming: fix/description (e.g., fix/login-bug)

Image Tagging Strategy

Branch Type Image Tag Format Registry Location
feat/fix :commit-sha ghcr.io/org/repo
dev :version-stg ghcr.io/org/repo
main :version + :latest ghcr.io/org/repo

Implementation Requirements

  1. GitHub Actions:
  2. Auto-PR creation on push
  3. Image building/pushing
  4. Version tagging

  5. Status checks

  6. Branch Protection:

  7. main: Require PR, status checks, review
  8. dev: Require PR, status checks

  9. feat/fix: Require status checks

  10. Scripts:

  11. Updated create-branch.js to enforce naming

  12. Pre-push hooks to prevent direct pushes to protected branches

  13. Version Management:

  14. Semantic versioning
  15. Automated changelog generation
  16. Release notes

Setup Instructions

# Install dependencies
pnpm install

# Setup Git hooks
pre-commit install --hook-type pre-commit --hook-type commit-msg --hook-type pre-push

Best Practices

  1. Always create branches using the interactive tool: 

    node scripts/create-branch.js

  2. Keep branches focused and short-lived

  3. Use meaningful, descriptive branch names

  4. Regularly sync with upstream dev branch