#168 some thoughts on modularity docs
Opened 5 months ago by zbyszek. Modified 4 months ago

During the recent modularity meeting, the issue of docs came up. To follow up on this, some items that I miss:

  • an overview of what Modularity is, in the sense of a list of concepts and implementation parts. I can think of the moduleml language, MBS, changes to dnf, some other tools that were developed specifically for Modularity? It would be great to have links to "further documentation" for all the involved components. Having this in the beginning would make it easier to form a mental overview.

  • a high level overview of MBS. What does it do, how to introspect it, etc.

Various places contain admonitions like "This page needs to be rewritten" and "TBD". Are the parts that follow up-to-date or should they be ignored?

In general, I'm missing reference documentation, i.e. a text that describes in boring and precise terms what something is, allowed states and values, and the meaning of each item. The docs do a pretty good job of suggesting where normal packages come short, but are very aspirational and general in how they describe the solution.

Each module defines its own life cycle which is closer to the upstream rather than the Fedora release.

This should be updated to describe the added constraints that tie module lifetimes to Fedora releases.

Updating the system always respects user’s module choices (or lack of module) even when there are multiple (and possibly higher) versions available.

If the user doesn’t enable any modules, all packages on their system get updated to the latest versions provided by the traditional base repository. However, if the user enables a module stream, packages get updated to the newest version provided by the module.

This doesn't describe correctly what happens when default modules are present.

Scenaro 2: There were cases when users couldn’t upgrade their system to a new Fedora release because their application wouldn’t function with the new version of a language runtime coming with the upgrade. Modularity can fix this problem by providing the same language versions in both Fedora releases. With that, the user can consume a specific stream of the language and keep it even when they upgrade their system.

Is this about nodejs? What packages fall into this category that can be kept, and what packages would need to be upgraded with the system?

Stream Expansion allows for automatic submission of multiple builds of the same component based on multiple versions of its build dependencies.

Who/what decides what is built against what versions? (I guess a short explanation and a link to the later docs that explain the yaml might be enough). Are all combinations delivered to the user? (The docs imply a positive answer, but it'd be nice to be explicit.)

https://docs.fedoraproject.org/en-US/modularity/installing-modules/#_discovering_content

How to list contents of non-default modules?

What does 'dnf module reset ...' actually do? It is always mentioned as part of a bigger operation, with various scary admonitions, but I don't see an explanation of what it means on its own.

After 'dnf module reset', what happens with packages provided by that module during a) normal upgrade, b) installation of a different version of the stream that provides a different set of rpms, etc.

What does 'dnf module remove ...' do? Does it remove the rpms?
(The "Advanced" section talks about something related, but only about the specific case when "a specific package has been installed first, and then a modules has been installed after that". ?)

In general, to remove a module installed on your system, use the following command:
$ sudo dnf module remove MODULE:STREAM/PROFILE

Is providing the stream and profile actually necessary, since only one can be installed anyway?

ref: latest # <- Branch name in dist-git

Normal dist-git branches have names like master or fNN. Some explanation whether additional branches need to be created in dist-git would be useful.

Other (unlisted) packages should be considered unsupported, or an implementation detail.

What does it mean "unsupported, or an implementation detail." for users and for other packagers?

DistGit branch, tag, or a commit — so the right version of the package gets included.

"3.0" is given as an example. This doesn't look like either a branch name, a tag, a commit hash. This explanation is missing context about the namespace: a branch name in the dist-git repo for the package, a commit in blah blah blah, etc.

community: http://www.example.com/

Not that it matters much, but please suggest https:// in preference to http://.

https://docs.fedoraproject.org/en-US/modularity/making-modules/defining-modules/#_building_in_a_specific_order_optional

What does it mean that packages are built in some order. Are packages that are built earlier installed in the buildroot for packages that are built later?

https://docs.fedoraproject.org/en-US/modularity/reporting-module-bugs/

That section is also "TBD". It would be great to fill it in.

I don't understand the structure of the docs. There are various useful bits buried rather deep in the tree. E.g. "Upgrade paths" talk about what modules actually do on the end system, so I'd expect the contents of that section to be near the beginning (with a different title). In general, the docs very much feel like they were formed by combining various documents of different origin. The parts near the beginning tend to be very general and imprecise, and some parts near the end are pretty good reference documentation. It'd be great to make all of the docs like that.

There is no search. IIUC, this is still a general issue with the documentation framework. I'm raising it here nonetheless, because the docs would be much easier to consume if search was available.


a list of concepts and implementation parts

Also the "defaults" system, i.e. https://pagure.io/releng/fedora-module-defaults, and how it fits with the rest.

From today's FESCo meeting:

mbooth> You would have to document how to upgrade from non-modular to modular applications somewhere -- AIUI this is not something that is well-known

https://docs.fedoraproject.org/en-US/modularity/installing-modules/ doesn't actually answer this question, but it seems that it would be the appropriate place to put that kind of information.

FTR what @zbyszek says in the previous comment is what I had in mind at the end of today's FESCo meeting.

Add a review of searching for docs and see what the results are (not using google directly which is biased, e.g. duckduckgo)

@zbyszek, @churchyard we can talk about this tomorrow; would you join us for the Modularity Team meeting on #fedora-meeting-3?

Metadata Update from @psabata:
- Issue tagged with: Meeting

4 months ago

Login to comment on this ticket.

Metadata