Skip to content
ZajLibrary
prod e051e98
Browse

7 · Release + incident response

TL;DR

Section titled “TL;DR”

Objective — close the phase with two release disciplines: a versioned, changelogged release you can point to and roll back to, and an incident-response runbook (Sentry, uptime, SSL expiry, severities, contacts) wired into the repo as dev-only — the difference between a calm incident and a scramble.

Background

Section titled “Background”

Steps

Section titled “Steps”

1. Audit existing release infrastructure

Section titled “1. Audit existing release infrastructure”

Decide whether to bootstrap a new changelog or extend an existing one (single-file vs the dual-file pattern some CodeCanyon kits ship).

  1. Inventory changelogs, version, and tags.

    Terminal window
    ls CHANGELOG.md HISTORY.md changelog.txt 2>/dev/null   # any existing changelog?
    grep '"version"' composer.json                          # current version, if set
    git tag --list | tail                                   # existing release tags
    # Expected: whatever changelog files exist, the current composer.json version, and recent tags
    • ✅ You know whether to bootstrap a new changelog or extend an existing one, and the current version/tags.

2. Determine the version number

Section titled “2. Determine the version number”

Use SemVer relative to what shipped: MAJOR.MINOR.PATCH. For a first managed release, 1.0.0 is reasonable if the vendor baseline is unversioned; otherwise increment from the latest tag.

3. Write the changelog

Section titled “3. Write the changelog”

Bootstrap when none exists; otherwise prepend the new version block and keep the existing format.

  1. Write (or prepend) the version block.

    # Changelog
    

    All notable changes to this project are documented here.
    This project adheres to [Semantic Versioning](https://semver.org/).
    

    ## [1.0.0] — 2026-06-09
    ### Added
    - Initial managed release on the deploy pipeline.
    ### Changed
    ### Fixed
    • ✅ The changelog carries the new version block; for dual-file kits (e.g. a public CHANGELOG.md + an internal one), both are updated so they don’t drift.

4. Bump version and tag

Section titled “4. Bump version and tag”

Commit the changelog + version bump together, then tag and push.

  1. Commit, tag, and push the release.

    Terminal window
    # Update composer.json version (if the kit tracks it there)
    # then commit the changelog + version bump together
    git add CHANGELOG.md composer.json
    git commit -m "release: v1.0.0"
    git tag -a v1.0.0 -m "v1.0.0 — initial managed release"
    git push origin main
    git push origin v1.0.0   # push only this release tag; never use the all-tags push form
    # Expected: the release commit and the v1.0.0 tag are pushed to the remote
    • ✅ The release is committed, tagged vX.Y.Z, and only that tag is pushed.

5. Audit incident-response infrastructure

Section titled “5. Audit incident-response infrastructure”

Check what already exists: Deployer’s rollback task, DB backup job, health-check endpoint, Sentry/error tracking.

  1. Inventory the runbook, error tracking, and rollback task.

    Terminal window
    ls INCIDENT.md docs/runbook.md 2>/dev/null      # existing runbook?
    grep -ri 'sentry' config/ .env.example          # error tracking wired?
    dep list 2>/dev/null | grep -q rollback && echo "rollback available"
    # Expected: any existing runbook, whether Sentry is referenced, and rollback task listed by dep list
    • ✅ You know what incident infrastructure already exists (runbook, Sentry, rollback task).

6. Pick a runbook strategy

Section titled “6. Pick a runbook strategy”
StrategyWhenResult
FullReal users, on-call expectedComplete runbook with all sections below
PartialLaunching soon, basics in placeCore sections; flesh out post-launch
Blank templatePre-launch, no traffic yetScaffold with TODOs so structure exists

7. Write the runbook content

Section titled “7. Write the runbook content”

A partial-to-full INCIDENT.md should cover:

  • Detection — Sentry alerts, uptime monitor (UptimeRobot/Better Stack), SSL-expiry monitor (cert from page 2 expires every 90 days).
  • Severity levels — e.g. SEV1 site down, SEV2 degraded, SEV3 minor — with response-time expectations.
  • Emergency contacts — who to call, in order; provider support links.
  • Playbook per failure — site down, deploy failed, DB issue, SSL expired — each with first commands.
  • Rollback — dep rollback production flips current back to the previous release (retention set in 1 · Deployer).
  • Pre-deploy checks — the gate to run before every production deploy.

8. Wire INCIDENT.md as dev-only

Section titled “8. Wire INCIDENT.md as dev-only”

The runbook is internal — it must never ship to the server. Add it to both the clear_paths/GIT_ONLY_PATHS pair from 4 · CI + ServerSync so it stays in Git but is stripped from releases.

  1. Confirm INCIDENT.md is in both path lists.

    Terminal window
    grep -A20 'clear_paths' deploy.php | grep INCIDENT
    grep 'GIT_ONLY_PATHS' .github/workflows/*.yml | grep INCIDENT
    # Expected: INCIDENT.md appears in both the clear_paths block and GIT_ONLY_PATHS
    • ✅ INCIDENT.md appears in both clear_paths and GIT_ONLY_PATHS.

Checklist

Section titled “Checklist”

Do not mark this step done until every box below is checked.

  • 🔀 Version + changelog — version determined (SemVer); CHANGELOG.md bootstrapped or updated (both files if dual-file).
  • 🤖 Release tagged — release committed and tagged vX.Y.Z; only that tag pushed (not --tags).
  • 🔀 Runbook complete — strategy chosen; INCIDENT.md covers detection, severities, contacts, rollback, pre-deploy checks.
  • 🤖 Dev-only wiring — INCIDENT.md present in both clear_paths and GIT_ONLY_PATHS.
  • 🤖 Rollback ready — dep rollback confirmed available as the recovery path.

The pipeline is wired. Continue to Phase 5 · Staging deploy — take the app from “runs locally” to “runs on a real server.”