#40 document upgrades + move version prefix to a separate page
Merged 7 months ago by asamalik. Opened 7 months ago by asamalik.
fedora-docs/ asamalik/modularity upgrades-doc  into  master

file modified
+1

@@ -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]

@@ -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. 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

@@ -0,0 +1,22 @@ 

+ = Module Version Prefix

In addition to prefixing module versions we also include the platform stream in the %dist tag to ensure the packages also have a clean upgrade path. I don't have a specific example of what this will look like in Fedora, however.

+ 

+ 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.

Documenting how upgrades work — considering standalone packages, modular packages, and hotfixes.

As discussed in the recent WG meeting.

I've also moved a bit of existing content describing modular version prefixes into its own page as it didn't quite fit onto the page discussing upgrades.

I would replace "RPMS" with "RPMs", as "s" isn't part of the acronym.

Note that we inspect the target modulemd rather than the current one. If the package name is no longer provided by any modules in the target state, updating to ursine is valid.

In addition to prefixing module versions we also include the platform stream in the %dist tag to ensure the packages also have a clean upgrade path. I don't have a specific example of what this will look like in Fedora, however.

I would replace "RPMS" with "RPMs", as "s" isn't part of the acronym.

That's a typo, thanks for noticing.

Note that we inspect the target modulemd rather than the current one. If the package name is no longer provided by any modules in the target state, updating to ursine is valid.

Very good point, I'll mention that explicitly.

In addition to prefixing module versions we also include the platform stream in the %dist tag to ensure the packages also have a clean upgrade path. I don't have a specific example of what this will look like in Fedora, however.

That's actually a part of the file I'm moving as part of this PR.

1 new commit added

  • PR feedback on upgrade paths
7 months ago

Pull-Request has been merged by asamalik

7 months ago