7 · Release + incident response

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.

Steps at a glance:

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).
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 — Bootstrap when none exists; otherwise prepend the new version block and keep the existing format.
4. Bump version and tag — Commit the changelog + version bump together, then tag and push.
5. Audit incident-response infrastructure — Check what already exists: Deployer’s rollback task, DB backup job, health-check endpoint, Sentry/error tracking.
6. Pick a runbook strategy — choose whether to adapt an existing incident runbook or create one, so production failures have a known response path.
7. Write the runbook content — A partial-to-full Zaj-INCIDENT.md should cover detection, rollback, contacts, and first-response commands.
8. Wire Zaj-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.

User part + done-when

👤 User part — a person chooses the SemVer number and the runbook strategy, and fills in the human details (emergency contacts, on-call order). An agent audits existing release/incident infrastructure, drafts and bumps the changelog, tags and pushes the release, and wires Zaj-INCIDENT.md into the symmetric path lists.

Done when the version is determined and Zaj-CHANGELOG.md is bootstrapped/updated, the release is committed and tagged vX.Y.Z and only that tag is pushed (not git push --tags), the runbook covers detection/severities/contacts/rollback/pre-deploy checks, Zaj-INCIDENT.md is in both clear_paths and GIT_ONLY_PATHS, and dep rollback is confirmed available.  ·  ⏱ ~30–45 min  ·  🔀 mixed (👤 version + contacts, 🤖 changelog/tag/wiring).

Background

SHOULD — release hygiene + operability

Two final disciplines before staging deploys begin: a versioned, changelogged release you can point to and roll back to, and a runbook for when production breaks. Both make the difference between a calm incident and a scramble.

Steps

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.

   ls Zaj-CHANGELOG.md 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

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

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 the two-changelog model (internal vendor-aware + public sanitized), both are updated so they don’t drift.

A public changelog must never name the CodeCanyon vendor

The release you’re about to commit and push is public. A public docs/public-changelog.md / release-notes page must never name the vendor — not the vendor name, marketplace name, or vendor product name, nor an author-vX tag. That’s a product-naming rule (customers see your brand, not the underlying script) and basic operational hygiene. Keep two documents per the project-standards two-changelog model: an internal Zaj-CHANGELOG.md (may record the vendor base) and a public sanitized one. “Upgraded vendor base v7.6 → v7.8” is internal-only; the public note for the same release reads “Performance and reliability improvements.”

Run this scrub gate on the public document before the tag/push in step 4 — it must print ✅ clean:

PUBLIC=docs/public-changelog.md           # or CHANGELOG.md if you ship a single public file
if grep -iE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC" >/dev/null 2>&1; then
  echo "❌ vendor reference leaked into $PUBLIC — sanitize before publishing:"
  grep -inE 'workdo|codecanyon|envato|author-v|dash[- ]?saas' "$PUBLIC"
else
  echo "✅ clean — no vendor references in $PUBLIC"
fi
# Expected: ✅ clean — add YOUR vendor's product name(s) to the pattern so the grep catches the exact script you're built on

If the in-app “What’s new” surface pulls from a changelog, point it at the public file, never the internal one.

4. Bump version and tag

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

1. Commit, tag, and push the release.

   # Update composer.json version (if the kit tracks it there)
   # then commit the changelog + version bump together
   git add Zaj-CHANGELOG.md docs/public-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.

Tag conventions in this pipeline

Keep the three tag types distinct: vendor baseline (untouched CodeCanyon import), checkpoint (pre-risky-change safety net), and release (vX.Y.Z, shippable). The release tag is what you roll back to.

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.

   ls Zaj-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

Strategy	When	Result
Full	Real users, on-call expected	Complete runbook with all sections below
Partial	Launching soon, basics in place	Core sections; flesh out post-launch
Blank template	Pre-launch, no traffic yet	Scaffold with TODOs so structure exists

7. Write the runbook content

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

• Detection — Sentry alerts, uptime monitor (UptimeRobot / Better Stack / MonSpark), SSL-expiry monitor (cert from page 2 expires every 90 days). When an agent helps in those vendor consoles, use the vendor console automation guide so login and secret-copy moments stay human-owned while non-secret setup is agent-driven.
• 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 Zaj-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 Zaj-INCIDENT.md is in both path lists.

   grep -A25 'clear_paths' deploy.php | grep 'Zaj-INCIDENT.md'
   grep 'GIT_ONLY_PATHS' .github/workflows/*.yml | grep 'Zaj-INCIDENT.md'
   # Expected: Zaj-INCIDENT.md appears in both the clear_paths block and GIT_ONLY_PATHS

   • ✅ Zaj-INCIDENT.md appears in both clear_paths and GIT_ONLY_PATHS.

Legacy unprefixed incident runbooks

If an older project already has a root incident runbook without the Zaj- prefix, move it to Zaj-INCIDENT.md and update every reference in the same commit. Zaj-authored, renameable root files must follow the Zaj- ownership rule.

Symmetry again

Zaj-INCIDENT.md must appear in both lists. In clear_paths only → ServerSync may re-pull then it gets wiped. In GIT_ONLY_PATHS only → it can leak into a release. Both, always.

Checklist

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

• 🔀 Version + changelog — version determined (SemVer); Zaj-CHANGELOG.md bootstrapped or updated (internal + public if two-changelog).
• 🤖 Public changelog scrubbed — the vendor-leak scrub gate prints ✅ clean on the public document before the tag/push (no workdo|codecanyon|envato|author-v|<vendor product>).
• 🤖 Release tagged — release committed and tagged vX.Y.Z; only that tag pushed (not --tags).
• 🔀 Runbook complete — strategy chosen; Zaj-INCIDENT.md covers detection, severities, contacts, rollback, pre-deploy checks.
• 🤖 Root name verified — the standing root runbook is Zaj-INCIDENT.md, not an unprefixed incident file.
• 🤖 Dev-only wiring — Zaj-INCIDENT.md present in both clear_paths and GIT_ONLY_PATHS.
• 🤖 Rollback ready — dep rollback confirmed available as the recovery path.

→Next step

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