Upgrading

Releases are git tags, and upgrading means merging one into your own repository. One command does the whole thing, asks you about the handful of files it cannot decide alone, and tells you how to undo it.

Before you start

Three rules, all of which the command enforces so you cannot forget them:

1. Upgrade on your own machine, then deploy the result. Never upgrade in place on a server. The command refuses to run outside development, because an upgrade that goes wrong on a server is an outage, while one that goes wrong on your laptop is an afternoon.
2. Commit everything first. A clean tree is what lets you undo anything the upgrade does.
3. Read the release notes. Updates in the control panel lists what each release changed, and anything needing action from you carries an Upgrade note.

Doing it

bin/nibble-upgrade          # the newest release
bin/nibble-upgrade 0.4.0    # a particular one

In order, it:

1. Takes a snapshot of your database and prints the exact command that puts it back. Copy that line somewhere; it is your way home.
2. Checks the release can upgrade from your version, and that your machine meets its Ruby and Node floors. It stops before touching anything if not.
3. Merges the release.
4. Installs dependencies, because a release usually moves some.
5. Runs bin/rails nibble:upgrade for database migrations and content migrations.

Then run your site, click around, and deploy when you are happy.

What it asks you

Two kinds of file cannot be merged for you, and it stops on each:

Files you own that Nibble generated. config/nibble.yml, .env, the deploy files. If the template has moved on, it re-renders yours from the answers your install recorded, shows you a diff, and asks whether to take it. Your load_defaults is always kept, so new behaviour stays off until you ask for it — see Settings.

Files you ejected. For each one it shows what changed in Nibble’s copy since you took yours, so you can decide what to carry across. Nothing is applied behind your back.

Undoing it

There is a boundary, and the command tells you as it crosses:

• Before the migrations run — git merge --abort undoes everything.
• After the migrations run — restore the snapshot it printed at the start. A release whose migrations cannot be undone says so plainly in its notes, so you know the snapshot is the only way back.

When git stops on a conflict

An upgrade should only stop where you changed something of Nibble’s. You can find out which files those are before you begin:

bin/rails nibble:check

It reports anything of Nibble’s you have edited in place, which is exactly the list a merge will stop on. If you meant to change one of those files, eject it instead — an ejected file is yours on purpose and the upgrade tells you when the original moves, rather than fighting you.

package-lock.json is the one file you both write, because your own theme and packages have to be in it. The upgrade rebuilds it rather than installing from it, so if git stops there: take either side, run npm install, and commit the result.

Hearing about releases

Updates in the control panel lists releases newer than yours, what each one changed, and the command that takes it. It checks once a day in the background, and checking means reading one published file — nothing about your site is sent anywhere. A switch on that screen stops even that.

Upgrading a site that is behind

If several releases have come out since yours, take them one at a time, running the site after each. It is slower, and it is the difference between knowing which release caused a surprise and guessing.