Add Ubuntu Core Stacks bits as a new subsection

[jhodapp]

We are using repo to manage sub-git-repositories for the Ubuntu Core Stacks documentation items. I've added documentation in README.md detailing how to fetch these sub-repos. This was the most sane way we could come up with on how to manage all of these various moving parts while not using a monolithic repository duplicating efforts of each snap's documentation.

[bergotorino]

All good

[morphis]

Would be nice to have a snap for repo.

[jhodapp]

It would be nice indeed. I'll add this as a story for our backlog.

[jhodapp]

Story added.

[morphis]

Lets wrap those shell commands into the right format

    $ snap install documentation-builder

[jhodapp]

It should be the right format as the Markdown syntax is just to indent with at least 4 spaces to get a codeblock.

[morphis]

Ok.

[morphis]

See comment about shell commands above

[alfonsosanchezbeato]

Why a hidden folder for ~/bin? I think the usual way is without the dot.

[jhodapp]

I based this off of an example from a site and this is the approach they took. I actually rather like the dot as it doesn't pollute your home directory in any kind of normal visual way. I'm not opposed to the other way either if someone has a strong opinion one way or another.

[morphis]

Why do we have udisks and udisks2?

[jhodapp]

We have a snap for both and thought it'd be important to discuss the differences between the two for any integrators out there.

[morphis]

We only have a udisks2 snap. A udisks snap does not exist. If you're referring to https://code.launchpad.net/~snappy-hwe-team/snappy-hwe-snaps/+git/udisks then I don't know why that exists but it does not have any relevance and should be removed.

[morphis]

Not sure why wifi maps to wifi-ap ?

[jhodapp]

It is intending to be a general wifi section, so if we have anything else (such as adding docs for wireless-tools), we'll share this directory with wifi-ap.

[morphis]

This is not only about "device management" but also playback/recording/..

[jhodapp]

That's covered in another bullet point below.

[morphis]

You mean media playback/recording management? I am not sure in which cases we want to tell people to use media-hub. That mostly makes only sense on consumer devices. In all others cases people want direct access to pulse and alsa when then serves as playback/recording service. Can't we name this point just "Audio" and the other one "Media management"?

[morphis]

Disk/storage manegement. Not only about where things are mounted. Udisks offer a lot more features like formatting, partioning, ...

[jhodapp]

Addressed this by making it more generic.

[morphis]

We should explain what TPM is and also outline the actual difference between both snaps (one supporting just 1.2 and the other one 2.0).

[jhodapp]

I need some help on this. I agree with you, I just have no experience in the details. Could also reach out to Scott to write a little blurb up.

[jhodapp]

For now, I added a link to the Wikipedia page for TPM. We should improve on this for the future when appropriate.

[morphis]

Ok. Tony wrote once ago a paper about this we can easily integrate here.

[morphis]

Both snap names go by lower-case

[morphis]

Shouldn't we better put this under a separate section named "testing" or similar?

[jhodapp]

Yes indeed. I had that, but since we didn't have any documentation yet I left it out for now.

[alfonsosanchezbeato]

Some small changes required.

Also, please rebase and force push so we have a cleaner history when the PR gets merged. Probably something like 3 commits would make sense: one for README.md, another one for adding default.xml and a third one adding the files from en/* .

[alfonsosanchezbeato]

I would add a "TODO" to the parts not created yet.

[jhodapp]

Done

[caldav]

In the main navigation, please don't add sub-pages without a location, they clutter navigation and make you hunt for actual links, these WIP topics are already visible (and don't look like links) on the index page of the section.

[alfonsosanchezbeato]

Why a hidden folder for ~/bin? I think the usual way is without the dot.

[alfonsosanchezbeato]

Better something like "Modem Cellular Data management"

[jhodapp]

@alfonsosanchezbeato I personally like when a history is detailed as is and not squashed down. I know we've differed in preference here before. What does the rest of the team prefer...I'll accommodate the group opinion.

[alfonsosanchezbeato]

@jhodapp it is not about being detailed or not, it is about having a clean history. By clean I do not mean longer or shorter, it can go either way, but, well, clean. This is something that can have different definitions indeed, but some cases look very clear to me.

For instance, let's take commit "Fix export statement in README.md" as an example. It is pretty clear that what it contains is a typo fix for a previous commit in the PR, and therefore if it gets merged it will simply add a commit to trunk with no useful information. That just clobbers main trunk history. It will be better if that concrete commit gets merged with "Add documentation to the README.md ...", and I think we can agree on that.

The same happens with the changes to en/metadata.yaml that are scattered along a few commits, being the changes of the same nature (adding sections). Splitting the changes in that way does not add useful information to trunk and makes history harder to read.

As said, we can discuss what "clean" is, because there are different strategies on how commits can be organized. But one rule that should be in any strategy is that a correction of a typo of a previous commit in the same PR, or adding items of the same type in a code section, should be squashed into the original commit inside the PR.

In other words: the internal history of the development of a PR is not interesting for the main trunk.

A blog post on this: https://www.notion.so/Keeping-Commit-Histories-Clean-0f717c4e802c4a0ebd852cf9337ce5d2 @

[alextnewman]

I don't mean to be pedantic, but functionality is used three times here with slightly different meaning. Is there a more concrete way to phrase this?

[jhodapp]

That's not pedantic, that's a good catch that I normally see myself.

[jhodapp]

@alfonsosanchezbeato I agree with you on the typo fixes. Since we've had this conversation before I'd recommend that you specify more precisely what you mean the next time it comes up. For example, specify that you'd like to see the typo commit fixes merged into other history items. My default is to prefer to leave the history exactly as happened during development, but that's just my preference.

[jhodapp]

I addressed all review comments that I thought appropriate (which was almost all of them). Take another look.

[morphis]

@jhodapp @alfonsosanchezbeato Lets not discuss this here. Every project has it's own preference. Lets see what @caldav wants. If he is fine with what @jhodapp did, then we're ok.

[morphis]

As we're talking about the snaps above we should give the right names here which are 'alsa-utils' and 'pulseaudio'.

[morphis]

We don't. See comment above. The has only one too

snap find udisks
Name     Version  Developer  Notes  Summary
udisks2  2.1.7-2  canonical  -      D-Bus service to access and manipulate storage devices

[morphis]

What do you mean with this paragraph? I have the feeling that the word 'application' is a bit overloaded in this context when talking about snaps as it has a different meaning there.

[jhodapp]

It is overloaded indeed, however that's ok in this context. For example, if someone reads it as an app like on a phone vs applying a snap to something, it still gives the same context. What I meant here though is if someone wants to use NetworkManager for example but they want it to manage ethernet connections, they'd need to do the work. It's not a great example since we'll be doing it, but it makes my point.

[jhodapp]

NOTE: I changed it a bit in my latest commit. See if that clarifies it a bit for you.

[morphis]

Later we may want to give an example here of how to contribute on launchpad as for today's github users that is not really obvious ...

[jhodapp]

+1, I'll add a section on that now as I think that is important.

[morphis]

Ubuntu Stacks -> Ubuntu Core Stacks

[morphis]

And change to just:

Ubuntu Stacks currently offers the following areas of functionality:

[jhodapp]

Done

[morphis]

Lets drop "several interesting". That is a personal feeling.

[jhodapp]

Done

[morphis]

Ok. Tony wrote once ago a paper about this we can easily integrate here.

[morphis]

There is just one single way. See comment below.

[jhodapp]

We should get rid of the udisks repo then if it's not being used. That's quite confusing.

[jhodapp]

Done

[morphis]

That is a thing which we need to debate. "master" always reflects development. For documentation which reflects snap's released into the stable channel we need to use the "stable" branch of each repository which will always reflect the latest version either inside stable or candidate. However we should never use "master" here unless the whole documentation is explicitly flagged to represent development.

[jhodapp]

It's a fair point but one we can correct in the future in a coordinated effort with David Calle since everyone is using master branches today.

[caldav]

I think we can review it once versioning lands in documentation-builder. Let's use master for now.

[morphis]

I don't agree. master always reflects our development branch. Once a snap is pushed to beta/candidate everything is tagged and merged into the stable branch. With that we can always ensure we have a well-known state of our documentation for our snaps being in beta/candidate/stable. So if we select a default here for the time being it should be 'stable' and not master. Otherwise we risk that not yet available features become available on docs.ubuntu.com and that is nothing we want, even not with this first initial version.

[alextnewman]

Is this a Canonical-ism? I find it a little irregular that we don't treat master as a "current stable" branch and use branches for features. While I completely understand the point of a release branch, it seems strange to me that we should use any branching strategy that doesn't trend toward a canonical (lowercase c) master.

[morphis]

Do we have a buy-in from @caldav on this?

[jhodapp]

Haven't received a review from him yet so unsure. I'll ping him again.

[caldav]

Makes a lot of sense here and could be worth exploring for other use cases in the snap doc, thanks for the idea. Works for me.

[jhodapp]

Great thanks. It's very easy to use and I found is the best solution for this. I research git submodules and git-subtree as well.

[caldav]

Some formatting nitpicks.

I'd like @nottrobin and @WillMoggridge to have a look at the repo requirements (README.md), that would need to be run when deploying the site.

[caldav]

In the main navigation, please don't add sub-pages without a location, they clutter navigation and make you hunt for actual links, these WIP topics are already visible (and don't look like links) on the index page of the section.

[caldav]

Is there a need for a numbered list here (eg. steps to follow or order of preference)? If not, please use a simple list (same goes for other pages)

[jhodapp]

Done

[caldav]

I don't think that "one or more" is needed there.

[jhodapp]

Done

[caldav]

Missing a "for"

[jhodapp]

Done

[nottrobin]

The intention of https://docs.ubuntu.com is as a home for technical documentation pertaining to specific versions of specific software products. The intention is that each set of documentation would basically be an HTML representation of the contents of a /docs folder within a specific codebase repository.

This then allows us to simply provide two features across all our sets of documentation:

• We can version the documentation in accordance with the branches/tags on the codebase repository
• We can easily provide links to the place in the repository where each document can be edited (coming soon)

The hope is that this will provide the reader with clarity in a number of ways. If they are hypothetically looking at https://docs.ubuntu.com/snapd/2.22/en/commands, then they can know:

• That this page specifically pertains to version 2.22 of snapd
• That all the documentation source is at https://github.com/snapcore/snapd/blob/2.22/docs/
• That the software for this documentation all lives in https://github.com/snapcore/snapd/blob/2.22/
• That it's source can be found at https://github.com/snapcore/snapd/blob/2.22/docs/en/commands.md

I am aware this vision hasn't quite materialised. MAAS is closest, but although the docs live at https://github.com/canonicalltd/maas-docs rather than in the original codebase.

However, I'd still rather stay as close to this vision as possible, to provide simplicity and clarity in our software and documentation structure.

This simplicity won't just make it easier for the reader to understand, it also makes it much easier for us to manage. One of the problems with managing the existing https://developer.ubuntu.com project that made it very hard to work with were that it pulled in many different bits of documentation from many different places with no clear structure. Not only does this make it very hard to understand where stuff is coming from, it also complicates dependencies and makes it more likely that a link will break somewhere internally - a software project will move or something - and then the documentation as a whole rapidly either brakes or gets out of date. I feel that by creating a clear set of hard and fast rules to govern the structure of our documentation we can avoid getting into this mess.

So to bring this back to this request. My preferred solution would be that each of the separate software products mentioned in default.xml, which appear to be separate software products (alsa-utils, pulseaudio, power etc.) have their own documentation, and then each of those sets would be linked to from the central Ubuntu Core documentation. This will be much simpler and more transparent for everyone to understand.

I realise this might mean we have a cumbersome list of different sets of documentation (ubuntu-core, core-alsa-utils, core-modem-manager etc.), so it may well be worth discussing ways in which we can group sets of documentation within docs.ubuntu.com. I have no problem with that. But I would much prefer that we keep each set of documentation as a self-contained unit.

This would keep it so that if you're working on ubuntu-core-docs, you can simply run documentation-builder and see exactly what's at http://docs.ubuntu.com/core/, as with all the other documentation.

[alextnewman]

@nottrobin I feel, based on the points that you've made, that we're not representing what we're trying to do very well. I'll try to provide some context for how and why we are attempting to collect our documentation this way.

We are specifically using repo as a structured way to aggregate the content from multiple git repositories and provide a coherent index along with the potential for associated top-level guides to content within those repositories, so I don't think we fundamentally disagree with the goal of maintaining documentation in our various git repos in a way where documentation can track alongside the development and MR/PR workflow through release branches. The goal here would be to place the metadata describing this collection not in an arbitrary internal listing but rather using a publicly available tool which is source controlled itself and can be run by any developer. Our own internal discussion on the subject led us on this path after observing that we would be doomed to recreate this aggregation solution if we did not embrace something widely available. Further, we embraced repo so that we could create a loose association of repositories via branches/tags as opposed to an unnecessarily tight association of commits via git sub-repos.

I would argue that by representing our component categories within Core as separate software components is not only unapproachably esoteric for customers coming to our solution from external stacks (i.e. "why do I search for alsa when I care about sound?") but also puts us on the path of representing Core as a collection of things instead of a product. So, I'd say we're very interested in pursuing a solution for creating "sets" of documentation (as you've mentioned) and that I'd like to respectfully ask that you reconsider our proposed solution for that subdomain of the problem and not disregard it outright. I don't think what we're doing is in conflict with any requirement or intention you've described and any movement toward defining a centralized structure for repos containing documentation or any proposed style-guide binding that documentation would be extremely helpful for our team as we work to make these rather technical components more accessible to our users. And I think that we need an additional "wrapper" on top of these upstream repositories so that we can avoid long-running branches that obfuscate history or attempting to foist Canonical-specific documentation or productization on the open source projects we utilize and contribute to.

I feel like we should be in very close to alignment in what we're trying to accomplish, so I'd like to propose that we have a discussion internally on how to best realize the benefits of a distributed workflow and a centralized product vision. The last thing we want to do is saddle your team with technical complexity, so I had originally proposed to my team that we perform this documentation aggregation internally before "releasing it" for inclusion in upstream documentation should there be a significant cost with regard to the tools we're using (like repo). I would appreciate any feedback you can offer on how to accomplish this.

[nottrobin]

Thanks @alextnewman for replying in such depth.

Sorry for sounding negative in my response earlier. I am primarily interested in creating simple patterns for all documentation to follow going forward. I'm sure the issues we're dealing with here will come up again, and I think therefore that the patterns we use deserve careful consideration, because complexity is easily created and very hard to undo without starting from scratch.

I agree it sounds like we're fairly aligned in our goals. Yes I think having a meeting about it would be very helpful.

[nottrobin]

Okay after much discussion with everyone, I'm happy for this git-repo solution to go ahead for now, as this documentation needs to be drawn together with some urgency.

I am still worried that it sets a bad precedent. I still think that each set of documentation markdown files should be self-contained, and the relationship between markdown repositories and built HTML files should be direct and simple. And this breaks that.

However, we do need a pattern for drawing together related sets of documentation. This should ideally be codified higher up the chain, with core functionality in documentation-builder or in the docs.ubuntu.com application, rather than hacked together with tools like git-repo in individual documentation sets. But unfortunately it doesn't look like creating and implementing the ideal solution can happen in time for this.

So for now I'm happy with this solution in this instance. I will try to revisit this to come up with a more future-proof solution in the near future, and I'd also appreciate it if everyone else would keep this in mind and let me know if they have any ideas.