Snapcraft: Move part lifecycle information into a reference

[medubelko]

Background

We currently have four documents that provide key insights into the build lifecycle:

• https://snapcraft.io/docs/parts-lifecycle
• https://snapcraft.io/docs/how-snapcraft-builds#heading--build
• https://canonical-snapcraft.readthedocs-hosted.com/en/stable/reference/parts_steps/
• https://canonical-craft-parts.readthedocs-hosted.com/en/latest/common/craft-parts/explanation/lifecycle.html

Request

On Snapcraft.io, we're missing a singular reference that covers the part lifecycle. That's the only appropriate place for these kinds of descriptions.

We ought to:

1. Move Parts lifecycle into Snapcraft's reference quadrant, adding a redirect and fixing any inconsistencies.
2. Seek and squash any inconsistencies between the two ReadTheDocs sites and the new reference. The Snapcraft page could also have insights that the other two are missing. These should be noted and marked for further work that a TA could pick up.
3. Cut the parts text out of How Snapcraft build snaps and replace it with a link to the new reference.

This work will eventually make its way into the Snapcraft ReadTheDocs site when page migration has progressed further.

These tasks will take a moderate amount of technical skill. We would appreciate anybody who is up for the challenge to give this a shot!

[Sophie-Pages]

Hi @medubelko, I would like to work on this issue. Could you please assign it to me?

[medubelko]

Salut @Sophie-Pages! I've assigned this to you.

Can you please provide an estimated completion date?

[Sophie-Pages]

Hi @medubelko, thank you! Yes, of course! I plan to have the first version by the beginning of next week at the latest. Is that okay with you, or do you need a first version for this week?

[medubelko]

@Sophie-Pages That would great! The first draft doesn't have to be very refined – I'd like to review the structure of the page to ensure you're on the right foot before we put lots of time and effort into the complete product.

And of course, let me know if you have any technical issues with the repository.

Thanks again!

[Sophie-Pages]

Hi @medubelko, following CODA's guidelines, I created a pull request with a draft of the Parts lifecycle reference here: #163.

I have a few questions/remarks:

• On this page https://snapcraft.io/docs/parts-lifecycle, I noticed an organize step that is not present anywhere else. Should it be added to the Parts lifecycle?
• On this page https://canonical-craft-parts.readthedocs-hosted.com/en/latest/common/craft-parts/explanation/lifecycle.html, I noticed an overlay step that is not present in other Snapcraft documentation but I found a Rockcraft documentation talking about it here https://documentation.ubuntu.com/rockcraft/en/latest/reference/parts_steps/. Should it be added to the Parts lifecycle?
• I decided to add directories and commands to the reference document because I found them useful. What do you think?
• About fixing inconsistencies in Snapcraft documentation, should I pull the documentation from Discourse and make a pull request on this repository?

[medubelko]

Hi Sophie,

• On this page https://snapcraft.io/docs/parts-lifecycle, I noticed an organize step that is not present anywhere else. Should it be added to the Parts lifecycle?

That looks to be an error. organize is a part key that takes effect during the stage step.

• On this page https://canonical-craft-parts.readthedocs-hosted.com/en/latest/common/craft-parts/explanation/lifecycle.html, I noticed an overlay step that is not present in other Snapcraft documentation but I found a Rockcraft documentation talking about it here https://documentation.ubuntu.com/rockcraft/en/latest/reference/parts_steps/. Should it be added to the Parts lifecycle?

Overlays are related to copying the host's base filesystem, and Snapcraft doesn't use them.

• I decided to add directories and commands to the reference document because I found them useful. What do you think?

I planned for this to be one document, which would be make it easier on the reader's comprehension and the TOC. I don't believe there are enough unique facets with how Snapcraft implements parts that it need be that much longer than the existing topic in Craft Parts. I saw the bigger challenge as how to reconverge the text about parts that's spread to other pages. For example, Parts and Steps would need to be renamed because it's about a lower-level implementation, but should its Step output directories section be exctracted and put in the updated lifecycle page? Questions like these need addressing.

Do you think the content is too long for one page?

• About fixing inconsistencies in Snapcraft documentation, should I pull the documentation from Discourse and make a pull request on this repository?

Yes! That's the correct (but slightly roundabout) process. Don't worry if there are bits that don't render in GitHub's Markdown preview – that's to be expected.

[Sophie-Pages]

Hi @medubelko,

Thank you for clarifying the organize and overlay steps.

I planned for this to be one document, which would be make it easier on the reader's comprehension and the TOC. I don't believe there are enough unique facets with how Snapcraft implements parts that it need be that much longer than the existing topic in Craft Parts. I saw the bigger challenge as how to reconverge the text about parts that's spread to other pages. For example, Parts and Steps would need to be renamed because it's about a lower-level implementation, but should its Step output directories section be exctracted and put in the updated lifecycle page? Questions like these need addressing.

Do you think the content is too long for one page?

We can absolutely add the Step output directories to the reference. I believe most of the information is already in the reference but I will need to check. If you see anything else that may be missing, don't hesitate to tell me.

I'll work on the inconsistencies and hope to provide a pull request by next week. While working on that, I may find other information that could be missing from the reference.

[Sophie-Pages]

Hi @medubelko,

I updated my existing pull request with new commits.

What I did: I added new information in the reference and removed duplicate information from Parts lifecycle and How Snapcraft build a snap. I believe we could clean Parts lifecycle even more from duplicate information (like commands and directories) but then we would lose additional information that this explanation bring and I don't think this is what we want.

Note: Because I added the raw documents first in my pull request, you should be able to see clearly the modifications I made by going commit by commit.

[medubelko]

Hi @Sophie-Pages,

I've had a quick look at the document. What I've seen so far looks excellent. Most importantly for our users, it's very complete, and combines and contextualises a lot of useful information about the underlying workings of what parts do and how they interact with the tool as a whole.

I'll give it a full review as soon as possible, but for now I'll address this:

I believe we could clean Parts lifecycle even more from duplicate information (like commands and directories) but then we would lose additional information that this explanation bring and I don't think this is what we want.

The contents of Parts lifecycle should be added to your new explanation page (explanation/parts-lifecycle.md), either copied or written in a more user-friendly way (I prefer the second). You've already covered it briefly, so you're on the right track. As we discussed, the goal of this ticket is to describe parts from the point of view of Snapcraft – the existing parts references are generic because they account for many other apps, which isn't very useful to new Snapcraft users.