Immich now ships release candidates. Here is how they work

For most of its life, Immich had one kind of release. A new version appeared on GitHub, people pulled it, and the bug reports came in over the following days. Then a patch release fixed the worst of them. That works. It also means the first wave of users does the testing on their real libraries, without having signed up for it.

Since v3, that has changed. Before a big release goes out, Immich now publishes one or more release candidates first. v3.0 had four of them in June, before the stable version landed on July 2. v3.2 went through three. v3.3 had three in under a week, between September 29 and October 2.

What a release candidate is

A release candidate, or RC, is a version the developers believe is ready, but want more eyes on before they call it final. The features are done. No new ones get added. What happens during the RC phase is testing and bug fixing, nothing else.

You can recognize one by the version number. v3.3.0-rc.0 is the first candidate for v3.3.0, v3.3.0-rc.1 the second, and so on. This follows semantic versioning, where anything after the hyphen marks a pre-release. A pre-release always counts as older than the version it leads up to, so v3.3.0-rc.2 sorts before v3.3.0. When nobody finds anything serious in the last candidate, the same code goes out as the stable release.

Darkroom photographers will know the pattern. You do not expose your best sheet of paper first. You make a test strip, check it, adjust, and only then make the real print. An RC is the test strip.

How to test one, and what can go wrong

For the server, you point the IMMICH_VERSION variable in your .env file at the candidate, for example v3.3.0-rc.2, and run docker compose pull && docker compose up -d. There is also a rolling v3-rc tag that always points to the newest candidate. For the mobile apps, Android users can install the APK from the release notes or join the beta on Google Play. iOS users join through TestFlight. The links are in each release on GitHub, and that is also where bugs should be reported.

Now the tradeoff, because there is one. Every RC comes with the same warning: it is not a stable release, and it may contain bugs or breaking changes. That warning is not a formality. A new version usually runs database migrations when it starts. Those migrations move forward only. Immich does not support downgrading, so if an RC breaks something, you cannot switch back to the previous version and carry on. You restore from a backup, or you wait for the next candidate.

So the rule is boring, and it is the right one. Make a fresh backup of both the database and your upload folder before you try an RC. Better still, test on a second instance with a copy of your data, not on the library your family uses every day. If you do not have a backup you have recently restored from, our post on the 3-2-1 backup rule is a good place to start.

If you have a spare machine and a bit of time, testing RCs is one of the most useful things you can do for an open-source project. Writing code is not the only way to contribute. A clear bug report against an RC fixes a problem for thousands of people before they ever see it.

What this means for PixelUnion users

Nothing changes in how you use PixelUnion. We do not run release candidates on your instance. We wait for the stable release and then roll it out in stages, the way we did with v3. You get the new features once they have been through the RC phase and our own checks.

We do follow the RCs closely. They tell us early what is coming, so we can prepare and tell you about it. And because more people test before the final release, the stable versions that reach you should contain fewer surprises. That is good for the self-hosting community, and it is good for us.

We would like to do more than watch. In the future, we want to run a beta version of PixelUnion. If you tell us you want to take part, your instance would get new Immich versions before the stable release, so you can help test them and give feedback quickly. That feedback goes back to the Immich project, which is the point. Whether and when this feature will land is not known yet. When we know more, you will read it here first.

If you would rather leave the testing, backups, and upgrades to someone else, that is what we are here for.

Start free with PixelUnion →

Cover photo by Francisco Gonzalez on Unsplash.