Skip to content

Branching Strategy

This document defines the Git branching strategy and practices for ConnectSoft repositories. It is written for engineers understanding how we manage code branches and Git workflows.

ConnectSoft uses a Git branching strategy that supports both Factory-generated code and manual development. The strategy enables parallel development, code review, and safe deployments while maintaining a clean, linear history.

Tip

Keep branches short-lived and focused. Merge frequently to avoid long-lived branches that become difficult to merge. Use feature branches for all changes, whether Factory-generated or manual.

Branch Types

Main Branch

Purpose: Production-ready code that has been tested and approved.

Characteristics: - Always deployable - Protected (requires PR and approval) - All commits are tagged with version numbers - Never commit directly to main

Develop Branch (Optional)

Purpose: Integration branch for features ready for testing.

When to Use: - Large teams with multiple features in progress - Need staging environment that's ahead of main

When NOT to Use: - Small teams - Simple workflows - Prefer feature branches → main directly

Feature Branches

Purpose: Development branches for new features or changes.

Naming: feature/description (e.g., feature/invoice-service, feature/add-payment-method)

Characteristics: - Created from main (or develop) - Merged back via PR - Deleted after merge - Short-lived (days, not weeks)

Hotfix Branches

Purpose: Critical production fixes that need immediate deployment.

Naming: hotfix/description (e.g., hotfix/security-patch, hotfix/payment-bug)

Characteristics: - Created from main - Merged to main and develop (if exists) - Deleted after merge - Bypass normal process for urgent fixes

Release Branches (If Used)

Purpose: Prepare releases with version bumps and final testing.

Naming: release/version (e.g., release/1.2.0)

When to Use: - Need to prepare releases with version bumps - Final testing before production - Not commonly used (prefer tags on main)

Workflow for Features and Fixes

New Feature Workflow

Steps:

  1. Create Feature Branch 

    git checkout main
git pull
git checkout -b feature/invoice-service

  2. Develop or Generate

  3. Option A: Request Factory to generate code (Factory creates branch)

  4. Option B: Develop manually on feature branch

  5. Commit Changes 

    git add .
git commit -m "Add invoice service"

  6. Push and Create PR 

    git push origin feature/invoice-service
# Create PR via Azure DevOps UI

  7. Code Review

  8. Reviewers review PR
  9. Address feedback

  10. Update PR with changes

  11. Merge PR

  12. Merge after approval and passing CI/CD
  13. Delete feature branch after merge

Bug Fix Workflow

Steps:

  1. Create Feature Branch 

    git checkout -b feature/fix-payment-bug

  2. Fix Bug

  3. Fix the bug

  4. Add test to prevent regression

  5. Commit and PR 

    git commit -m "Fix payment processing bug"
git push origin feature/fix-payment-bug
# Create PR

  6. Review and Merge

  7. Review PR
  8. Merge after approval

Hotfix Workflow

Steps:

  1. Create Hotfix Branch 

    git checkout main
git pull
git checkout -b hotfix/security-patch

  2. Fix and Test

  3. Fix the issue
  4. Test thoroughly

  5. Add tests

  6. Merge to Main 

    git checkout main
git merge hotfix/security-patch
git tag v1.2.1

  7. Merge to Develop (if exists) 

    git checkout develop
git merge hotfix/security-patch

  8. Delete Branch 

    git branch -d hotfix/security-patch

Release Branching (If Used)

Release Process

Steps:

  1. Create Release Branch 

    git checkout -b release/1.2.0

  2. Version Bump

  3. Update version numbers
  4. Update changelog

  5. Commit changes

  6. Final Testing

  7. Run full test suite
  8. Manual testing

  9. Fix any issues

  10. Merge to Main 

    git checkout main
git merge release/1.2.0
git tag v1.2.0

  11. Merge to Develop (if exists) 

    git checkout develop
git merge release/1.2.0

  12. Delete Branch 

    git branch -d release/1.2.0

Note: Most teams prefer tagging main directly instead of release branches.

Factory-Generated Branches

Factory Branch Naming

Format: factory/feature-description or factory/run-{runId}

Examples: - factory/invoice-service-generation - factory/run-12345 - factory/update-billing-service

Factory Branch Workflow

How Factory Uses Branches:

  1. Factory Creates Branch - Factory creates feature branch for generation
  2. Generates Code - Factory commits generated code to branch
  3. Creates PR - Factory creates PR automatically
  4. Human Review - Human engineers review PR
  5. Merge - Human merges PR after approval

Working with Factory Branches:

  • Don't modify directly - Don't commit to Factory branches manually
  • Create new branch - Create your own branch from Factory branch if you need to modify
  • Merge Factory branch - Merge Factory branch into your branch, then create PR

Example: 

# Factory creates: factory/invoice-service-generation
# You need to add custom logic:

git checkout factory/invoice-service-generation
git checkout -b feature/invoice-service-with-custom-logic
# Add your custom code
git commit -m "Add custom invoice calculation"
git push origin feature/invoice-service-with-custom-logic
# Create PR from your branch

Tip

When Factory generates a branch, create your own branch from it if you need to add custom code. Don't commit directly to Factory branches—this makes it hard to regenerate from Factory later.