Upgrading taw/core on an existing site
How to bring a live TAW site's taw/core up to date, what changes by default between versions, and what to check afterwards.
The short version
Every 1.x release of taw/core keeps existing theme code working and never changes stored data. A few
releases changed a default, though, so the upgrade comes with a checklist organized by the version the
site is coming from:
- In any theme:
vendor/taw/core/UPGRADING.md(the copy that came with the new version); - Online: UPGRADING.md on GitHub.
It's written so an AI agent working on the site can follow it step by step.
Steps
Check the installed version
composer show taw/core | grep versions
Sync the theme scaffold (recommended)
Ask your agent to "update the theme". The update-theme skill runs php bin/taw sync, which updates functions.php, bin/, CI and the framework skills, and never touches Blocks/, inc/ or templates. Its composer.json and package.json suggestions include optional starter features (Reactiph, the chatbot's packages) that an existing site can skip.
Update the package
composer update taw/core
Work through UPGRADING.md
Read every section newer than the version you came from, and run the checks it marks. The update-theme skill does this for you when you let it update taw/core.
Verify and commit
Run the tests, load the front page and a page with a form (the visual-check skill), and open a few wp-admin screens with metaboxes and options pages. Then commit composer.lock.
A real form submission can email a client or create a post. To check validation, send a form with a required field left empty: nothing is saved or sent. Under Local, start the site first; php bin/taw commands need its database.
What changed by default since v1.22
These are the changes a site gets without asking. Everything else since v1.22 is opt-in.
| Since | Change | What to check |
|---|---|---|
| v1.24 | Anonymous requests can't list users over REST | Whether anything fetches /wp/v2/users without logging in |
| v1.25 | TAW metabox fields appear in the REST API; Tools → TAW Data appears | Whether a field holds something that shouldn't be public on published posts |
| v1.30 | The RAG chatbot needs RagSettings::enable() | Only if the site uses the chatbot |
| v1.39.1 | Forms reject an empty required email | Submit each form once |
| v1.41 | Metaboxes with tabs show tabs | Open a post whose block uses metabox tabs |
| v1.56 | taw-core has its own translations | Nothing: the theme's own translations still win |
| v1.59.2 | taw-core's Spanish loads in classic themes; tabs work by keyboard | On a Spanish site, a required-field message is in Spanish |
To roll back, reinstall the previous version: composer update taw/core:<previous version>, or restore
composer.lock. Nothing needs migrating either way.
New things you may want
Since v1.22, taw/core also gained features that stay off until a site uses them:
- Fields: the data panel, term and user fieldsets, and the
linkfield type. - Reading: typed reads with
Taw::post(). - Content and REST: content snapshots, and options pages over REST.
- Lockdown: editing policies.
- Integrations: Lucide icons and media folders.