Channels


#1

Channel basics

In the snap world channels define which releases from a particular snap the system will be observing and attempting to install new revisions of.

For example, this command installs a new revision from latest/stable, or stable short:

$ sudo snap install vlc

While this one will pick up the latest beta snap, if there is one available, or otherwise something more stable than that:

$ sudo snap install --channel=beta vlc

Again, beta and latest/beta refer to the same channel.

Once a snap is installed the system will continued observing the channel used during installation, and during refresh attempts it will pick up new revisions that are made available to that channel, directly or indirectly (see details below).

After installation the channel for a particular snap may be changed during a refresh:

$ sudo snap refresh --channel=candidate vlc

And it may also be changed via the switch command with no immediate interaction with the store:

$ sudo snap switch --channel=offline

The snap info command will display the channel being used by the given snap under the tracking field.

Channel tracks

The channel name structured as three parts separated by slashes:

  • <track>/<risk>/<branch>

The track defines the series of versions that may be obtained for snaps in the given channel. Different projects use different conventions for its tracks according to its internal practices. For example, certain projects use tracks named after the minor version of the project (3.2) implying only micro releases of that specific version will be found under that track (3.2.5). Other projects hold tracks for its LTS (long-term support) releases, so version numbers may change even across majors (3.2 → 4.1). The default track is latest and is implied when the field is missing.

At this time and to encourage consistency and sanity in the ecosystem tracks must be explicitly requested via the #store forum category. Also, “guardrail” regular expressions are applied to the versions being released in specific channels to ensure that mistakes are not made and reasonable user expectations are not broken. For example, only 3.2.* versions are accepted into a 3.2 track.

Channel risks

The risk part must necessarily be one of:

  • stable
  • candidate
  • beta
  • edge

It conveys the stability level of snaps in the given channel. These terms may not match exactly the internal conventions used by the project (some will say alpha instead of edge) but they are close enough to the most accepted conventions, and allow users to express their risk interest across all snaps in a consistent way.

The stable and candidate channels are said to be of stable grade, while beta and edge are said to be of devel grade, and that small distinction is in place to help prevent process mistakes that could result in unintended versions hitting production users and causing major harm.

Closing channels

Closing a channel is a convenient way for the snap publisher to tell the world that there’s nothing available with that exact specification right now, but closing a channel does not change the choice of systems following it. Instead, when the channel of a specific risk level is closed the snap store will internally fallback to the next channel of the same track that offers a more conservative choice than the risk specified.

For example, if a client is following a beta channel but that channel is closed, the store will offer the current snap in the candidate channel if one is available, or the one from stable otherwise. In that scenario the client continues following the beta channel, though, and once the channel is reopened the client will refresh into the snap released there.

If it sounds a bit confusing, the important thing to remember is that this logic means the behavior is correct and what you would expect: if you ask for a beta, you get a beta, unless something even more recent and more stable than that beta is made available, in which case there’s no reason to stay behind.

Channel branches

The branch part is optional and missing by default. Its purpose is to allow the creation of short-lived sequences of snaps for experimentation or other temporary purposes. Branch names must convey the reason for their existence, and although accessible to anyone that would have access to other channels of the given snap, these names are not exposed in the snap information by default.

Branches also have an enforced expiration time at which point the branch will be closed. Similar to the behavior described above when considering risk levels, once a branch is closed the store will offer clients the snap in the most appropriate channel. For example, a stable/fix-bug-42 channel will fallback to stable once the fix-bug-42 branch is closed.


How to create channel branches
Snapd channel information
Announcing channel branches
Parsing snap info
Disabling automatic refresh for snap from store
How to upgrade snaps across tracks
Disabling automatic refresh for snap from store
Track request for etcd 3.2
Docker snap tracks request
Track request for etcd 3.2
Documentation outline
Getting started
What does it mean to track a channel that doesn't exist?
Disabling automatic refresh for snap from store
Auto-aliasing and duplicate aliases
Using branches on non-stable channels
Syntax for build-snaps
#2

9 posts were split to a new topic: How to create channel branches


#11

3 posts were split to a new topic: How to upgrade snaps across tracks


How to upgrade snaps across tracks
#14

5 posts were split to a new topic: Using branches on non-stable channels


#15

How do we handle the ambiguity of two part names?

e.g. is stable/beta:

  1. track=stable, risk=beta, branch=(none)
  2. track=latest, risk=stable, branch=beta

Does this mean that tracks and branches can’t use the risk names?


#16

There are four risk names, and those track names are reserved to avoid the ambiguity. The corresponding branch names don’t need to be reserved, since a naked branch name is illegal.

To parse a channel string into its three components:

One segment: If the first segment is a risk, the form is $RISK and it expands to latest/$RISK. If it is not a risk, the form is $TRACK and it expands to $TRACK/stable.
Two segments: If the first segment is a risk, the form is $RISK/$BRANCH and it expands to latest/$RISK/$BRANCH. If it is not a risk, the second segment must be a risk, and the form is $TRACK/$RISK.
Three segments: The second segment must be a risk and the form is $TRACK/$RISK/$BRANCH.


#17

I should point out, though, that existing clients mostly just treat channels as opaque strings, and that’s probably a good idea in general. It’s possible that channel structure may change in future, and clients in the wild should at least not crash if they see something they don’t understand.


#18

Improved the text existing text a bit, separated it into sections to make it easier to digest, and also added a new basics section at the top describing the most interesting operations.


#19

I’d like to include information on the length limit of things, here. In particular, what’s the length limit of tracks, and what’s the length limit of branches?

I think branches have a length limit of 128. Is the expectation that they’re never ever shown to the user in a listing?


#20

@chipaca I’m don’t know what’s the limit of either of those. We probably didn’t bother because there’s a review process in place to make sure that they are sensible names at all, length and otherwise.

As for the expectation, yes, branches were purposefully designed not to be listed anywhere. They are meant for things such as temporary hotfixes and similar cases that will be thrown out shortly, and that shouldn’t be recommended other than by word of mouth.

Anything long-lived and that listing would be expected should really be a track instead.