2 · Apply the update

TL;DR

Objective — bring the new vendor files into the repo on a branch you can throw away, then merge and migrate — so your live code is never touched until the update is proven safe.

User part + done-when

👤 User part — one thing only: unzip the new vendor release into the project with your file manager, not the command line, so file permissions and hidden files copy correctly. Everything else — the backup tag, the branch, the merge, the migrations — is agent-runnable.

Done when the new author/vY.Y.Y branch holds the vendor files, the merge to develop is clean, migrations ran, and a backup tag exists to roll back to.  ·  ⏱ ~30–45 min  ·  🔀 mixed (👤 unzip, 🤖 git + migrations).

Background

The schema diff (step 1) told you what will change. This step makes it happen — reversibly. Two safety nets do the work: a backup tag captured before anything changes, and the branch model where the new release lands on its own author/vY.Y.Y branch, frozen and pristine, before it ever merges into your working code.

That branch model is the spine of the whole vendor-update strategy. Each vendor release gets its own frozen author/vX.X.X branch; your changes live downstream on develop. Merging a new author branch into develop is what surfaces conflicts cleanly — and because your customizations sit in update-safe homes (Workflow 3), there should be almost none.

flowchart TD
  T["Tag backup<br/>before-vY.Y.Y"] --> A["Branch<br/>author/vY.Y.Y"]
  A --> U["Drop in new<br/>vendor files"]
  U --> C["Commit frozen<br/>vendor baseline"]
  C --> M["Merge into<br/>develop"]
  M --> R["composer install<br/>+ migrate"]

Steps

1. Tag a rollback point before anything changes

The cheapest insurance there is. A backup tag is a named save-point — if the update goes wrong, you check it out and you’re back where you started.

1. Create and push a dated backup tag from your current production state.

   git checkout production
   git pull origin production
   git tag backup-$(date +%Y-%m-%d)-before-vY.Y.Y
   git push origin backup-$(date +%Y-%m-%d)-before-vY.Y.Y
   # Expected: a new tag named backup-<today>-before-vY.Y.Y exists locally and on the remote

   • ✅ A dated backup tag exists on the remote; git tag | grep backup lists it.

Back up the database too, if step 1 flagged a destructive change

The git tag protects your code. If the schema diff flagged a DROP or TRUNCATE, also dump the database before migrating — mysqldump -u USER -p DB > backup.sql — because no git tag can restore deleted rows.

2. Create the frozen author branch

Branch off your current frozen baseline and name the new branch for the new version. This is where the vendor files land — kept clean, with none of your customizations, so it stays a true mirror of what the vendor shipped.

1. Create the new author branch for the incoming version.

   git checkout -b author/vY.Y.Y
   # Expected: now on branch author/vY.Y.Y, branched from your frozen baseline

   • ✅ git branch --show-current prints author/vY.Y.Y.

This branch must stay vendor-pure — never commit a customization here. Its only job is to record exactly what the vendor shipped, so future diffs (like the one you just ran) stay honest.

3. Drop in the new vendor files

Replace the tracked vendor files with the new release. The clean way is to un-track everything, unzip the new files over the project, then re-add — so deletions and renames are captured, not just additions.

Who does this

🔀 User + Agent — the agent runs the git rm / git add / commit bookends; 👤 User unzips the vendor release into the project root with a file manager (Finder, not the terminal), so permissions and dotfiles copy correctly.

1. Un-track the current vendor files so the next git add records a true replace.

   git ls-files -z | xargs -0 git update-index --force-remove --
   # Expected: all tracked files are staged for removal (working files stay on disk)

   • ✅ git status shows the tracked tree staged as deleted; your files are still present on disk.

2. Unzip the new vendor release over the project root — 👤 with your file manager, overwriting when prompted. Do not use the command line for this.

   • ✅ The new vendor files are in place; the version in the vendor’s own version file matches the release you downloaded.

3. Re-add everything and commit the frozen baseline.

   git add .
   git commit -m "Import vendor vY.Y.Y"
   git push origin author/vY.Y.Y
   # Expected: a single commit capturing the new vendor files as the frozen vY.Y.Y baseline

   • ✅ One commit records the new baseline; the author/vY.Y.Y branch is pushed.

Prefer the clean full-replace for routine updates

The git rm --cached → unzip → git add flow is the recommended path for a normal release — it captures the vendor’s deletions and renames automatically. Reach for a selective copy of just a few folders only when you’re applying a partial or cherry-picked update.

4. Merge into develop and migrate

Bring the new baseline down into your working branch, then install dependencies and run migrations. Because your customizations live in update-safe homes, conflicts should be rare — and the few that appear follow one simple rule.

1. Merge the author branch into develop.

   git checkout develop
   git merge author/vY.Y.Y
   # Expected: a clean merge, or conflicts confined to vendor files you deliberately edited

   • ✅ The merge completes; any conflicts are in known vendor files, not in your _zaj tables or ZajModules.

2. Resolve conflicts by the golden rule — your changes win in your homes, vendor wins in theirs.

   Conflict	Resolution
   New vendor file	Accept the vendor version
   Vendor file you edited	Keep your logic; re-apply over the new vendor base
   A _zaj table or ZajModule	Should never conflict — if it does, your customization strategy leaked into vendor space

   • ✅ Every conflict is resolved; no _zaj or ZajModule file was in conflict (or you’ve noted why it was).

3. Install dependencies, preview, then run migrations.

   composer install
   npm install && npm run build
   php artisan migrate --pretend   # preview one more time
   php artisan migrate
   php artisan optimize:clear
   # Expected: only the changes you classified in step 1 are applied; caches cleared

   • ✅ Migrations apply exactly the changes you classified earlier; the app boots with php artisan serve.

composer install just reverted your overlay

Running composer install restores vanilla vendor files — which means your vendor-customizations overlay is now gone from vendor/. That is expected, and it is exactly what the next step fixes. Do not test customized behavior until you’ve restored the overlay.

Checklist

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

• 🤖 Backup tagged — a dated backup-…-before-vY.Y.Y tag exists on the remote (plus a DB dump if a destructive change was flagged).
• 🤖 Author branch created — on author/vY.Y.Y, branched from the frozen baseline.
• 🔀 Vendor files imported — 👤 unzipped via file manager; 🤖 committed as one frozen-baseline commit and pushed.
• 🤖 Merged to develop — merge clean; conflicts confined to known vendor files, none in _zaj/ZajModules.
• 🤖 Migrated — composer install + migrate ran; only the classified changes applied; app boots.

→Next step

Restore customizations