Progressive releases

doc
1

When a snap has been published and has an established user base, tracks and channels help balance the risk of a release containing unexpected issues against user expectations for new features. This is covered in Release management.

Progressive releases offer an additional strategy to help mitigate the risk of unexpected issues affecting users. They help by making a release available only to a specific percentage of a snap’s user base. This percentage can be initially small, perhaps 10% or 20%, and increases as confidence in a release grows.

To deploy a progressive releases, add an additional argument to the snapcraft release command, which itself operates on an uploaded revision of a snap:

snapcraft release <snap-name> <revision> <channel> --progressive <percent>

The percentage value defines the proportion of devices a progressive release will be deployed to.

:information_source: Snapcraft 7.x or newer is required to use progressive releases.

Creating a progressive release

First, ensure there is a revision of the target snap available on the Snap Store. See Releasing your app for details on building and uploading locally, or Remote build to create a revision on remote servers using Launchpad.

The snapcraft revisions command can be used to see which revisions have been uploaded and available:

$ snapcraft revisions <snap-name>
Rev. Uploaded              Arches       Version  Channels
357  2020-11-03T11:29:13Z  amd64,armhf  4.1255   -
356  2020-11-03T08:27:23Z  amd64,armhf  4.1249   latest/candidate*
355  2020-10-26T13:07:16Z  amd64,armhf  4.1246   latest/stable

In the above example output, revision 357 of the snap has been uploaded but has not been released, revision 356 is on the candidate channel and 355 is on the stable channel. To release revision 356 to the stable channel of the default (latest) track, issue the following command:

$ snapcraft release <snap-name> 356 stable

To release revision 356 to the stable channel of the default (latest) track as a progressive release, with 30% deployment, issue the following command:

$ snapcraft release <snap-name> 356 stable --progressive 30

The command above will release the snap to 30% of devices, chosen pseudo-randomly based in part on a hash of their device ID, with the snap installed from its stable channel. This means that roughly every third device will get the update when it next requests a refresh.

Monitoring a release

The snapcraft status command can be used to monitor the progress of a progressive release:

$ snapcraft status <snap-name>
Track     Arch    Channel    Version    Revision    Progress
latest    amd64   stable     4.1246     341         73 → 70%
                             4.1249     355         21 → 30%
                  candidate  ↑          ↑           -
                  beta       -          -           -
                  edge       -          -           -

The above output shows that the progressive release of the stable channel has been set to target 30% of devices, with 70% remaining on revision 341 and 30% upgrading to revision 355. The Progress column shows the current deployment progress towards those percentages.

If an issue is discovered with a revision deployed as a progressive release, a new revision can be built and uploaded to address the issue without further deployment. When the new revision is itself published as a progressive release to the same channel, the devices that received the earlier release will be prioritised.

Finalising a progressive release

After the assigned percentage of devices have received the release, there are two ways the snap publisher can proceed:

  1. Re-release the same revision again with a higher percentage and continue to do so manually, pausing to solicit user reports of any issues, until 100% is reached:

    snapcraft release <snap-name> 356 stable --progressive 40

    When a progressive release reaches 100% (with --progressive 100), a non-progressive release is still required. This is because certain devices may be configured to ignore progressive releases entirely.

  2. Release the same revision non-progressively. This makes the revision available to 100% of devices with the snap installed:

    snapcraft release <snap-name> 356 stable

After a non-progressive release, a snap will revert to standard Release management processes and procedures.

1 Like
2

What credentials do you need to run these commands? I’m logged in via my credentials file, and I am not allowed to even run “snapcraft revisions” to check the revisions for a snap.

3

Hello! I just tested this with fresh snapcraft 7.0.11 install (rev 7923) and freshly exported credentials and all of the above is working for me.

I did initially have a problem because I had old credentials in a snapcraft config file and was getting a Cannot parse config: File contains no section headers error, but after deleting the config file everything worked. (~/.config/snapcraft/snapcraft.cfg).

I’ve updated the Snapcraft authentication options doc in case other people experience the same problem.

4

I think they are no longer experimental on Snapcraft 7.x. Can this maybe be changed to just mention that Snapcraft 7.x or newer is required to use progressive releases? At this point I don’t think there’s much of a reason for people to still be using Snapcraft 6.x anyway.

5

Thank you for the hint - I’ve updated the doc!

6

Hi, the above still shows in the document and is confusing when taken together with the newly-added:

I guess my point was that progressive releases are no longer considered experimental and don’t need --experimental-progressive-releases if using snapcraft 7.x or newer, which we are saying is required.

Thanks and sorry for not being clear at the beginning :slight_smile:

  • Daniel
7

It’s my fault. I went through this too quickly and didn’t remove the experimental flag. Thanks for letting me know!

8

Thanks! One more thing - this documentation page is excellent and is rather tutorial-ish, which is good - however it feels like it leaves the example “halfway through” - there’s no indication of what to do once the assigned percentage of devices have all received the release.

There are two ways a publisher can proceed:

  • Re-release the same revision again with a higher percentage:

    $ snapcraft release <snap-name> 356 stable --progressive 40

    and continue doing so manually, maybe pausing to listen for user reports of any trouble, until 100% is reached.

  • Release the same revision non-progressively, which makes it available to 100% of devices:

$ snapcraft release <snap-name> 356 stable

Interestingly, because $REASONS, even if one has released progressively to 100%, say:

$ snapcraft release <snap-name> 356 stable --progressive 100

it’s still required to release non-progressively the same revision in order to “complete” the release and make it available to all devices, because there are a few rules by which a device might entirely ignore a progressive release and stay on the previous version if this is not done.

Would it be possible to add these steps to the example?

Also, the reason I’m pestering about this documentation page is that we want to announce progressive releases’ wide availability in a forum or blog post; the one thing we needed was a great documentation page (which this one is - thanks!), I just wanted to ensure all these small quirks, knobs and levers are properly documented as well.

Thanks again!

  • Daniel
9

Thanks for the feedback and for writing the missing pieces. I’ve updated the doc to include those. Good luck with the announcement!