This document defines the official branching, promotion, and deployment policy for the engineering team. The objective is to: - Maintain code quality and release stability - Enable controlled promotion across environments - Support commercial/demo-only functionality without impacting core development - Ensure auditability, traceability, and governance

This policy is mandatory for all repositories following this model.

Direct commits to protected branches are strictly prohibited

All changes must go through Pull Requests (PRs)

CI checks must pass before merge

Forward-only promotion (no reverse merges)

Every deployment must be traceable to a PR and commit

The following sections include standard Git commands to be used by the team. These commands are indicative and must be executed only after pulling the latest changes from the remote repository.

Branch Creation & Development Commands

git checkout Dev
git pull origin Dev
git checkout -b feature/<feature-name>

After development:

git add .
git commit -m “feat: <short description>“
git push origin feature/<feature-name>

Create a Pull Request:

feature/* → Dev

On merge, code is automatically deployed to the DEV environment.

Developers create feature branches from Dev

Feature branches are merged back into Dev via PR

Merge to Dev automatically deploys to DEV environment

Promotion Commands

git checkout Dev
git pull origin Dev
git checkout Main
git pull origin Main

Create a Pull Request:

Dev → Main

On merge to Main: - Artifact is built once - Full test suite runs - Code is deployed automatically to the TEST environment

PR is raised from Dev → Main

On merge, pipeline:

Builds artifact (once)

Runs full test suite

Deploys to TEST environment

Promotion Commands

git checkout Main
git pull origin Main
git checkout Test
git pull origin Test

Create a Pull Request:

Main → Test

On merge: - Same artifact is deployed to STAGING - UAT and integration tests are executed

PR is raised from Main → Test

No new code changes allowed

On merge, pipeline deploys the same artifact to STAGING

UAT and integration tests are executed

Promotion Commands

git checkout Test
git pull origin Test
git checkout Production
git pull origin Production

Create a Pull Request:

Test → Production

After required approvals: - Manual production deployment is triggered - Smoke tests are executed

PR is raised from Test → Production

Requires approvals from authorized reviewers only

Deployment requires manual environment approval

Post-deployment smoke tests are mandatory

The Demo branch exists to support: - Commercial discussions - Customer-specific demonstrations - Proof-of-concept features - Business validation prior to development commitment

Demo functionality is not part of the committed product roadmap until approved.

Demo Branch Creation Commands

git checkout Main
git pull origin Main
git checkout -b Demo
git push origin Demo

Rules: - Demo branch always originates from Main - No direct commits allowed

Demo branch must always be created from Main

No direct commits are allowed

Only demo-related changes permitted

Demo Feature Branch Commands

git checkout Demo
git pull origin Demo
git checkout -b demo/<demo-feature-name>

After implementation:

git add .
git commit -m “demo: <short description>“
git push origin demo/<demo-feature-name>

Create a Pull Request:

demo/* → Demo

Rules: - Demo code must be feature-flagged - Configuration-driven - Fully reversible

Demo code must be:

Feature-flagged

Config-driven

Reversible

No permanent database schema changes without architecture approval

Demo code must not block or delay regular releases

PRs targeting Demo require:

Technical Lead review

Product / Business stakeholder awareness

CI checks include:

Build validation

Basic functional tests

Demo deployments are manual only

Deployed to a dedicated DEMO environment

Access is restricted and monitored

No automatic promotion to other branches

git checkout Dev
git pull origin Dev
git cherry-pick <commit-sha>
git push origin Dev

Hotfixes are used only for critical production issues such as: - Production outages - Security vulnerabilities - Data integrity issues

Hotfixes must follow a controlled and traceable path and must not bypass environments.

Hotfix branches are always created from Production.

Commands

git checkout Production
git pull origin Production
git checkout -b hotfix/<issue-id-or-description>

After implementing the fix:

git add .
git commit -m “hotfix: <short description>“
git push origin hotfix/<issue-id-or-description>

Create a Pull Request:

hotfix/* → Production

Requirements: - Mandatory senior reviewer approval - CI build and critical tests must pass

On merge: - Hotfix is deployed to PRODUCTION with manual approval - Smoke tests are executed immediately

After production deployment, the hotfix must be propagated forward to avoid regression.

Production → Test

Test → Main

Main → Dev

Optional (if relevant):

Main → Demo

This ensures all active branches contain the hotfix.

Hotfix branches must be short-lived

No new features allowed

No refactoring unless required to fix the issue

Demo-only code is not allowed in hotfixes

hotfix/*
↓
Production ──▶ PROD
↓
Test ──▶ STAGING
↓
Main ──▶ TEST
↓
Dev ──▶ DEV

git checkout Dev
git pull origin Dev
git cherry-pick <commit-sha>
git push origin Dev

If a demo feature is approved:

Relevant commits are cherry-picked or merged into Dev

Demo-only configuration is removed

Feature flags are reviewed for production readiness

Feature follows standard promotion path:

Dev → Main → Test → Production

If a demo feature is rejected: - Demo branch is archived or reset - No merge into Dev/Main/Test - No impact on production code

Artifacts are built once (on Main)

Same artifact is promoted across environments

Environment differences handled via configuration only

Demo uses feature flags, not forked artifacts

Every deployment is traceable to:

Commit

PR

Approval

Demo work is isolated from regulated releases

Rollback is possible via artifact redeployment

Engineering leadership owns this policy

CI/CD pipelines enforce compliance

Exceptions require written approval from Architecture & Product

This branching and demo policy ensures: - Stable and predictable releases - Safe experimentation for commercial needs - Strong governance and audit readiness - Minimal risk to production systems

All team members are expected to understand and follow this policy.