1 · Ship — code → test → deploy

TL;DR

Objective — get a finished local change live the same safe way every time: pick small-vs-big, work on develop, pass the database safety gate, then deploy through the selected non-production target(s) from Zaj-PROJECT.md before production and tag the release.

User part + done-when

👤 User part — the production deploy itself is human-gated: a person runs the production push + dep deploy production, then tests critical paths on production. The user also tests the selected non-production URL after the (agent-run) non-production deploy. Everything up to production — git, the non-production deploy, the DB safety gate — is terminal-runnable by the agent; only the live-server promotion is fenced to a human (same as branch-protection and live-payment actions).

Done when the change is live on production, both manual tests passed, a version tag is pushed, and main is updated.  ·  ⏱ ~15 min – 2 hr  ·  🔀 mixed (🤖 git + staging deploy, 👤 production deploy + staging/production testing).

Background

Shipping is dangerous in exactly two ways: a migration can drop data, and a bad merge can take the site down. This workflow removes both risks by making the path identical every time — a small change and a big feature flow through the same gate, so you never improvise on the day something breaks.

Read Zaj-PROJECT.md before you start. Use its environment matrix for the real non-production branch, deploy target, URL, SSH alias, PHP binary, DB engine/collation, and production target. If this ship changes composer.json, composer.lock, Node build tooling, DB driver/collation, deploy paths, or server runtime facts, rerun the parity checks and update Zaj-PROJECT.md plus .tool-versions in the same change.

For the command-only card (Patterns A–D, quick smoke checks), use the Code → test → ship runbook.

The default branch model is develop → selected non-production branch (often staging) → production, then mirror production into main as a backup. Zaj-PROJECT.md can name several non-production rows (staging-primary, qa, uat, client-demo, etc.); deploy through the row selected for this release.

NON_PROD_BRANCH="staging" # example; source branch from Zaj-PROJECT.md
DEPLOY_TARGET="staging"   # example; Deployer target from Zaj-PROJECT.md
NON_PROD_URL="https://nonprod.example.com"
# Expected: values match the environment row selected for this ship

flowchart LR
  D["develop<br/>(work here)"] --> S["non-production<br/>(selected test server)"]
  S --> P["production<br/>(live)"]
  P --> M["main<br/>(backup)"]

Steps

0. Sync the local DB before DB-dependent UI work

Use this pre-work only when the change depends on database-backed UI state — landing pages, settings, plans, seeded content, or any admin-panel value that local cannot reproduce from code alone.

Local DB Sync before DB-dependent UI work

Do not iterate by deploying to the same non-production target twice for one DB-backed UI feature — that is a process smell; one mysqldump beats two Deployer runs. Flow: dump the selected non-production DB from Zaj-PROJECT.md → import to Herd (strip the MariaDB 11.x sandbox line, for example tail -n +2 nonprod.sql | mysql ...) → fix the local app_url / stored site URL values → clear caches. Never pull the production DB to local unless PII is sanitized. Herd: use the full path to mariadb / mysql and TCP -h 127.0.0.1 -P 3306.

1. Decide small or big

Before touching code, size the change. A one-line fix and a multi-file feature take different paths into git — getting this right keeps your history clean and your develop branch deployable.

1. Classify the change against the size table.

   Size	Definition	Action
   Small	1–3 commits, simple change	Work directly on develop
   Big	4+ commits, multi-file feature	Create a temporary branch

   • ✅ You know whether you’re working directly on develop or on a NewFeature/... branch.

2. Confirm the starting state

Stale or out-of-sync branches are the most common cause of a confusing deploy. Verify you’re on develop, up to date, and that staging/production carry nothing develop doesn’t.

1. Pull develop and confirm the branches are synced.

   git checkout develop && git pull origin develop
   git log --oneline "develop..$NON_PROD_BRANCH"     # Expected: empty (no commits)
   git log --oneline "$NON_PROD_BRANCH..production"  # Expected: empty (no commits)
   # Expected: on develop, up to date, both log commands print nothing

   • ✅ You’re on develop, up to date, and both range logs are empty.

If a server had admin-panel changes that aren’t in git yet, capture them with Server sync before you ship — otherwise this deploy can overwrite them.

3. Do the work and commit

Make the change, test it locally, and commit with the right type prefix so the history reads as a log of what kind of change shipped when.

1. For a big change, branch first. Skip this for a small change on develop.

   git checkout -b NewFeature/descriptive-name
   # Expected: switched to a new branch named NewFeature/descriptive-name

   • ✅ Big changes live on their own branch; small changes stay on develop.

2. Make the change, test locally, then commit with a typed message. Test in the browser at your local site (e.g. PROJECT.test) before committing.

   git add [files]
   git commit -m "🔨 🟪 T3 Add-Feature: [description]"
   # Bug fix instead:  🔧 🟦 T2 Fix-Bug: [description]
   # Config change:    🔧 🟦 T2 Setup-Config: [description]
   git push origin [branch]
   # Expected: the commit lands and pushes to its branch

   • ✅ The change works locally and is committed with a type prefix that matches it.

4. Clear the database safety gate

This is the non-negotiable gate before any deploy that might include migrations. A migration that drops a table or column can destroy customer data — so you inspect every pending migration and let Atlas lint flag the dangerous ones before they ever reach a server.

1. List pending migrations, then dry-run them to read the SQL.

   php artisan migrate:status                  # which migrations are pending
   php artisan migrate --pretend               # the SQL each would run — no DB change
   # Expected: a clear list; if nothing is pending, the gate is already clear

   • ✅ You can see exactly what SQL would run — or confirm nothing is pending.

2. Run Atlas lint and STOP on a destructive finding. Atlas flags dangerous operations by code; the two that block a deploy are DS102 (DROP TABLE) and DS103 (DROP COLUMN).

   atlas migrate lint --env local --latest 1
   # Expected: no DS102 / DS103. STOP if either appears — back up the DB and get explicit approval first.

   • ✅ Lint is clean, or a destructive finding was handled (database backed up, explicit approval obtained, tested on staging first).

3. Back up the database before any approved destructive op — rollback net first. A DROP, MODIFY COLUMN, or any migrate:fresh (which drops every table before re-running) must be preceded by a verified dump you can restore from.

   # Herd Pro ships MariaDB → the dump tool is mariadb-dump (mysqldump was renamed; alias it if you prefer).
   mariadb-dump -u [DB_USER] -p [DB_NAME] > "backup-$(date +%Y%m%d-%H%M%S).sql"   # or: mysqldump ...
   ls -lh backup-*.sql   # Expected: a non-empty .sql dump exists before the migration runs

   • ✅ A verified, non-empty backup exists before the destructive migration runs — or there is no destructive op to guard.

Never deploy a destructive migration without a backup — and never migrate:fresh on shared data

DROP COLUMN, DROP TABLE, TRUNCATE, and MODIFY COLUMN are high-risk. Take a verified DB dump first (step 3), get explicit approval, and prove it on staging before it touches production. php artisan migrate:fresh / migrate:reset / wipe drop all tables — never run them against staging or production data; they are local-rebuild-only commands. TRUNCATE is a hard block — manual approval only. If the dump tool is missing, install it during Prerequisites — never skip the backup because the tool wasn’t ready.

5. Deploy develop → non-production → production

With the gate clear, run the standard deploy sequence. Each environment gets a deploy, then a human test, before the next one — the selected non-production target catches what local missed; production is verified the moment it’s live.

Who does this

🤖 Agent runs the non-production git and dep deploy "$DEPLOY_TARGET" commands, and prepares + stages everything for production. 👤 User runs the production deploy themselves (git push origin production + dep deploy production) and tests after — production is human-gated, the same way branch-protection and live-payment actions are fenced from the agent. The agent never pushes or deploys to the live server; a person promotes to production and confirms it works.

1. For a big change, merge the feature branch back into develop first. Skip for small changes already on develop.

   git checkout develop && git merge NewFeature/descriptive-name
   # Expected: the feature branch is merged into develop

   • ✅ All the work is on develop before promotion begins.

2. Push develop, then promote to the selected non-production branch and deploy.

   git push origin develop
   git checkout "$NON_PROD_BRANCH" && git merge develop && git push origin "$NON_PROD_BRANCH"
   dep deploy "$DEPLOY_TARGET"
   # Expected: zero-downtime release completes on the selected non-production server

   • ✅ Non-production deployed cleanly — then 👤 test on $NON_PROD_URL and confirm the change works.

3. Promote the tested non-production branch to production and deploy. 👤 USER step — production is human-gated. Only after the selected non-production target tested clean. Who runs this — 👤 you (production is human-gated). The agent prepares and verifies everything up to this point; a human runs the actual production push + deploy. Agents are correctly fenced from production deploys (real-user / real-money actions), the same way branch-protection and live-payment actions gate them.

   git checkout production && git merge "$NON_PROD_BRANCH" && git push origin production
   dep deploy production
   # Expected: zero-downtime release completes on the production server

   • ✅ Production deployed (by 👤 you) — then 👤 test critical paths on production (login, checkout, the changed feature).

6. Tag and finalize

A live deploy isn’t done until it’s labelled and backed up. Tag the version, mirror production into main, and return to develop so the next change starts from a clean, deployable base.

1. Tag the release, update main, and return to develop. Version scheme: first update after a major is vX.X.X-a; subsequent ones -b, -c; a significant change gets a new vX.X.Y.

   git tag -a v[VERSION] -m "[Description]"
   git push origin v[VERSION]
   git checkout main && git merge production && git push origin main
   git checkout develop
   # Expected: tag pushed, main mirrors production, you're back on develop

   • ✅ The version is tagged, main matches production, and you’re on develop again. Update Zaj-CHANGELOG.md if the change was significant; delete the temp branch only with user confirmation.

Public-facing release notes must never name the CodeCanyon vendor

A public CHANGELOG-PUBLIC.md, in-app “What’s new”, or release-notes page must use the project’s own name and SemVer only — never the vendor script, author, or marketplace (WorkDo, CodeCanyon, Envato, author-vX, etc.). Keep vendor lineage in internal Zaj-CHANGELOG.md if you need it; sanitize the public one. Quick gate before tagging:

grep -inE 'workdo|codecanyon|envato|author-v[0-9]' CHANGELOG-PUBLIC.md && \
  echo "  ❌ public changelog names the vendor — sanitize before release" || \
  echo "  ✅ public changelog is vendor-neutral"
# Expected: vendor-neutral (no match). Replace your actual vendor token(s) in the pattern.

Checklist

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

• 🤖 Branches synced — on develop, up to date; develop..staging and staging..production both empty.
• 🔀 Local DB Sync handled when needed — DB-dependent UI work used a staging → Herd sync first, or this gate was explicitly marked N/A.
• 🤖 Committed with type — the change is committed with the right prefix (T3 Add-Feature, T2 Fix-Bug, etc.).
• 🔀 DB gate cleared — migrate:status reviewed, Atlas lint clean (or destructive finding handled: verified DB dump taken first, explicit approval, tested on staging). No DS102/DS103 shipped unguarded; no migrate:fresh/reset/wipe against staging or production.
• 👤 Non-production tested — the change verified on the selected non-production URL before promoting.
• 👤 Production deployed + tested — 👤 you ran the production push + dep deploy production (production is human-gated), then verified critical paths on production after deploy.
• 🤖 Tagged + main updated — version tag pushed, main mirrors production, back on develop.

→Next step

Server sync — capture server changes