From f430b832fad74b71866d99263a4eefdf2fcae871 Mon Sep 17 00:00:00 2001
From: Petr Písař <ppisar@redhat.com>
Date: Oct 08 2021 11:50:08 +0000
Subject: Demodularization


Since libmodulemd 2.13.0 and libdnf-0.64.0, it is possible to remove
a package from a module stream and start using a nonmodular package of
the same name.

This patch documents this use case.

---

diff --git a/modules/ROOT/pages/building-modules/fedora/defining-modules.adoc b/modules/ROOT/pages/building-modules/fedora/defining-modules.adoc
index 9121cf8..96a138d 100644
--- a/modules/ROOT/pages/building-modules/fedora/defining-modules.adoc
+++ b/modules/ROOT/pages/building-modules/fedora/defining-modules.adoc
@@ -364,6 +364,29 @@ Filtered RPMs are still available to use as build dependencies in subsequent sta
             - second-package-nope
 ----
 
+=== Demodularized packages (optional, defaults to none)
+
+If you decide to remove a binary package from your module stream, you will probably stop building it, or you will filter it out with a `filter` option.
+But that's not enough if you want to move the package back to nonmodular packages:
+Because the package remains listed among artifacts in the previous version of the stream and a package manager could see both the updated and the historical version.
+(The previous version can be available in GA and updates repositories, while your updated module will first appear in an updates-testing repository.)
+
+To return the package back to nonmodular package set, you need to write it on a list of demodularized packages.
+A package manager checks the demodularized list of the very latest version of the module stream over all repositories and if it only sees a package name there, it will stop hiding the same-named nonmodular packages while the stream is enabled.
+
+The list of demodularized packages is defined in `demodularized` field:
+
+[source,yaml]
+----
+    demodularized:
+        rpms:
+            - first-removed-package
+            - second-removed-package
+----
+
+With this explicit mechanism, called demodularization, a package can be demoted from a module.
+If you ever revert your decision and make the package modular again, the only thing necessary is remove it from the demodularized list.
+
 === Creating build-only components (optional)
 
 In addition to filtering subpackages, it's possible to filter out all of the artifacts produced by a component in a module.