From e5bb0ae95c0da120956c2f0158dbd70443be0b47 Mon Sep 17 00:00:00 2001
From: Adam Samalik <asamalik@redhat.com>
Date: Dec 07 2018 11:29:55 +0000
Subject: [PATCH 1/2] 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.

From 5ac6b5d0da9b0856cc5f59d21d517d4e6fa8b3d4 Mon Sep 17 00:00:00 2001
From: Adam Samalik <asamalik@redhat.com>
Date: Dec 11 2018 17:27:58 +0000
Subject: [PATCH 2/2] PR feedback on upgrade paths


---

diff --git a/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc b/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc
index 5aeeb78..3a7230b 100644
--- a/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc
+++ b/modules/ROOT/pages/architecture/consuming/upgrade-paths.adoc
@@ -4,14 +4,14 @@ On the package level, upgrades of a modular system work the same way as on a tra
 
 There are up to three classes of RPM packages available to a modular system:
 
-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.
+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.
+2. Add modular packages that are part of an enabled module, and potentially replace any standalone packages having a same name. To do this, look at the target modulemd rather than the current one. 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

