From 59b5aaaf5284079a79dffa978a2f070f294074e4 Mon Sep 17 00:00:00 2001
From: Filip Valder <fvalder@redhat.com>
Date: Mar 30 2022 07:34:41 +0000
Subject: Add Modularity category and release notes regarding module obsoletes


---

diff --git a/modules/release-notes/nav.adoc b/modules/release-notes/nav.adoc
index a91003f..ee3cb3a 100644
--- a/modules/release-notes/nav.adoc
+++ b/modules/release-notes/nav.adoc
@@ -20,6 +20,7 @@ include::{partialsdir}/entities.adoc[]
 *** xref:developers/Development_Go.adoc[Go]
 *** xref:developers/Development_Haskell.adoc[Haskell]
 *** xref:developers/Development_LLVM.adoc[LLVM]
+*** xref:developers/Development_Modularity.adoc[Modularity]
 *** xref:developers/Development_Dotnet.adoc[.NET]
 *** xref:developers/Development_Python.adoc[Python]
 *** xref:developers/Development_Ruby.adoc[Ruby]
diff --git a/modules/release-notes/pages/developers/Development_Modularity.adoc b/modules/release-notes/pages/developers/Development_Modularity.adoc
new file mode 100644
index 0000000..6e90aec
--- /dev/null
+++ b/modules/release-notes/pages/developers/Development_Modularity.adoc
@@ -0,0 +1,67 @@
+
+include::{partialsdir}/entities.adoc[]
+
+[[sect-modularity]]
+= Modularity
+
+[[modularity-obsoletes]]
+== Module Obsoletes
+
+Fedora 36 Modularity project comes with a new feature of EOL-ing/obsoleting
+of old modular streams.
+
+The obsolete feature itself has been introduced in
+https://github.com/fedora-modularity/libmodulemd/releases/tag/2.10.0[libmodulemd-2.10.0],
+but the full support within the modular pipeline became available in F36.
+
+=== Using Module Obsoletes
+
+. Add obsoletes in the
+https://pagure.io/releng/fedora-module-defaults[module-defaults] repository,
+**branch f36**. Use `<module-name>:<stream>.yaml` naming convention for the
+obsoletes metadata files. Make sure the files are stored in the `obsoletes/`
+directory.
++
+Follow the
+https://github.com/fedora-modularity/libmodulemd/blob/main/yaml_specs/[module
+obsoletes specification] for the obsoletes data format. As of the F36 release,
+there's been v1 specification available and supported in the pipeline.
+
+. Configure pungi to use the obsoletes and create a modular compose using pungi.
++
+The relevant pungi config snippet:
++
+```
+    module_obsoletes_dir = {
+        'scm': 'git',
+        'repo': 'https://pagure.io/releng/fedora-module-defaults.git',
+        'branch': 'f36',  # must match the fedora-module-defaults branch
+        'dir': 'obsoletes'
+    }
+```
++
+Follow https://docs.pagure.org/pungi[pungi
+docs] on how to create a modular compose. Check the
+https://docs.pagure.org/pungi/gathering.html#modular-compose[gathering phase
+of a modular compose] and the corresponding configuration reference.
+
+. The obsoletes metadata will appear in the `modules.yaml` file of the
+resulting repodata.
++
+When the obsoletes metadata appear in the repodata (modules.yaml file), DNF is
+expected to handle the information regarding obsoletes and react accordingly.
+
+[TIP]
+====
+For the detailed generic workflow, please follow the
+https://docs.fedoraproject.org/en-US/modularity/building-modules/fedora/module-obsoletes/[Fedora
+Modularity docs].
+====
+
+[IMPORTANT]
+====
+There's a known bug in pungi which doesn't allow to obsolete
+multiple streams of the same module. The issue is tracked in
+https://pagure.io/pungi/issue/1592[pungi#1592] in Pagure.
+====
+