How do we handle the ambiguity of two part names?
e.g. is stable/beta:
- track=
stable, risk=beta, branch=(none) - 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 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.
There is some discussion about all snaps having a latest track by default and that if not specified otherwise, that is the default (sorry for the confusing phrasing).
Could some documentation be added about the “configurable default track” functionality?
If a snap already has some tracks created, one of them can be designated as the “default track” instead of latest. This is the track that the snap will be installed from, if a track is not specified explicitly.
Example, assuming snap superfoo has a 2.0 track in addition to latest:
snapcraft set-default-track superfoo 2.0
Now, an “implicit track” install will install from 2.0 instead of latest:
snap install superfoo
But note that the default track does NOT remove latest; latest is never a pointer to another track. So this will still install from latest:
snap install superfoo --channel=latest
Thanks for this. We had something vague like Without the snap developer specifying otherwise, but I’ve added a little to this page to hopefully make it clearer.
I’ve also added a section to our Publish to a branch page on setting a track as default: Publish to a branch
I believe something went wrong in the middle of the sentence.
Fixed, thanks for flagging this!