Release Engineering, Deployment Protocols & Changelog Governance

---

1. Release Philosophy & Semantic Versioning (SemVer)

Debelu follows strict Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH) to govern changes across all applications, libraries, and database migrations.

       vMAJOR . MINOR . PATCH
         │        │       │
         │        │       └── Backward-compatible bug fixes & performance patches
         │        └────────── New features, additive schema migrations, non-breaking APIs
         └─────────────────── Breaking schema changes, major API rewrites, architectural shifts

Monorepo Version Alignment

• Shared Libraries (@debelu/ui, @debelu/core): Versioned synchronously with core platform releases.
• Independent Services (debelu-backend, storefront, debelu-marketing): Deploy continuously under trunk-based git commits on main, tagged with release milestones (v1.4.0).

---

2. Pre-Release Verification Gates

No code reaches staging or production without clearing seven mandatory automated gates:

graph TD
    PR[Pull Request Submitted to main] --> G1[Gate 1: Monorepo Typecheck & Lint]
    G1 --> G2[Gate 2: Unit & Component Tests]
    G2 --> G3[Gate 3: Live Postgres:16 Flow Tests]
    G3 --> G4[Gate 4: Playwright E2E & Axe A11y]
    G4 --> G5[Gate 5: Supply Chain & npm audit]
    G5 --> G6[Gate 6: SBOM Generation]
    G6 --> G7[Gate 7: Peer Review & 4-Eyes Sign-Off]
    G7 --> MERGE[Merge to main]

The 7 Quality Gates

1. Type & Style Check: npm run check executes TypeScript strict mode compilation (tsc --noEmit) and ESLint checks across all 6 workspace packages.
2. Unit & Integration Tests: Vitest and Jest test suites execute with $> 85%$ branch coverage across all shared financial and validation modules.
3. Database Migration Verification: In GitHub Actions (monorepo-ci.yml), a dedicated postgres:16 container boots, applies all 97 migrations from clean slate, and executes scripts/db-flow-tests.sh to prove foreign key and RLS integrity.
4. End-to-End & Accessibility: Playwright runs multi-device browser tests across Chrome, Safari, and Android viewports, enforcing zero Axe-core accessibility violations.
5. Supply Chain Security: npm audit --audit-level=high confirms zero known high/critical vulnerabilities.
6. SBOM Generation: Automatic generation and validation of CycloneDX sbom.json.
7. Maker-Checker Peer Review: At least two senior engineers must approve, with zero unresolved review comments.

---

3. Multi-Surface Deployment Sequencing

To eliminate downtime and prevent state synchronization mismatches, deployments follow an immutable sequence:

sequenceDiagram
    autonumber
    actor Rel as Release Manager
    participant DB as Supabase PostgreSQL
    participant EDGE as Supabase Edge Functions
    participant BACKEND as Railway Backend API
    participant FRONT as Cloudflare Pages (Apps)
    participant MKT as Vercel (Marketing)

    Rel->>DB: 1. Apply Backward-Compatible DB Migrations
    Note over DB: Expand Phase: Add new columns/tables safely
    Rel->>EDGE: 2. Deploy Edge Functions (paystack-webhook)
    Rel->>BACKEND: 3. Deploy Express Backend (Docker build)
    Note over BACKEND: HealthCheckService returns healthy
    Rel->>FRONT: 4. Deploy Storefront & Admin (Cloudflare Pages)
    Rel->>MKT: 5. Deploy Marketing Site (Vercel)
    Rel->>DB: 6. Apply Contract Migrations (After 48h soak)
    Note over DB: Contract Phase: Remove deprecated columns

Detailed Execution Steps

1. Database Migrations (Expand Phase):
   • Execute schema updates via Supabase CLI. Migrations must be purely additive (new columns must be nullable or have defaults).
2. Edge Functions:
   • Deploy updated Deno functions:

     supabase functions deploy paystack-webhook --project-ref <PROJECT_ID>
     supabase functions deploy deliver-notification --project-ref <PROJECT_ID>

3. Backend API (debelu-backend):
   • Railway automatically triggers Docker image build upon merge to main.
   • Deployment pauses traffic shift until GET /health/readiness returns HTTP 200 OK.
4. Storefront & Admin Console:
   • Built via Vite and published to Cloudflare Pages:

     npm run build:storefront
     npx wrangler pages deploy apps/storefront/dist --project-name debelu-storefront

5. Marketing Site (debelu-marketing):
   • Deployed to Vercel with automatic edge cache invalidation.

---

4. Rollback Playbooks per Surface

If a critical defect or financial anomaly is identified post-release:

Surface	Rollback Strategy	Time to Restore	Command / Procedure
Backend API (Railway)	Container Image Rollback	$\le 60\text{ seconds}$	railway rollback --service debelu-backend or via Railway web UI.
Storefront (Cloudflare)	Instant Atomic Deployment Switch	$\le 10\text{ seconds}$	Select previous green deployment in Cloudflare Pages dashboard and click Rollback to this deployment.
Marketing (Vercel)	Instant Instant Rollback	$\le 10\text{ seconds}$	vercel rollback <DEPLOYMENT_URL> or via Vercel dashboard.
Edge Functions	Redeploy Previous Version	$\le 90\text{ seconds}$	Check out previous git tag and run supabase functions deploy <FUNCTION>.
Database Schema	Forward-Only Compensating Migration	$\le 10\text{ mins}$	Never execute DROP statements in panic. Author a new migration reverting logic or constraints, test in staging, and apply.

---

5. Software Bill of Materials (SBOM) Governance

In compliance with modern enterprise security standards (Executive Order 14028 / NIST SP 800-218):

5.1 Generation Engine

The monorepo includes an automated SBOM generator:

• Script: [scripts/generate-sbom.mjs](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/scripts/generate-sbom.mjs)
• Standard: CycloneDX v1.5 JSON specification (sbom.json).
• Tooling: @cyclonedx/cyclonedx-npm

# Generate root and workspace SBOM
npm run generate:sbom

5.2 Storage & Auditing

• sbom.json is archived with each git release tag on GitHub Releases.
• Audited quarterly against the National Vulnerability Database (NVD) for zero-day component tracking.

---

6. Dependency Management & Version Overrides

To prevent supply chain poisoning and dependency desynchronization across workspaces, the root package.json enforces strict dependency resolutions:

{
  "overrides": {
    "dompurify": "^3.2.4",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  }
}

• Dependency Review Process: Any PR introducing a new third-party npm library requires an Architecture Decision Record (ADR) or Tech Lead sign-off evaluating bundle weight, license compatibility (MIT/Apache-2.0 only), and maintenance velocity.

---

7. Configuration & Schema Drift Prevention

Configuration drift between staging, production, and code schemas is caught via automated tooling:

7.1 Automated Drift Inspector

The repository provides [scripts/check-drift.mjs](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/scripts/check-drift.mjs), which audits:

1. Environment Variables: Confirms that every key in .env.example is present in active environment stores without missing values.
2. Database Types: Validates that [packages/core/src/types.ts](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/packages/core/src/types.ts) matches the live database catalog schema.
3. Cloudflare R2 Bucket Policies: Verifies CORS headers and public access restrictions on image buckets.

# Execute drift detection in CI
node scripts/check-drift.mjs --strict

---

8. Release Notes Template & Changelog Standards

Every production release must be accompanied by structured release notes using the template below:

# Release v[MAJOR.MINOR.PATCH] - [Release Codename]

**Release Date**: YYYY-MM-DD  
**Release Manager**: [Name]  
**Git Tag**: `vX.Y.Z`  
**Commit Range**: `vX.Y.Z-1...vX.Y.Z`  

## 🚀 New Features & Enhancements
- **Campus Commerce**: Added automated UNILAG delivery hub selection for New Hall and Jaja halls.
- **Storefront**: Upgraded product gallery to support fluid multi-image zoom and swipe gestures.

## 🐛 Bug Fixes & Stability
- **Payments**: Resolved edge-case Paystack webhook signature timing variance on high-throughput bursts.
- **Escrow**: Fixed decimal precision edge case in vendor commission deductions.

## 🔒 Security & Compliance
- Updated `dompurify` to `3.2.4` across all frontend packages.
- Validated RLS policies on `vendor_applications` table.

## 🗄️ Database Migrations
- `20261005120000_add_hub_operating_hours.sql` (Additive / Zero-Downtime)

## 📦 Dependency & SBOM Updates
- SBOM CycloneDX updated: `sha256:a1b2c3d4e5f6...`