Updates

How an update reaches customers

1. You submit the new versionPush new commits to your branch and submit an update from the developer portal, with what's new and the version number. Submit freezes the branch's latest commit. See Submitting.
2. The code checks runThe same checks as your first version, against today's template. An update on an older template version is refused (template_outdated): upgrade it with the template's docs/agent/upgrade.md first.
3. It is reviewedThe same levels and checklist. A new test site is built from the update, and the code review reads every change since the live version. Your live version stays live meanwhile. See Review.
4. It is publishedApproval publishes it in the store straight away. The reviewer confirms the version number, or sets another one.
5. Your public preview moves to itThe store's preview is deployed again with the new version, on the same site. It keeps its data: your new migrations run on its database and nothing is wiped. The version before keeps serving until the new one is live.
6. Customers see Update availableEvery customer who installed your listing sees it on their site's Apps tab, with your notes on what's new. Nothing changes on their site until they press Update.
7. Update merges your version into their copyFile by file, in their editor, by the rules below. Nothing they changed is written over.
8. Their AI settles what clashesWhere you both changed the same lines, their version stays and yours waits in .platform/apps/<slug>/incoming/. Their own AI merges it in the editor, and runs npm install when package.json changed.
9. They try it on stagingChanges land on staging first: their staging site and staging database, with your migrations run on it. Their live site is untouched.
10. Publish runs your migrations on liveWhen they publish, the platform runs your new migrations on their live database before the new code goes live. If one fails, the site keeps serving the version before.
11. They can undo itUndo update takes their copy back to the version before, merged the same way, their changes kept. Migrations are not undone: the database keeps your new tables and columns. That is why every migration must be safe for the version before.

How Update merges, file by file

For every file, Update compares three copies: the version the customer's copy was last given, their copy as it is now, and your new version.

Update merges up to 300 files in one go. Past that, the rest go to incoming for their AI, one more reason to keep updates small.

The platform keeps a record in each copy of the version it was last given, so the next update knows what changed, even after many updates.

Before you submit an update

• Your new migrations work on a database from the previous version, with data in it. Not only on an empty one: customers' databases are full. And the previous version still runs on the new schema.
• Migrations only add: new tables, new nullable columns, new indexes. You never edit, rename or delete a migration that is in a released version. See Database.
• It is small and focused. A big rewrite clashes with what customers changed. Files are moved or renamed only for a reason: a moved file is a delete and an add for every customer.
• What's new is written for customers, with what they might lose, and the notes for their AI: what changed, and how to carry their changes over. See Every update says what changed.
• The version number is higher than the live version (1.2 → 1.3).
• The template is on its current version and src/platform/ is untouched. After an upgrade, download the template kit again for its new store-check.mjs.
• Your sample data still loads on the new schema: prisma/seed.sql runs twice in a row without errors.
• The store check passes: node store-check.mjs on the commit you will submit.

Test on the previous version's database

On a throwaway Postgres of your own (never one you care about):

# 1. A database from the version customers have now, with data in it
git checkout v1.2.0              # your last released commit
npx prisma migrate deploy
psql "$DATABASE_URL" -f prisma/seed.sql
npm run dev                      # sign up, add a few rows the way a customer would

# 2. The update, on that same database
git checkout main
npx prisma migrate deploy        # only your new migrations run
npm run build && npm run dev     # the new code on the old data

# 3. The version before, on the new schema (an Undo puts it back)
git checkout v1.2.0 && npm run dev