# Git Branching & Release Standard

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

## 1\. Branch Structure

We use the following permanent branches:

```text
main
dev
uat
prod
```

Temporary branches:

```text
feature/*
bugfix/*
release/*
hotfix/*
```

### Branch purpose

| Branch | Purpose | Environment |
| --- | --- | --- |
| `main` | Stable integration/source-of-truth branch | — |
| `dev` | Active development | DEV |
| `uat` | UAT-approved release candidate | UAT |
| `prod` | Production code | PROD |
| `feature/*` | New functionality | — |
| `bugfix/*` | Normal bug fixes | — |
| `release/*` | Release stabilization | — |
| `hotfix/*` | Critical production fixes | — |

* * *

## 2\. Standard Development Flow

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

### Example

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

* * *

## 3\. Feature Branches

All new development must start from `dev`.

```bash
git checkout dev
git pull origin dev

git checkout -b feature/customer-payment
```

Naming:

```text
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:

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

Create from `dev`:

```text
dev
 ↓
bugfix/claim-calculation
 ↓
PR
 ↓
dev
```

* * *

## 5\. Release Branch

When the development version is ready for UAT:

```text
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.

```text
release/2.5.0
       ↓
      UAT
```

* * *

## 6\. UAT → Production

After UAT approval:

```text
release/2.5.0
       ↓
      prod
       ↓
     PROD
```

Create a Git tag:

```text
v2.5.0
```

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

* * *

## 7\. Production Hotfix

For critical production issues:

```text
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.

```text
             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.

```text
❌ Direct push → prod
❌ Direct push → uat
❌ Direct push → dev

✅ Branch → PR → Review → Merge
```

* * *

## 9\. Environment Rules

### DEV

```text
dev → DEV
```

Automatic deployment is allowed.

### UAT

```text
release/* → UAT
```

Deployment should be controlled and associated with a specific release.

### PROD

```text
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.

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

Example:

```text
ghcr.io/company/claim-api:2.5.0
```

Prefer immutable image tags/digests for production.

Avoid relying on:

```text
: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.

```text
feature/customer-login
feature/esewa-payment

bugfix/claim-calculation
bugfix/report-filter

release/2.5.0

hotfix/payment-timeout
hotfix/claim-production-error
```

Avoid:

```text
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

```text
FEATURE → DEV → RELEASE → UAT → PROD
```

### Emergency workflow

```text
PROD → HOTFIX → PROD
             ↓
        back-merge → DEV
```

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