@degville should remove “legacy” adapter and “full”. Default is “full”, so the only really interesting bit is “none”.
However adapter will be dropped altogether for core 20 and its use is quite limited. @sergiusens suggests removing it altogether.
Thanks for the updates - I’ll make those changes.
Please feel free to edit docs yourself though. Anyone can make modifications, and we want to encourage people to do so. I always look over whatever has changed to keep it consistent.
I’m new here and saw this a while ago.
For the apps.<app-name>.command description, Classic Confinement should point to here.
Hello - welcome to the forum, and thanks for flagging this. The link should be fixed now.
We should add the top-level environment here as well, since it works not just for an app but globally in the snapcraft.yaml (in which case it ends up applying to all of the apps in the generated snap.yaml)
is autostart correct? It’s in the parts.<partname> stanza? I thought it was an apps.<appname> item!
Thanks for spotting this and letting us know! You’re right - it should be in apps., as described in Snapcraft app and service metadata. I’ll fix it now. Edit: fixed.
Is package-repositories available to use now?
Thanks for flagging this - yes, it became available with snapcraft 4.3. I’ll update the docs !
Update: I’ve just tried a simple snap with Snapcraft 4.3 and package-repositories and it seems the feature is still flagged as experimental (it needs the --enable-experimental-package-repositories flag). I’ll ask the Snapcraft team for an ETA on this feature being stable.
In the parts.<part-name>.source-subdir section, I think it would be useful to add a note that if you use this, then your build will not have access to files outside the subdir (like one level up for instance).
Otherwise it might seem that using source-subdir is equivalent to cd’ing to the relative directory in an override-build step, when that is not the case.
The version field is not really mandatory, in fact, if you use adopt-info you should not use it. Maybe it could be written as mandatory*, and then have an explanation in the description, like this:
* This field is normally mandatory, except if you use
adopt-info. See Using external metadata for more details.
Thanks for this! - I’ve added your suggestion to source-subdir above and in Snapcraft parts metadata.
Thanks, that’s a really good point about version. I’ve updated the description above, and also it’s entry on Snapcraft top-level metadata.
This is missing the service ordering parts which are already documented for The snap format .
| Name | Description |
|---|---|
apps.<app-name>.beforeoptional |
List of applications that are ordered to be started before <app-name>. Applications must be part of the same snap. (snapd 2.31+)Type: list[string]Requires daemon to be set as the app type. |
apps.<app-name>.afteroptional |
List of applications that are ordered to be started after <app-name>. Applications must be part of the same snap. (snapd 2.31+)Type: list[string]Requires daemon to be set as the app type. |
It would be nice if this document talked about the /root/parts/<part-name>/* subdirectories where relevant.
For example, parts.<part-name>.organize says A map of files to rename / the key represents the path of a file inside the part and the value represents how the file is going to be staged.
But if I shell into the build container and go to /root/parts/<part-name>/, I see these subdirectories:
Does organize copy/rename those files from src to build? From src to install? From build to install?
Similarly, does parts.<part-name>.stage copy files from build to install? Or install to /root/stage? Does parts.<part-name>.prime only copy from /root/stage to /root/prime, or does it get involved in /root/parts/<part-name>/ somehow?
The context that I’d like to know all of this is that if I use say override-build and then run snapcraftctl build, I’m left unsure what steps have been run, and where the files have been put (build or install or /root/stage/?).
It would also be great if sections like parts.<part-name>.override-build could talk about what exactly snapcraftctl build does. IIRC, it handles running parts.<part-name>.organize, so if you don’t run snapcraftctl build for whatever reason, the files don’t get organized.
Why do we need to edit the documentation in such a strange way instead of editing some md file on github?
I don’t see any benefits in this approach, and many issues, like polluting this chat and needing to reference “where the section says X and Y it actually should be…”. I mean, this definitely doesn’t scale in the long term and seem to just become more and more confusing 
I completely agree that this is not a suitable way to collaborate on docs, and. I’ve raised this as an issue both before and after the implementation. It seems that it’s the way that Canonical has decided to do things despite being unworkable/unscalable. Similarly the Ubuntu Discourse does the same thing for tutorials and docs specific to Ubuntu, also. Whenever I’ve raised this issue it has been stated that it’s fine and won’t be changing.
I created a thread for this, can you please write something to share your support? 
@degville can you add layouts to the reference here and maybe link to the other page we already have about layouts too?
