From e5bb0ae95c0da120956c2f0158dbd70443be0b47 Mon Sep 17 00:00:00 2001 From: Adam Samalik Date: Dec 07 2018 11:29:55 +0000 Subject: document upgrades + move version prefix to a separate page --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index cc77458..b5a998b 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -5,6 +5,7 @@ *** xref:architecture/consuming/upgrade-paths.adoc[Upgrade Paths] ** xref:architecture/building/name-and-id.adoc[Module name and ID] *** xref:architecture/consuming/naming-policy.adoc[Naming Policy] +*** xref:architecture/module-version-prefix.adoc[Version Prefix] ** xref:architecture/stream-expansion.adoc[Stream Expansion] * xref:making-modules.adoc[Making Modules] ** xref:making-modules/adding-new-modules.adoc[Adding New Modules] diff --git a/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc b/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc index be05119..5aeeb78 100644 --- a/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc +++ b/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc @@ -1,24 +1,17 @@ -= Modular Upgrade Paths += Upgrade Paths in Modularity -== Version Prefixes +On the package level, upgrades of a modular system work the same way as on a traditional system — using NEVRA comparison to determine which packages are the newest. There is, however, one additional step right before the NEVRA comparison that needs to happen on a modular system — limiting which packages are going to be part of the comparison based on what modules are enabled — and that is the key difference. -Modules built with Module Build Service (MBS) v2.8.1 or newer will contain a -version prefix. This prefix is derived by the stream version of the Platform -module that the module build buildrequires. For instance, if the Platfom module -has a stream of `f29`, then the stream version would be `29`. This makes it so -that a module with a version of `20181109101859` would become -`2920181109101859`. This ensures that modules built with later versions of -Fedora always have higher versions, and thefore, have a clear upgrade path. +There are up to three classes of RPM packages available to a modular system: -The reason this is needed is that a module's version is dynamically derived -from the commit timestamp of the modulemd that was used for the module build. -This becomes an issue in the following scenario. If you build a module for -Fedora 28, then build a module of the same stream for Fedora 29, then when -upgrading to Fedora 29 will work just fine because the module build for Fedora -29 was built later, so therefore has a higher version. If the module build for -Fedora 28 needs to be rebuilt however, then the version will be higher than the -Fedora 29 build since the modulemd will have a newer commit. This will mean that -a user with the Fedora 28 module version installed, will encounter issues when -upgrading to Fedora 29 since the user will already have a module with a higher -version installed than what is provided by Fedora 29. Prefixing the module -version with the buildrequired Platform stream version solves the issue. +1. **Standalone packages** (also refered-to as "bare RPMS" or "ursine RPMS") — packages not being part of a module. In Fedora, these are coming from the Everything repository. +2. **Modular packages** — packages being part of a module. In Fedora, these are coming from the Modular repository. +3. **Hotfixes** — standalone packages created on-demand by users or vendors meant to fix a critical issue before an official upgrade comes from the distribution. These need to be provided in a separate repository with a hotfix flag set. Fedora doesn't provide such packages. + +To determine the limited set of packages for the NEVRA comparison, the following algorithm is used: + +1. Take all standalone packages. +2. Add modular packages that are part of an enabled module, and potentially replace any standalone packages having a same name. This step ensures that modular packages have always a higher priority than standalone packages. In other words, standalone packages can never upgrade modular packages. +3. Add all hotfix packages. These are just added, not replacing anything. That means hotfixes can potentially upgrade both traditional and modular packages. + +The next step is to take this set of packages, and run a NEVRA comparison to determine the highest version of each package. The highest versions are then installed as a part of the upgrade process. \ No newline at end of file diff --git a/modules/ROOT/pages/architecture/module-version-prefix.adoc b/modules/ROOT/pages/architecture/module-version-prefix.adoc new file mode 100644 index 0000000..d18067d --- /dev/null +++ b/modules/ROOT/pages/architecture/module-version-prefix.adoc @@ -0,0 +1,22 @@ += Module Version Prefix + +Modules built with Module Build Service (MBS) v2.8.1 or newer will contain a +version prefix. This prefix is derived by the stream version of the Platform +module that the module build buildrequires. For instance, if the Platfom module +has a stream of `f29`, then the stream version would be `29`. This makes it so +that a module with a version of `20181109101859` would become +`2920181109101859`. This ensures that modules built with later versions of +Fedora always have higher versions, and thefore, have a clear upgrade path. + +The reason this is needed is that a module's version is dynamically derived +from the commit timestamp of the modulemd that was used for the module build. +This becomes an issue in the following scenario. If you build a module for +Fedora 28, then build a module of the same stream for Fedora 29, then when +upgrading to Fedora 29 will work just fine because the module build for Fedora +29 was built later, so therefore has a higher version. If the module build for +Fedora 28 needs to be rebuilt however, then the version will be higher than the +Fedora 29 build since the modulemd will have a newer commit. This will mean that +a user with the Fedora 28 module version installed, will encounter issues when +upgrading to Fedora 29 since the user will already have a module with a higher +version installed than what is provided by Fedora 29. Prefixing the module +version with the buildrequired Platform stream version solves the issue.