From 4f9e06fb4eac35b294b5d29ed5a2a6fa19fd83fc Mon Sep 17 00:00:00 2001 From: mprahl Date: Nov 09 2018 22:23:11 +0000 Subject: Add documentation explaining the module version prefix --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index b71ed8b..2fb7b6d 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -4,6 +4,7 @@ ** xref:architecture/consuming.adoc[Consuming Software] *** xref:architecture/consuming/dnf-behavior.adoc[DNF Behavior] *** xref:architecture/consuming/naming-policy.adoc[Naming Policy] +*** xref:architecture/consuming/upgrade-paths.adoc[Upgrade Paths] * xref:making-modules.adoc[Making Modules] ** xref:making-modules/adding-new-modules.adoc[Adding New Modules] ** xref:making-modules/updating-modules.adoc[Updating Existing Modules] diff --git a/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc b/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc new file mode 100644 index 0000000..be05119 --- /dev/null +++ b/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc @@ -0,0 +1,24 @@ += Modular Upgrade Paths + +== Version Prefixes + +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.