Snap help development

snapd
,
1

If you run snap help you get a list of commands broken into a nice list of groups:


Commands can be classified as follows:

         Basics: find, info, install, list, remove
        ...more: refresh, revert, switch, disable, enable
        History: changes, tasks, abort, watch
        Daemons: services, start, stop, restart, logs
       Commands: alias, aliases, unalias, prefer
  Configuration: get, set, wait
        Account: login, logout, whoami
    Permissions: connections, interfaces, interface, connect, disconnect
      Snapshots: saved, save, check-snapshot, restore, forget
          Other: version, warnings, okay, ack, known
    Development: run, pack, try, download, prepare-image

For more information about a command, run 'snap help <command>'.
For a short summary of all commands, run 'snap help --all'.

But from there it’s somewhat difficult to drill down on the groups. It would be nice to be able to then use snap help development to get information about development-related commands such as uploading to the store, preparing images, etc. I could see this working for other groups as well such as snap help permissions with a blurb about permissions and common things people would want to do with them.

2 Likes
2

While you make a good point, I must ask: you did check snap help --all, yes?

3

Yes and I think that is a nice list as well. I guess what I wanted more was to help the process of “ok, I have a snap I built. How do I go about the process of getting it onto the store in my personal namespace for testing?” I’m familiar enough with snaps to not need full documentation on everything, but not familiar enough to know how to actually upload a snap. I’m looking for something like:

$ snap help development
Development (developer-oriented features):
These are the typical commands you would use to develop a snap. First you use
`snap template` to create a skeleton snap. After writing the snap, use
`snapcraft` to build it. After testing locally with `snap try`, uploading to
your namespace on the store is accomplished with `snap push`. For
publishing your snap for others, you need to post to the forum at
http://bit.ly/link. After testing, release your snap by changing the track
with `snap track`.

run - Run the given snap command
pack - Pack the given directory as a snap
try - Test an unpacked snap in the system
download - Download the given snap
prepare-image - Prepare a device image
...

It’s just a tripping point for me and by projection, I think others but I can’t be certain. On one hand I should just read through the documentation, but on the other hand, it feels like I just need a little nugget of information and it’s a bit of needle and haystack feeling even if it isn’t actually. It is very possible that the confusion stems from the separation of the snap command line tool and the snap store, but it really feels like they are intimately conjoined and I intuitively go to the snap command to try and handle snap-related things.

1 Like
4

@degville @pedronis I think @knobby might be onto something here, WDYT?

5

Yes, I think it’s a good idea too, especially if we can make this extended help fit all our help categories, ie. Basics, History, Daemons… we may need to think about ...more and Other (I think is what @knobby is suggesting).

Explaining this extra help should then be easy, and perhaps it’s the kind of behaviour you might intuitively expect from the way we’re formatting the output anyway.

1 Like
6

Absolutely was the point. Development was the example, but I would like to see information like this for all the options.

7

“Development” as a category is a bit confusing considering the conflation with snapcraft. Either a note should be added or probably a name change is warranted, maybe “Advanced” as some of the commands listed there are not strictly about development; downloading a snap is not related to development, snap run could be more of a troubleshooting thing.

8

It’s not a bad idea and I’m not particularly against, I do worry slightly how we make sure these new help sections don’t become stale, they are not associated with a command, nor are they simply a list. Do we add the list of command again there, so that when you add a command you are forced somehow to review the general/intro text?

9

@chipaca any thoughts on my worry? do you consider this backlog worthy?

10

sorry for dropping this.

I don’t have a good suggestion for making sure the help category blurbs don’t get stale. Best I can think is to review it periodically. I’ve historically been rather poor at keeping tabs on things like this… if there is a reasonable static check, it escapes me.

If we were to do it I’d try to minimise the chances of the section category blurbs going stale by keeping them together with the category description itself, a bit like how the short vs long category names are kept now. But I think you’re right that we’d probably need some way to ensure it gets looked at often.

If we can agree on a plan for this, I think it’s backlog material, yes.