Channels

Channels are an important snap concept. They define which release of a snap is installed and tracked for updates.

A channel consists of, and is subdivided by, tracks, risk-levels and branches:

  • Tracks enable snap developers to publish multiple supported releases of their application under the same snap name.
  • Risk-levels represent a progressive potential trade-off between stability and new features.
  • Branches are optional and hold temporary releases intended to help with bug-fixing.

The complete channel name can be structured as three distinct parts separated by slashes:

<track>/<risk>/<branch>

The tracking value for an installed snap, as shown in the output from the snap list command, shows which channel is installed and is being followed for that snap.

Tracks

All snaps have a default track. Without the snap developer specifying otherwise, the default track is called latest. Similarly, when no track is specified, a snap will implicitly install from the latest track. The track can also be specified explicitly:

snap install vlc --channel=latest/edge

Developers can optionally choose whether to supplement the default latest track with additional tracks. The developer is also free to designate one of these as the default track to be installed when no further preference is given.

Microsoft’s Skype snap is a good example of how tracks can be used. It contains two tracks: the default latest track for the majority of users, and an insider track for Microsoft’s QA team and users interested in testing the latest Skype developments ahead of a stable release.

Equally, a track could also be used to track minor updates (2.0.1, 2.0.2), major updates (2.1, 2.2), or releases held for long-term support (3.2, 4.1).

Tracks are listed in the channels section of the output from the snap info command:

$ snap info skype
[...]
channels:                                  
  stable:            8.28.0.41  (51) 148MB classic
  candidate:         ↑                     
  beta:              ↑                     
  edge:              ↑                     
  insider/stable:    8.30.76.41 (53) 151MB classic
  insider/candidate: ↑                     
  insider/beta:      ↑                     
  insider/edge:      ↑  
[...]

In the above output, the Skype snap includes the custom insider track. You can also see which tracks a snap supports by clicking Other versions from its online Store entry.

To install Skype from its insider track, for example, use the following command:

snap install skype --channel=insider/stable

A user who already has Skype installed can switch channel with the snap refresh command:

snap refresh skype --channel=insider/stable

Alternatively if using GNOME Software, select the ‘stable’ channel in the store page for Skype, and select a channel to switch to.

Developers must currently make a request for tracks to be added to their snap via the #store-requests forum category. Releases are verified and checked to ensure that reasonable user expectations are being met. For example, only 3.2.* versions are accepted into a 3.2 track.

Risk-levels

There are four risk-levels: stable, candidate, beta and edge. These represent decreasing levels of stability for a snap, although that decision is ultimately up to the snap’s publisher.

Installing from a less stable risk-level will typically mean that updates for a snap will be more frequent than for a more stable risk-level.

The risk-levels have the following meaning:

  • stable: for the vast majority of users running on production environments.

    Releases at this risk level are as stable as they will ever get, according to the project’s standards. Important software will only reach this stage once it’s ready for production use and may be used in products. There is an implied promise to avoid any changes that would disrupt those usages.

  • candidate: for users who need to test updates prior to stable deployment, or those verifying whether a specific issue has been resolved.

    Candidate releases are considered almost ready for going into stable, but need some additional real world experimentation before they move forward. Software reaching this stage will typically have passed all available QA and review processes, since users following it expect a high stability level. Should almost never break.

  • beta: for users wanting to test the latest features, typically outside of a production environment.

    Beta is the first level towards the stabilisation of what was before a fast moving stream of changes. Specific projects may have slightly different terminology for such releases (alpha, beta, etc) but all of these are welcome on this risk level. These releases will almost certainly have passed some sort of review and QA, but may still have unfinished parts. Breaking changes are still relatively common here.

  • edge: for users wanting to closely track development.

    Edge releases often include a moving stream of changes without QA or review promises and are typically built automatically by a CI process from an arbitrary source code snapshot. Often the CI will only publish after some sort of automatic QA passed, and code reviews remain a good practice, but these are project specific. Assume edge releases may break often.

Snaps are installed from the stable risk-level by default. For example, the following command installs VLC from its stable channel:

sudo snap install vlc

Use the --channel option to select a different risk-level. The following command will install the latest beta snap of VLC:

sudo snap install --channel=beta vlc

If the beta snap is not available, a snap will be installed from the closest channel with a more stable risk-level.

ⓘ For brevity, --stable, --candidate, --beta and --edge can be used instead of --channel=<risk-level>

After installation, the risk-level being tracked can be changed with the use of the switch command option:

sudo snap switch --channel=stable vlc

This option will not automatically refresh the snap to force the installation of a new snap. To switch channels and update the snap with a single command, add the --channel option to the refresh command:

sudo snap refresh --channel=stable vlc

To check which channel a snap is tracking, look for the tracking field in the output from the snap info command:

$ snap info vlc
[...]
snap-id:      RT9mcUhVsRYrDLG8qnvGiy26NKvv6Qkd
tracking:     edge
refresh-date: yesterday at 19:54 BST
[...]

Risk-levels may not match a project’s internal conventions. Some projects may use alpha instead of edge, for instance. However, a project’s own release nomenclature should be close enough to a snap’s risk-levels to allow you to judge the relative stability of the version you’re installing.

Branches

A branch is an optional, fine-grained subdivision of a channel for a published snap that allows for the creation of short-lived sequences of snaps that can be pushed on demand by snap developers to help with fixes or temporary experimentation.

Branch names convey their purpose, such as fix-for-bug123, but the name isn’t exposed in the normal way, such as with the snap info command. Instead, they can only be installed by someone who knows the branch name, and this is usually only shared by the snap developer to test a specific fix or release.

After 30 days with no further updates, a branch will be closed automatically. The replacement snap will then be chosen as it would be with closed channels (see below). For example, beta/fix-for-bug123 will fall back to beta after the fix-for-bug123 branch is closed.

See Publish to a branch for more details on how snap developers can use branches to publish temporary snap releases.

Closing channels

A channel can be closed by a snap publisher when there is no longer a snap that fits a channel’s original purpose or specification.

For example, when a specific risk-level channel is closed, the snap store will select a snap from a more stable risk-level of the same track. If the original channel is re-opened, snaps will once again be selected from the original channel.

This approach is commonly used for beta testing. If a snap is following a beta channel that is then closed, the store will offer the snap from the candidate channel. If the candidate channel is not available, the snap from the stable channel will be selected. If the beta channel re-opens, the snap will once again be selected from that channel.

4 Likes

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

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

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

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?

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.

3 Likes

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.

1 Like

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.

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?

@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.

Just a friendly suggestion, but at the end of this document it mentions how a developer can close a channel (implying a manual operation).

I was thinking it might be a good thing to do a command sample there. As you do throughout the rest of the documentation. :+1:

1 Like

Does snapd apply the same to tracks? Example: I have network-manager installed from 1.10/stable, as latest/stable still has v1.2.22 (reason being stability, semantics aside). The n-m team plans to promote the 1.10 snap to latest eventually; what happens when they close the 1.10 track? Will snapd fall back to latest/stable?

no, track switches need to be explicit/manual (at least for the time being)

Thank you for the clarification. So snapd will keep tracking a previously valid track (e.g. 1.10 in n-m’s case) even if this track is closed? Sorry for being so pedantic about this, just planning ahead what I’ll need to advise users to do once network-manager/1.10 is no longer updated.

Yes, that is what will happen, if the track is closed the devices on it will not get any update, until some other agent (user, mgmt software) switches them if appropriate/applicable.

1 Like

Documentation feedback: I knew branches existed, but spent a while trying to find documentation on how to create and use one. I expected something to be documented in the area “Publishing/Releasing a snap/Uploading a snap” but found nothing. I eventually found this page, but this doesn’t tell me how to upload a branch either. I’m still none the wiser.

If it’s documented, could someone please link to it from here, and maybe also signpost from some of the above pages?

Thanks for this - it’s really good feedback and you’re absolutely right. We have very little on branches. I’ll make it a priority to document this better and, as you say, link it into the Publishing/releasing pages we have.

1 Like

More pedantry:

  • “which tracks a snap support[s]”
  • “A user who already has Skype installed can switch channel with the snap refresh command:-” (superfluous trailing hyphen)
  • “For convenience …” I would write “For brevity …”, but that’s just me.
  • “will fallback to beta” -> “fall back” “fallback” is a noun, “fall back” an action.

Not pedantry - great fixes and suggestions, thank you!

There are a couple references to an “alpha” release level that might be used internally, which is perfectly reasonable but I might reword or add the caveat that “alpha” is purely an internal convention and cannot be added as a fifth risk level. I realize the current explanation might cover that, but I had to take a second look to ensure that the reference to “alpha” was not suggesting someone could use it as an actual risk level in defining a channel.