Upgrade Arc CMS

Your site or app is a copy of the Arc CMS repository, so an upgrade is a git merge of the newer Arc CMS into it. When your copy has not edited any core file, the merge is clean.

Once: add Arc CMS as the upstream remote

git remote add upstream https://github.com/quadralyst/arccms.git

git fetch upstream

A copy made as on Install has it already. npm run check:core needs this remote: without it, it checks nothing and fails, so it never passes by accident.

Every upgrade

1. Check that no core file changed, with your work committed:

   npm run check:core

   It must report that no Arc CMS core file changed. If it lists core files, move those changes into the custom space first (Keep core untouched), or the merge will conflict with them. A site's own home page, templates, static pages and partials belong in src/custom/site/. A copy made before that folder existed has them in public/, listed as core: merge anyway, then move them with npm run arc:own-site (Move your site into src/custom/site).

2. Read what changed in CHANGELOG.md of the new version, and look for any step it asks of an app.

3. Merge the new version:

   git fetch upstream

   git merge upstream/main

   A copy that follows the dev branch merges upstream/dev instead; npm run check:core names the branch your copy follows.

4. Install the dependencies of the app and of the functions:

   npm install

   npm install --prefix functions

5. Run the tests:

   npm run test -- --run

   If your app has rules of its own, or the new version changed the rules, run the rules tests too:

   npm run test:rules

6. Redeploy everything. A new version can add or change functions, rules, indexes and the website, so pick "Everything" in the guided deploy:

   npm run deploy

   A deploy of all the functions also deletes those the new version no longer has. It lists them and asks first. See Deploy.

What a clean upgrade looks like

• The merge has no conflicts, and none of your custom files changed: Arc CMS ships them once, empty, and never changes them again.
• npm run check:core still reports no core file changed. Your custom and install files are counted, not flagged.
• The tests pass, and the deploy ends with Done:.

When the merge conflicts

• In a core file: your copy edited it. Take the new version's file, then make your change in the custom space. If the custom space cannot do it, the change belongs in Arc CMS as a general feature: see Core and custom.
• In public/: your copy edited the website in Arc CMS's files. Run npm run arc:own-site, then npm run arc:own-site -- --write: it moves your edits into src/custom/site/ and settles these conflicts (Move your site into src/custom/site).
• In src/environments/environment.ts, environment.prod.ts or arc-install.ts: your copy filled them in, and the update that made Arc CMS ship them with no project emptied them. Keep your own version of each (git checkout --ours <file>). Arc CMS never changes their values again; when it adds a key, CHANGELOG.md names it: add only that key.
• In package.json or functions/package.json: your app added a dependency. Keep both sides' entries, then run the two installs above to rewrite the lock files.

Functions deployed without the arccms- prefix

Every Arc CMS function deploys as arccms- followed by its name. A project that still has Arc CMS functions under their plain names moves over once with npm run arc:upgrade. It deletes every deployed function that has an Arc CMS function name and is not in the arccms codebase, then deploys the arccms functions. See what it would delete first, and check that the list holds no function of another app with the same name:

npm run arc:upgrade -- --project=default --dry-run

Then run it without --dry-run at a quiet time: for a few minutes, database events are not handled. Straight afterwards:

1. Deploy the website. The previous website calls the old function names, which no longer exist.

2. Register the webhooks again at their new addresses, arccms-dodoWebhook and arccms-handleEmailWebhook. Until then, the payment and email providers' events are lost.

3. Republish the static pages, so their search box calls arccms-search: npm run seed:dev, or npm run seed:prod for the production alias.

4. Send one test email and make one test checkout.