Upgrade Paths in Modularity

Module builds with static_context: true keyword are called static-context. A value of context field is the only factor considered when establishing an upgrade path.

For instance, having installed foo:stream:0:A which requires bar:x and the following four static-context modules in a repository:

DNF will create two lineages A and B, picks lineage A because foo:stream is already installed with a static context A, warn that foo:stream:2:A cannot be installed because it conflicts with an already enabled stream bar:x, and will upgrade to foo:stream:1:A because version 1 is the highest number which has met run-time dependencies.

Module builds without static_context: true keyword are called dynamic-context (or nonstatic). Establishing an upgrade path actually does not consider the context value, but run-time dependencies of the modules. This algorithm is deprecated because it’s cumbersome, does not support changing run-time dependencies, and adding and removing contexts.

For instance, having installed foo:stream:0:Z which requires bar:x and the following four dynamic-context modules in a repository:

DNF will create two lineages 1 and 2, and will upgrade to foo:stream:2:A. This is because foo:stream:2:A has the highest version in a lineage whose modules require bar:x as the already installed foo:stream:0:Z.

Observe that with the dynamic context a module maintainer cannot express that foo:stream:0:Z or foo:stream:1:B should upgrade to foo:stream:2:C if the maintainer decided to change a dependency from bar:x to bar:y and were unable to build foo:stream:2:A (e.g. an upstream rewrote the application from Ruby 2.4 to Ruby 2.6).

Once DNF identifies the latest module, all modular metadata defined in that module build will apply and replace modular metadata occurring in the older module versions. That includes a module description shown with dnf module list command, a list of packages installed when installing a profile, or a list of demodularized packages.

The only data which are used from older versions of (a context of) the stream are RPM packages. That enables users to downgrade a package in case the newer module build contained a bug.

For the reasons explained above, if you want to add a new context (e.g. you want to add a support for a new Perl 5.32 to your perl-DBI module), you need to use a static context:

It’s not possible to achieve this by standard means with a dynamic context. DNF would report a warning or an error. If you ever needed to achieve this with nonstatic contexts, the key point how to indulge DNF is fill a matrix of contexts and versions with artificial modules which have never been built (i.e. manually writing the modulemd documents):

On the other hand, with a static context DNF will understand that modules from context B should not mix with module from a context A. When installing perl-DBI:stream for the first time, DNF will pick the right context based on an already installed perl stream. When upgrading perl-DBI:stream, DNF will preserve the context based on an already installed perl-DBI:stream context. Thus using static-context modules is recommended.

The same constrains of dynamic context and a strong recommendation for static context apply here. With static context you can stop building modules for that context whenever you want. With dynamic context you cannot and need to maintain the full matrix forever.

With a static context it’s possible to use a modulemd-obsoletes document to switch to a completely different stream. This is useful when you want to stop supporting an existing stream, or a context, and you provide a replacement. When user has installed an obsolete stream, or a context, DNF will offer switching to the replacement.

This feature is currently experimental and needs to be enabled in DNF configuration with module_stream_switch=True option.

A system has enabled streams bar:1 and loo:1; a repository contains:

dnf install foo command will install foo-3.

A reasoning is following: Active contexts are bar:1::a and loo:1::c. (It is not bar:1::b because loo:1 is enabled.) Hence packages available to DNF are foo-2 and foo-3. (It is not foo-1 because it’s nonmodular and has the same name as modular foo-2. It is not foo-4 because bar:1::b has an unmet modular dependency. It is not foo-5 because bar:2 is not enabled.) Highest NEVRA among the two available packages is foo-3. Therefore DNF will install foo-3.

Next day a new update appears:

dnf upgrade foo command will not upgrade anything, reporting foo-3 is already latest and installed.

A reasoning is that the pile of available packages contains foo-1, foo-2, and foo-3 and foo-3 is already installed.

Please observe that foo-1 package became available because foo is unlisted name now. However, unlisting that name does not disappear the modular packages foo-2 and foo-3. Modular and and nonmodular foo packages are now handled equally.

Another day a next update appears:

dnf upgrade foo command will upgrade to foo-6.

A reasoning is that foo-6 is the highest one from a pile of available packages among foo-1, foo-2, foo-3, and foo-6.

This demonstrates that a successful demodularization of a package requires both unlisting that package name and building that package, this time out of any module, with a new, highest version.