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?
Yes, of course - thanks for letting me know. I’ll update this post when it’s done.
Update: I’ve added Layout to the above reference and also to the top-level metadata document. I think we missed this because layouts had been experimental for so long.
missing refresh-mode: endure | restart?
Thanks for letting us know. I’ve added it above and also to the snapcraft app metadata document.
Instead of proposing changes as a message, we can also edit the wiki directly, by clicking the green icon in the first post 
Thanks for flagging this missing option. I’ve now added it to the reference and other services-related docs.
there is no mention of setting plugs for hooks that are documented on https://snapcraft.io/docs/supported-snap-hooks
This threw me for a long time and would have been helpful to have been here
That’s a really good point - sorry it caused you to struggle, and it’s something that should be here. I’ll add hooks to this document.
