Updating a site

A TAW theme updates like a package. taw update updates taw/core, applies the framework's files, runs the migrations and the checks, commits on a new branch, and opens a pull request. It asks no questions: the theme's taw.json already answers them. Available from taw/core 1.91.

taw update

What one update does

--plan says what it would do without changing anything. --no-deliver stops at the commit. Every option: update in the command reference.

The policy: taw.json

The theme's taw.json belongs to the site, and updates never change it. Every setting is optional; these are the defaults:

{
  "$schema": "./vendor/taw/core/resources/schema/taw-json-1.0.json",
  "update": {
    "core": "minor",
    "scaffold": "auto",
    "manifests": "add+bump",
    "docs": "framework-sections",
    "checks": ["lint", "phpstan", "test", "build"],
    "deliver": "pr",
    "remote": "origin"
  }
}

taw policy explains the current settings in words, and --init writes a starter file. If the file is invalid, updates refuse to run until it's fixed, so nothing is ever half applied.

What the policy governs

Migrations follow taw.json wherever they run: in taw update, in the Composer hook below, and in taw upgrade --apply. scaffold: off holds back the site-skills and configs migrations, and docs: off holds back agent-docs. A held-back migration doesn't run, and it says so:

1.91.0/agent-docs is off in taw.json ("docs": "off"), so it didn't run. To do it anyway: vendor/bin/taw upgrade --explain 1.91.0/agent-docs (By hand).

The update report lists it under "Off in taw.json", and upgrade --json under held. With scaffold: off, update also skips the framework files.

The commands for one part of the framework do what you ask, whatever the policy says: sync --apply (Tier 1 files), skills:sync --apply, docs:sync --apply and configs:sync --apply.

When something fails

Nothing is pushed. The work stays on the update branch, and .taw/update-report.md lists:

• what failed, with the command and its output;
• why that kind of failure usually happens, and the steps to fix it;
• how to check the fix, how to finish the update, and how to undo it.

It's written for whoever picks it up. The site owner reads the summary at the top; a developer follows the steps. It's also a complete prompt: to have Claude finish the update, give it this file, or press Fix with Claude in taw-fleet. A person and an agent follow the same guide, so you can always finish an update by hand. When everything passes, the report is the pull request's description.

Plain composer update works too

Both scaffolds list taw/core's Composer hook, so composer update also runs any migrations the theme still needs and taw.json allows, quietly when there are none. It never fails the update: a migration that fails prints how to do it by hand. Review the changes and commit them with composer.lock. composer install doesn't run migrations, because it must reproduce the lock file exactly.

"scripts": {
    "post-update-cmd": ["TAW\\CLI\\ComposerScripts::postUpdate"]
}

Turn it off with TAW_NO_UPGRADE=1, or "extra": {"taw": {"upgrade": false}} in composer.json.

The migrations so far:

A migration keeps no record of having run: it looks at the theme each time, so running it again changes nothing.

From taw-fleet

In taw-fleet, u on a site (or taw-fleet update <site>) is Update this site. It asks one question, worded from taw.json, such as "Update acme-shop? taw/core, framework files, migrations, checks, then a pull request to merge.", then runs the theme's vendor/bin/taw update with the site's PHP and Local's Composer. A screen shows each step as it runs, and at the end o opens the pull request and r the report.

• A theme on an older taw/core gets one step too: taw-fleet first installs the newest taw/core in vendor/, puts composer.lock back, and lets the new update do the rest.
• When an update stops, taw-fleet offers Fix with Claude, which starts Claude Code with the report as its prompt (it asks before pushing and never merges), or Do it myself, which opens the report in your editor.
• U (or taw-fleet update --all) updates every client theme that needs it, one after another, each with its own pull request. A theme that stops doesn't stop the others.

Details: Dashboard and keys.

What the framework keeps for you

Since taw/core 1.91, the parts of a theme that only the framework changes ship with taw/core and update with it. The theme keeps short files of its own, so an update never has to merge your edits:

The migrations convert older themes. A file you edited is left as it is, with a "For you" step that says how to move your changes. To replace an edited agent doc anyway, run taw docs:sync --apply --force, then put your notes back under "This site".

Theme CI

A theme's CI is a short stub that calls taw/core's shared workflow, so the checks update with taw/core:

jobs:
  ci:
    uses: Relmaur/taw-core/.github/workflows/theme-ci.yml@v1
    with: { smoke: true, build: false }

It runs only the checks the theme has: PHP lint, the block getData() check, PHPStan and tests, schema:validate, the front-end check or build, and an optional WordPress smoke test. One check always runs (taw/core 1.93): it fails when the repository holds a database dump, a content snapshot (.sync/) or a credentials file (remote.env, .env, wp-config.php, a private key). On a pull request it checks every commit, so a dump added and then removed again still fails. Remove it from the branch's history and change any password it held. Since taw/core 1.94 the same check also runs before each commit on your Mac: the update installs a git pre-commit hook that refuses the commit, so the file never leaves your machine. git commit --no-verify skips the hook, but CI still checks the push. The header of each workflow lists the same steps as commands, so you can run them by hand.