From b0f7889c3d5be192d57b32e3a87bc7a325f624ea Mon Sep 17 00:00:00 2001 From: Björn Persson Date: Jan 09 2025 17:33:12 +0000 Subject: Documented one-to-many replacement. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index e01f31b..279c6d7 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -3021,6 +3021,46 @@ Note however that the -devel subpackages of lib packages are pulled in as build dependencies using the package name, so adding the Provides is often appropriate there. +=== One-to-Many Replacement + +Sometimes a package is split into two or more packages +(either subpackages or separate source packages) +to make some components optional, +but users of the optional parts shall be able to upgrade +without losing the functionality. +Thus the new packages need to be pulled in +on upgrade from a version before the split. +If some are later removed, +they shall not be pulled in again on further upgrades. + +This is achieved by putting an `+Obsoletes:+` tag like above +in each of the packages that together replace the original package. +If the name of the original package still exists after the split, +that package needs to obsolete itself. +Even if an optional split-out package requires the original package, +the original package still must obsolete itself. +Otherwise the split-out package won't be pulled in. + +Example: Foo version 3 contains Bar as a non-essential component. +In version 4, Bar is moved to a subpackage. +Bar shall not disappear on upgrade. + +[source, rpm-spec] +---- +Name: foo +Version: 4 +Release: 1%{?dist} +Obsoletes: foo < 4 + +%package bar +Requires: foo%{?_isa} = %{version}-%{release} +Obsoletes: foo < 4 +---- + +NOTE: Packages pulled in this way are not marked as user-installed by DNF 4, +so `+dnf autoremove+` will remove them. +This appears to be fixed in DNF 5. + == Deprecating Packages A procedure exists for indicating that a package is deprecated