Version: 1.0 Applies to: All development teams and repositories Environments: DEV, UAT, PROD

1. Branch Structure

We use the following permanent branches:

main
dev
uat
prod

Temporary branches:

feature/*
bugfix/*
release/*
hotfix/*

Branch purpose

2. Standard Development Flow

feature/*
     ↓
    PR
     ↓
   dev
     ↓
    DEV
     ↓
release/*
     ↓
    UAT
     ↓
   UAT
     ↓
   prod
     ↓
   PROD

Example

feature/payment-integration
        ↓
       PR
        ↓
       dev
        ↓
       DEV
        ↓
release/2.5.0
        ↓
       UAT
        ↓
       prod
        ↓
      PROD

3. Feature Branches

All new development must start from dev.

git checkout dev
git pull origin dev
 
git checkout -b feature/customer-payment

Naming:

feature/customer-payment
feature/google-login
feature/claim-search

Keep feature branches short-lived.

Do not directly commit to dev, uat, or prod.

4. Bug Fixes

Normal bugs:

bugfix/claim-calculation
bugfix/payment-callback
bugfix/report-filter

Create from dev:

dev
 ↓
bugfix/claim-calculation
 ↓
PR
 ↓
dev

5. Release Branch

When the development version is ready for UAT:

dev
 ↓
release/2.5.0

After creating a release branch:

• No new features

• Only bug fixes

• Release/configuration fixes are allowed

• Changes require PR/review

The release branch is deployed to UAT.

release/2.5.0
       ↓
      UAT

6. UAT → Production

After UAT approval:

release/2.5.0
       ↓
      prod
       ↓
     PROD

Create a Git tag:

v2.5.0

Production must always be traceable to a specific commit/tag.

7. Production Hotfix

For critical production issues:

prod
 ↓
hotfix/payment-failure
 ↓
PR
 ↓
prod
 ↓
PROD

After the hotfix is released, the fix must be merged/back-ported into dev and any active release branch that contains the affected code.

             hotfix
            /   |   \
           ↓    ↓    ↓
         prod  uat   dev

This prevents the production fix from being lost in future releases.

8. Pull Request Rules

Every change must go through a Pull Request.

Minimum requirements:

• CI/build must pass

• Tests must pass

• Code review required

• No unresolved comments

• No merge conflicts

• Branch must be up to date where required

Production branches must be protected.

❌ Direct push → prod
❌ Direct push → uat
❌ Direct push → dev
 
✅ Branch → PR → Review → Merge

9. Environment Rules

DEV

dev → DEV

Automatic deployment is allowed.

UAT

release/* → UAT

Deployment should be controlled and associated with a specific release.

PROD

prod → PROD

Production deployment requires explicit approval.

10. Docker / CI-CD Rule

Build once, deploy the same artifact.

Do not rebuild the application separately for DEV, UAT, and PROD.

Source Code
    ↓
Build
    ↓
Docker Image
    ↓
GHCR
    ↓
DEV
    ↓
UAT
    ↓
PROD

Example:

ghcr.io/company/claim-api:2.5.0

Prefer immutable image tags/digests for production.

Avoid relying on:

:latest

for production deployments.

11. Database Migration Rule

Database migrations must be:

1. Created and tested in DEV

2. Tested in UAT

3. Reviewed before PROD

4. Executed in a controlled deployment process

Avoid automatically running destructive database migrations during application startup in PROD.

12. Branch Naming Standard

Use lowercase and descriptive names.

feature/customer-login
feature/esewa-payment
 
bugfix/claim-calculation
bugfix/report-filter
 
release/2.5.0
 
hotfix/payment-timeout
hotfix/claim-production-error

Avoid:

test
new-feature
fix
my-branch
ejan-work
temp
final
final2

13. Golden Rules

Every developer should remember these 10 rules:

1. Never push directly to prod.

2. Never push directly to uat.

3. Use a feature/bugfix branch for development.

4. All changes go through PR and code review.

5. dev is for active development.

6. release/* is for UAT stabilization.

7. uat contains the release being validated.

8. prod contains production code.

9. Every production release gets a version tag.

10. Production/UAT fixes must be back-merged into dev.

One-line workflow

FEATURE → DEV → RELEASE → UAT → PROD

Emergency workflow

PROD → HOTFIX → PROD
             ↓
        back-merge → DEV

This is the standard I would put into your team's engineering documentation.