Updating the engine

git pull
./blog.sh rebuild

rebuild, not ruby build/build_blog.rb: the build script renders one language per run, and rebuild runs it for every language the site publishes and then deploys. On a site in two languages the bare script followed by a deploy leaves the second language's pages as the previous version built them -- and uploads them that way.

main is the release branch: a clone on it gets each release by git pull. A clone that was put on a release tag (git checkout v1.8) is on no branch, and git pull refuses with "You are not currently on a branch"; move it to the next release by name instead:

git fetch --tags && git checkout v1.9

The first build after an upgrade may be a full one -- the engine's own fingerprint changed, so the record of the last build is thrown away -- and it writes .build_cache.json in the installation directory, which is per-machine, gitignored and always safe to delete. Deploy the assets with it: a page that cannot fetch assets/js/share.js logs a 404 on every load.

Going back a version is git checkout <tag> and a rebuild, and what the newer version was given to work with is looked at first, because the older one does not treat all of it alike. From 1.10 back to 1.9: take series: and language_name: out of every config/site.<lang>.yml, or the build stops on them and nothing is deployed -- a language's file is where 1.9 refuses a key it does not know. on_this_day under widgets: it does not refuse: the build says one line about it, doctor marks it, and the card is simply not drawn. And site.author_name, banner.show_image, layout.lead_card and publishing.allow_partial it passes over without a word, so the pages go back to what 1.9 makes without them -- the banner's picture is shown again, for one, and a site of several languages is asked about every post again. Old addresses a translation was given (translations.<lang>.former_slugs) stop being answered -- 1.9 does not read them, and a translation saved there is written without the list, so those addresses are not in the post on the way forward again either. What 1.10 left in the installation folder for itself (.on-this-day.*.json, .search_index.json, .last-sidebar-run) is safe to delete. The posts, the media and the rest of the configuration are otherwise untouched in both directions.

Per-deployment files (content.nosync/, media.nosync/, config/site.yml, config/site.<lang>.yml, env.sh, incoming/, trash/, drafts/, manifests) are gitignored and survive any pull untouched. The one thing to watch: if you've edited engine files in place (templates, CSS), a pull can conflict -- keep such customizations as commits on your own branch so git merges them for you. config/palettes.yml is one of those: it ships with the engine, so a palette of your own added to it is an edit in place. The wizards also leave a .bak of whatever they rewrote -- config/site.yml.bak, env.sh.bak -- which is how you take a wizard run back by hand. Nothing deletes them, and the env.sh one holds your previous tokens at the same 0600, so remove it once you have rotated a token.