====== Team Branching & Release Policy ====== ===== 1. Purpose ===== 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. ===== 2. Branch Overview & Intent ===== | Branch | Purpose | Deployment Behavior | | **Dev** | Active development & feature integration | Auto deploy to **DEV** | | **Main** | Stable, release-ready code | Auto deploy to **TEST** | | **Test** | Staging / UAT validation | Auto deploy to **STAGING** | | **Demo** | Commercial / pre-sales demo features | Manual deploy to **DEMO** | | **Production** | Live system | Manual approval deploy to **PRODUCTION** | ===== 3. General Rules (Applies to All Branches) ===== 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 ===== 4. Standard Development & Release Flow ===== 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. ==== 4.1 Feature Development ==== **Branch Creation & Development Commands** git checkout Dev\\ git pull origin Dev\\ git checkout -b feature/ After development: git add .\\ git commit -m "feat: "\\ git push origin feature/ 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 ==== 4.2 Promotion to Test ==== **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 ==== 4.3 Promotion to Staging (UAT) ==== **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 ==== 4.4 Production Release ==== **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 ===== 5. Demo Branch Policy (Commercial / Pre-Sales Use) ===== ==== 5.1 Purpose of Demo Branch ==== 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. ==== 5.2 Demo Branch Creation ==== **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 ==== 5.3 Demo Development Rules ==== **Demo Feature Branch Commands** git checkout Demo\\ git pull origin Demo\\ git checkout -b demo/ After implementation: git add .\\ git commit -m "demo: "\\ git push origin demo/ 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 ==== 5.4 Demo Review & Merge Process ==== PRs targeting **Demo** require: Technical Lead review Product / Business stakeholder awareness CI checks include: Build validation Basic functional tests ==== 5.5 Demo Deployment ==== Demo deployments are **manual only** Deployed to a dedicated **DEMO environment** Access is restricted and monitored No automatic promotion to other branches ===== 6. Demo Decision Outcomes ===== ==== Common Commands for Cherry-Picking Approved Demo Code ==== git checkout Dev\\ git pull origin Dev\\ git cherry-pick \\ git push origin Dev ===== 7. Hotfix Policy (Production Critical Fixes) ===== ==== 7.1 Purpose of Hotfix ==== 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. ==== 7.2 Hotfix Branch Creation ==== Hotfix branches are always created from **Production**. **Commands** git checkout Production\\ git pull origin Production\\ git checkout -b hotfix/ ==== 7.3 Hotfix Development & Validation ==== After implementing the fix: git add .\\ git commit -m "hotfix: "\\ git push origin hotfix/ 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 ==== 7.4 Forward-Merge Hotfix to Lower Branches (Mandatory) ==== After production deployment, the hotfix **must be propagated forward** to avoid regression. === Step 1: Production → Test === Production → Test === Step 2: Test → Main === Test → Main === Step 3: Main → Dev === Main → Dev **Optional (if relevant):** Main → Demo This ensures all active branches contain the hotfix. ==== 7.5 Hotfix Restrictions ==== 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 ==== 7.6 Hotfix Summary Flow ==== hotfix/*\\ ↓\\ Production ──▶ PROD\\ ↓\\ Test ──▶ STAGING\\ ↓\\ Main ──▶ TEST\\ ↓\\ Dev ──▶ DEV ===== 8. Branch Protection & Approvals ===== ==== Common Commands for Cherry-Picking Approved Demo Code ==== git checkout Dev\\ git pull origin Dev\\ git cherry-pick \\ git push origin Dev ==== 6.1 Demo Approved for Productization ==== 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 ==== 6.2 Demo Rejected or Deferred ==== If a demo feature is rejected: - Demo branch is archived or reset - No merge into Dev/Main/Test - No impact on production code ===== 7. Branch Protection & Approvals ===== | Branch | Protection Rules | | **Dev** | PR required, CI mandatory | | **Main** | PR + full test suite | | **Test** | PR + UAT approval | | **Demo** | PR required, limited reviewers | | **Production** | PR + restricted approvers + manual approval | ===== 8. Artifact & Configuration Policy ===== 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 ===== 9. Compliance, Audit & Risk Management ===== Every deployment is traceable to: Commit PR Approval Demo work is isolated from regulated releases Rollback is possible via artifact redeployment ===== 10. Ownership & Enforcement ===== Engineering leadership owns this policy CI/CD pipelines enforce compliance Exceptions require written approval from Architecture & Product ===== 11. Summary ===== 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.