From 77460aaf1c6edb4439ac50f3960bf6cceb6631f0 Mon Sep 17 00:00:00 2001 From: Filip Valder Date: Jan 25 2022 08:52:09 +0000 Subject: Module obsoletes guidelines --- diff --git a/modules/ROOT/pages/building-modules/fedora/adding-new-modules.adoc b/modules/ROOT/pages/building-modules/fedora/adding-new-modules.adoc index c065ace..09cea24 100644 --- a/modules/ROOT/pages/building-modules/fedora/adding-new-modules.adoc +++ b/modules/ROOT/pages/building-modules/fedora/adding-new-modules.adoc @@ -95,4 +95,8 @@ Submitting module builds is done using `fedpkg` and is covered in the xref:build == Publishing the Module -include::{partialsdir}/submit-module-update.adoc[] \ No newline at end of file +include::{partialsdir}/submit-module-update.adoc[] + +== Module Stream EOLing/Obsoleting + +include::{partialsdir}/module-obsoletes.adoc[] diff --git a/modules/ROOT/pages/building-modules/fedora/index.adoc b/modules/ROOT/pages/building-modules/fedora/index.adoc index 3092431..cc9d565 100644 --- a/modules/ROOT/pages/building-modules/fedora/index.adoc +++ b/modules/ROOT/pages/building-modules/fedora/index.adoc @@ -2,4 +2,6 @@ If you wish to maintain an additional version of an application, language stack, or any other piece of software, modules might be the way to go for you. -The xref:building-modules/fedora/adding-new-modules.adoc[Adding New Modules] covers the whole process of adding a new module to Fedora. \ No newline at end of file +The xref:building-modules/fedora/adding-new-modules.adoc[Adding New Modules] covers the whole process of adding a new module to Fedora. + +The xref:building-modules/fedora/module-obsoletes.adoc[Module Obsoletes] covers the process of a module stream EOLing/obsoleting. diff --git a/modules/ROOT/pages/building-modules/fedora/module-obsoletes.adoc b/modules/ROOT/pages/building-modules/fedora/module-obsoletes.adoc new file mode 100644 index 0000000..86d8b77 --- /dev/null +++ b/modules/ROOT/pages/building-modules/fedora/module-obsoletes.adoc @@ -0,0 +1,107 @@ += Module Obsoletes +:toc: + +[.lead] +Module obsoletes allow for stream obsoleting another module or a stream being EOLed. + +The feature has been introduced in https://github.com/fedora-modularity/libmodulemd/releases/tag/2.10.0[libmodulemd-2.10.0]. + +== Module Obsoletes in the Pipeline (Quick Start) + +. Add obsoletes in the https://pagure.io/releng/fedora-module-defaults[module-defaults] repository. +. Configure pungi to use the obsoletes and create a modular compose using pungi. +. The obsoletes metadata will appear in the `modules.yaml` file of the resulting repodata. + +== Individual Steps + +=== Prepare module obsoletes metadata + +Follow the https://github.com/fedora-modularity/libmodulemd/blob/main/yaml_specs/[module obsoletes specification] for an up-to-date format. +As of the time of writing this article (January 2022), there's been v1 specification available and supported in the pipeline. + +Examples: + +. *EOLed stream nodejs:11 as of a specified date/time* ++ +[source,yaml] +---- +document: modulemd-obsoletes +version: 1 +data: + modified: 2018-05-23T14:25Z + module: nodejs + stream: "11" + # A string representing UTC date in ISO 8601 format: YYYY-MM-DDTHH:MMZ + # It is strongly recommended to keep HH:MM to 00:00. + # If not specified, the module is EOLed immediately. + # OPTIONAL + eol_date: 2020-03-19T00:00Z + message: "Module stream nodejs:11 is no longer supported." +---- + +. *Immediately obsoleted stream nodejs:11 with a new stream nodejs:12 available* ++ +[source,yaml] +---- +document: modulemd-obsoletes +version: 1 +data: + modified: 2018-05-23T14:25Z + module: nodejs + stream: "11" + message: "Module stream nodejs:11 is no longer supported. Please switch to nodejs:12" + obsoleted_by: + module: nodejs + stream: "12" +---- + +Theses are perhaps the most common scanarios, but check the specification for other workflows: + +- Resetting a previously EOLed/obsoleted stream. +- Obsoleting/EOLing a specific module stream context. + +=== Add the metadata into `fedora-module-defaults.git` repository + +. Clone the repository and *add the module obsoletes metadata* into the `obsoletes/` directory. ++ +Use `:.yaml` convention as each file can contain only a single module obsoletes +document for the subsequent processing to be successful. ++ +IMPORTANT: Make sure to commit your changes before going to the next step. + +. Execute `run_tests.sh` in the root of the repository to *validate the metadata locally*. ++ +First, testing metadata are checked to make sure your libmodulemd is able to handle +module obsoletes. Then the actual metadata in the `obsoletes/` directory are validated. + +. *After a successful validation*, file a https://pagure.io/releng/fedora-module-defaults/pull-requests[pull request] +for the module obsolete to be included in the repository. + +=== Configure pungi for module obsoletes and create a modular compose + +. Add the following snippet to pungi configuration. ++ +[source] +---- + # Optional module obsoletes configuration which is merged + # into the module index and gets resolved + module_obsoletes_dir = { + 'scm': 'git', + 'repo': 'https://pagure.io/releng/fedora-module-defaults.git', + 'branch': 'main', + 'dir': 'obsoletes' + } +---- + +. Follow https://docs.pagure.org/pungi[pungi docs] on how to create a modular compose. ++ +TIP: Check the https://docs.pagure.org/pungi/gathering.html#modular-compose[gathering phase of a modular compose] +and the corresponding configuration reference. + +=== Final repodata contain module obsoletes + +When the obsoletes metadata appear in the repodata (`modules.yaml` file), DNF is expected +to handle the information regarding obsoletes and react accordingly. + +NOTE: If in doubt, check https://github.com/rpm-software-management/ci-dnf-stack/blob/master/dnf-behave-tests/dnf/module/obsoletes.feature +for what's the expected behavior.