1 / 12
Diagnostic.ly — SDLC Process

New Development Process

Branching & Deployment
Workflow

How we develop, test, and ship code — starting today

March 2026

Why We're Changing

The Problem with master

How it was

  • Everything pushed directly to master
  • No code review or pull requests
  • No staging or QA environment
  • Production deploy = git pull origin master
  • One bad commit = production is down
  • No way to test before it hits users

How it works now

  • Feature branches with pull requests
  • Code review before merging
  • 3 environments: staging, UAT, production
  • Automated CI checks on every PR
  • QA verification before production
  • Automated rollback on deploy failure

Branch Model

Three Long-Lived Branches

Branch Environment URL Purpose Who deploys
develop Staging stg.diagnostic.ly Integration testing — see your feature in a real environment Auto on merge
uat UAT uat.diagnostic.ly QA verification — test before production Auto on merge
main Production diagnostic.ly Live production — only tested code goes here Release Owner
ℹ️ Key change: master has been renamed to main. Update your local clone: git branch -m master main && git fetch origin && git branch -u origin/main main

The Big Picture

Code Flow

feature/*
Your branch
→
PR (squash)
Code review
→
develop
Staging
→
PR (merge)
QA approval
→
uat
QA testing
→
PR (merge)
Release Owner
→
main
Production
⚠️ Never push directly to main, uat, or develop. Always use pull requests.

Conventions

Branch Naming

PrefixUse forExample
feature/New featuresfeature/scheduling-calendar
fix/Bug fixesfix/login-otp-expiry
hotfix/Urgent production fixeshotfix/payment-crash
refactor/Code refactoringrefactor/user-service
docs/Documentationdocs/api-guide
test/Test additionstest/payment-edge-cases

All branches are created from and PR'd back to develop — except hotfixes, which go to main.

Day-to-Day

Developer Workflow

  1. Pull latest develop: git checkout develop && git pull
  2. Create your branch: git checkout -b feature/my-feature
  3. Write code + commit: git commit -m "feat(module): add thing"
    Pre-commit hooks auto-run Pint + ESLint + commitlint
  4. Push your branch: git push -u origin feature/my-feature
  5. Create PR to develop: gh pr create --base develop
    CI runs automatically. Wait for green checks.
  6. Get review, merge (squash). Auto-deploys to stg.diagnostic.ly
  7. Verify on staging. Does it work? If yes → ready for promotion.

Automated Checks

CI Pipeline — Runs on Every PR

Lint
Pint, ESLint
TypeScript, PHPStan
Test
PHPUnit (parallel)
Vitest
Security
composer audit
npm audit, CodeQL
Build
Vite production
build assets
Coverage
Codecov
40% threshold

CI must pass before any merge. Staging and UAT deploys now also run CI first — no broken code reaches any environment.

⚠️ If CI fails: Fix the issue in your branch and push again. The PR checks will re-run automatically.

Merge Strategies

Different Merges for Different Targets

Squash Merge → develop

All your commits become one clean commit on develop. Keeps history clean and readable.

gh pr merge --squash

Regular Merge → uat

Preserves all commits for QA traceability. QA can see exactly what changed.

gh pr merge --merge

Regular Merge → main

Full audit trail. Each merge to main represents a tested, approved release.

gh pr merge --merge

Releasing

Promotion Flow

  1. Features merged to develop. Staging auto-deploys. Team verifies on stg.diagnostic.ly
  2. Create PR: develop → uat.
    gh pr create --base uat --head develop --title "release: promote to UAT"
  3. Merge to uat. UAT auto-deploys. QA team verifies on uat.diagnostic.ly
  4. Create PR: uat → main.
    gh pr create --base main --head uat --title "release: promote to production"
  5. Release Owner approves. Merge to main. Production auto-deploys with health checks + rollback.
ℹ️ Production deploy includes: maintenance mode → backup → migrate → cache → health check → auto-rollback on failure

Emergency Fixes

Hotfix Process

For urgent production issues (P1/P2) only. This is the one exception to the normal flow.

# 1. Branch from main (not develop)
git checkout main && git pull
git checkout -b hotfix/fix-critical-bug

# 2. Fix + regression test (mandatory)
git commit -m "fix: resolve critical auth issue"

# 3. PR directly to main
gh pr create --base main

# 4. After merge: back-merge main into develop and uat
git checkout develop && git merge main && git push
git checkout uat && git merge main && git push
⚠️ Every bug fix must include a regression test. No exceptions — this is a governance rule.

Action Items

What You Need to Do Today

  1. Update your local clone — rename master to main:
    git branch -m master main
    git fetch origin
    git branch -u origin/main main
    git remote set-head origin -a
  2. Never push to main, uat, or develop directly. Always create a feature branch and PR.
  3. Use conventional commits: feat(scope): description, fix(scope): description
  4. Read the full docs: docs/branching-workflow.md in the repo

Quick Reference

New feature?Branch from develop, PR to develop
Bug fix?Branch from develop, PR to develop
Production on fire?Branch from main, PR to main, back-merge
Ready for QA?PR from develop → uat
Ready for prod?PR from uat → main
CI failing?Fix it in your branch, push again

Full documentation: docs/branching-workflow.md

Questions? Reach out to Jostein or check the docs.