How to Switch Release Branch

2022-09-28 08:35:39.743Z2022-12-02 07:14:08.155Z

on-premise

If you're self hosted: Talkyard has different release branches: (inspired by Kubernetes)

tyse-v0-regular which gets new features and bug fixes regularly.
Branches with names like: tyse-v0.YYYY.NN (e.g. tyse-v0.2022.14). These are medium-term-stable branches; they get security fixes only.

You can switch from any of the tyse-v0.YYYY.NN to the tyse-v0-regular branch at any time. But you can switch to a tyse-v0.YYYY.NN branch only if it's the same version or newer — that is, if the version number in the branch name (i.e. v0.YYYY.NN for example v0.2022.14) is the same or higher than the version you're using (see step 2 below).

If you want to use medium term stable branches only, then, once in a while you need to switch to more recent such branches, because each such branch is maintained only for a bit more than half a year. For example, switching from tyse-v0.2022.10 to tyse-v0.2022.14 (it's generally fine to jump many versions, e.g. from v0.2022.10 to ...14 in this example).

Here follows detailed instructions about how to switch release branch:

Switching to the Regular branch

If you're using a tyse-v0.YYYY.NN branch and want to go back to using the regular release branch, do steps 1, 3 and 4 below (in the next section), but in step 3, type tyse-v0-regular instead, as the branch you want to use: RELEASE_CHANNEL=tyse-v0-regular. And then do step 4, i.e. run the upgrade-if-needed.sh script.

Switching to a Medium Term Stable branch

If you're using tyse-v0-regular (or an old tyse-v0.YYYY.NN branch), here's how to switch to a tyse-v0.YYYY.NN branch:

1. Log in to the Talkyard server

sudo -i
cd /opt/talkyard

2. Check the version number

Verify that the tyse-v0.YYYY.NN branch you'd like to use, is not old — find out what version you're using now:

grep VERSION_TAG .env

For example:

bash# grep VERSION_TAG .env  
VERSION_TAG=v0.2022.13-6d49a6e33

Here, the version currently in use is v0.2022.13 (and -6d49a6e33 is a Git revision which you can ignore). You cannot change to a release branch with a lower version, for example, don't try to change to tyse-v0.2022.12 — because the more recent version you're using (v0.2022.13 in this example) might have made changes to the database that older versions of Talkyard don't understand.

3. Edit config file

Edit the .env file mentioned just above: vi .env, and set the RELEASE_CHANNEL=... line to the branch you want to use, e.g.:

RELEASE_CHANNEL=tyse-v0.2022.14

if you want to use the tyse-v0.2022.14 medium term stable branch. (The config value RELEASE_CHANNEL should be called RELEASE_BRANCH instead, because it's actually a Git branch, not the same as a "channel" in Kubernetes terminology — this'll get fixed in the future.)

4. Download and restart

Lastly, do this, to download and start the latest version of Talkyard in the new release branch:

./scripts/upgrade-if-needed.sh | tee -a talkyard-maint.log

This can take long, if the new Talkyard version changes the database structure and you have lots of data. — Just before making any such changes, Talkyard takes an extra backup. So, if anything goes wrong, you can, worst case, restore the backup. See How to Rollback a Database Upgrade.

Done

After the steps above, you will be using the new release branch (tyse-v0.2022.14 in this example), and Talkyard will fetch security upgrades from that branch, e.g. automatically upgrade itself to tyse-v0.2022.14.1, tyse-v0.2022.14.2, tyse-v0.2022.14.3.

If you're using medium term stable branches, then, but not yet implemented:

When there's just 3 months left, until your stable branch becomes unmaintained, your Talkyard server will email you about this and show notices for admins when they visit the Talkyard forum, letting you know that it's time to switch to a newer medium-term-stable branch (so you continue getting new features and security fixes).
By default Talkyard will upgrade automatically to a more recent branch, once your current branch is about to become unmaintained (if you didn't upgrade yourself).