From d5acff59aacf1f8386dc505fceecb048990a312c Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Oct 07 2021 09:18:45 +0000 Subject: [PATCH 1/2] Add a form of Obsoletes with a caret to simplify removal of old packages The requirement to use a specific version+release, but bumped, is something that is annoying (because we need to look up what releases have been built in various branches of Fedora), and something that people get wrong quite often. (E.g. https://src.fedoraproject.org/rpms/fedora-release/c/026814f9c79336538459b55c91104375df594556 is one random example that I saw this morning and which pushed me to write this patch.) With a caret we can skip this complicated logic. In the new scheme, the last version v suffixed with "^" is used. The release part is ignored. v^ sorts higher than all releases like v-1, v-33.f34, etc. If the package is unretired, if the unretired version is higher, then things just work. If the unretired version is unchanged, than the new package would have to get a fake version bump like v^. (For example we had hello-5.1.1-11.fc34 as the last version built, it gets retired, we have 'Obsoletes:hello < 5.1.1^'. If it is unretired, the version could be either hello-5.1.2-1.fc35, or hello-5.1.1^-1.fc35.) Since the scenario of unretirement with the exact same version is fairly unlikely, I think this solution is acceptable. I downloaded the git-seed-latest repo and went over retirement+unretirment cases. It turns out that we resurrect packages with the same version quite often, much more often than I expected. Thus the simplified form can only be used in some specific cases. But when it is applicable, it is quite nice, so advertise it as an option. While at it, I moved the discussion of Epoch higher, because it relevant to for $provEVR, and simplified the text a bit. `<=` doesn't work as expected, because it's defeated by the `%{dist}` suffix. Use `<`. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index c8c2bef..8f8de4b 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1710,24 +1710,42 @@ Provides: oldpackagename = $provEVR Obsoletes: oldpackagename < $obsEVR .... -$provEVR refers to an (Epoch-)Version-Release tuple the original unchanged package would have had if it had been version or release bumped. You usually use macros here because the provides EVR should continue to go up as the renamed package advances in version and release. $obsEVR is an (Epoch-)Version-Release tuple arranged so that there is a clean upgrade path but without gratuitously polluting the version space upwards. You usually do not use macros for this as you're simply trying to advance beyond the last known release under the old name. +`+$provEVR+` uses the version of the providing package (and continues to go up over time). +Usually it is just `+%{version}-%{release}+`. +You usually use macros here because the version and release should continue to go up as the renamed package advances. -If a package supersedes/replaces an existing package without being a sufficiently compatible replacement as defined above, use only the `+Obsoletes:+` line from the above example. +`+$obsEVR+` is an (Epoch-)Version-Release arranged so that there is a clean upgrade path but without gratuitously polluting the version space upwards. +You usually do not use macros for this as you're simply trying to advance beyond the last known release under the old name. +When deciding what $obsEVR should be, remember that it needs to be higher than the previous `Release` with `+%{?dist}+` expanded. -CAUTION: *Take `+%{?dist}+` into account*: When deciding what $obsEVR should be, remember that it needs to be higher than the previous `Release:` with `+%{?dist}+` expanded. Example: if the package previously had `+Release: 4%{?dist}+` the release in $obsEVR should be at least 5. +Example: if the package previously had `+Release: 4%{?dist}+` the release in `$obsEVR` should be at least 5. -If retired packages need to be removed from end user machines because they cause dependency issues which interfere with upgrades or are otherwise harmful, a packager MAY request that `+Obsoletes:+` be added to `+fedora-obsolete-packages+`. Simply file a bugzilla ticket https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&version=rawhide&component=fedora-obsolete-packages[here]. Please include information on which packages need to be obsoleted, the exact versions which need to be obsoleted, and the reasons why they cannot be allowed to remain installed. +A simplified form of `+$obsEVR+` may be used when it is expected that the unretired package will have a higher version. +(The typical case is when the last built version is already behind upstream at the time when the Obsoletes is added, +so it clear that even it package is brought back, it will be with a higher version.) +In this case, the release marker is replaced by `+^+`. -If the obsoleted package had an Epoch set, it must be preserved in both the `+Provides:+` and `+Obsoletes:+`. For example, assume foo being renamed to bar, bar is compatible with foo, and the last foo package release being foo-1.0-3%\{?dist} with Epoch: 2. The following should be added to bar (and similarly for all subpackages as applicable): +If a package supersedes/replaces an existing package without being a sufficiently compatible replacement as defined above, use only the `+Obsoletes:+` line. + +If the obsoleted package had an Epoch set, it must be preserved in both the `+Provides:+` and `+Obsoletes:+`. For example, assume `foo` being renamed to `bar`, `bar` is compatible with `foo`, and the last `foo` package release being `+foo-2:1.0-3.fc25+` (the epoch is "2"). The following should be added to `bar` (and similarly for all subpackages as applicable): .... Provides: foo = 2:%{version}-%{release} -Obsoletes: foo <= 2:1.0-4 # Important: We set the Obsoletes release to 4 to be higher than the previous Release: 3%{?dist} +Obsoletes: foo < 2:1.0-4 # Important: We set the Obsoletes release to 4 to be higher than the previous Release: 3%{?dist} +.... + +In the simplified form of `+$obsEVR+` this would become .... +Provides: foo = 2:%{version}-%{release} +Obsoletes: foo < 2:1.0^ # This obsoletes versions like 2:0.9-1.fc35 or 2:1.0-35.eln100, but not 2:1.0.0-1.fc35 or 2:1.0.1-1.fc35. +.... + + +Explicit `+Provides:+` need to be aware of whether the package is supplying things that can be used in an arch-independent or arch-specific fashion. For packages that are not noarch, `+Provides:+` should be made arch-specific by applying the `+%{?_isa}+` macro to the end of the string in Provides (e.g. `+Provides: foo%{?_isa} = 2:%{version}-%{release}+`). Packages that explicitly provide things that can be used in an arch-independent way (for example, those whose dependents don't need to be of the same arch—need not apply this macro. In some cases, a package will supply multiple elements, some of which may be consumed only by dependents of an identical arch and some which may be consumed by dependents of any arch. In such cases, both arch-specific and arch-independent `+Provides:+` are warranted. -Explicit `+Provides:+` need to be aware of whether the package is supplying things that can be used in an arch-independent or arch-specific fashion. For packages that are not noarch, `+Provides:+` should be made arch-specific by applying the `+%{?_isa}+` macro to the end of the text string in Provides (e.g. `+Provides: foo%{?_isa} = 2:%{version}-%{release}+`). Packages that explicitly provide things that can be used in an arch-independent way (for example, those whose dependents don't need to be of the same arch—need not apply this macro. In some cases, a package will supply multiple elements, some of which may be consumed only by dependents of an identical arch and some which may be consumed by dependents of any arch. In such cases, both arch-specific and arch-independent Provides: are warranted. +Examples of packages that should explicitly provide only arch-specific `+Provides:+` include native code libraries or plug-ins and their associated -devel packages. Packages that should explicitly provide only arch-independent `+Provides:+` include most standalone programs (in addition to all noarch packages). Even though these programs may themselves be arch-specific, clients that run them should not care about their arch. A package that explicitly provides, for example, both a native code library as well as an interpreted language interface to that library should have both arch-specific (for clients of the native code library) and arch-independent (for clients of the interpreted language interface) `+Provides:+`. -Examples of packages that should explicitly provide only arch-specific `+Provides:+` include native code libraries or plug-ins and their associated -devel packages. Packages that should explicitly provide only arch-independent `+Provides:+` include most stand-alone programs (in addition to all noarch packages). Even though these programs may themselves be arch-specific, clients that run them should not care about their arch in most cases. A package that explicitly provides, for example, both a native code library as well as an interpreted language interface to that library should have both arch-specific (for clients of the native code library) and arch-independent (for clients of the interpreted language interface) Provides:. +If retired packages need to be removed from end user machines because they cause dependency issues which interfere with upgrades or are otherwise harmful, a packager MAY request that `+Obsoletes:+` be added to `+fedora-obsolete-packages+`. Simply file a bugzilla ticket https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&version=rawhide&component=fedora-obsolete-packages[here]. Please include information on which packages need to be obsoleted, the versions which need to be obsoleted, and the reasons why they cannot be allowed to remain installed. If there is no standard naming for a package or other long term naming compatibility requirements involved with the rename, the Provides should be assumed to be deprecated and short lived and removed in the distro release after the next one (i.e., if introduced in FC-X, keep in all subsequent package revisions for distros FC-X and FC-(X+1), drop in FC-(X+2)), and the distro version where it is planned to be dropped documented in a comment in the specfile. Maintainers of affected packages should be notified and encouraged to switch to use the new name. Forward compatibility Provides: in older distro branches can be considered in order to make it possible for package maintainers to keep same simple specfiles between branches but still switch to the newer name. From 6a2bc937d707e57e9dcf185a00ec98c457b99264 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Oct 07 2021 09:23:40 +0000 Subject: [PATCH 2/2] Change MAY to SHOULD for fedora-obsolete-packages inclusion The logic that we use in Fedora has changed: in the past we were perfectly happy with users having to do various magical incantations during upgrades. Nowadays we expect upgrades to go smoothly. If a package causes a "dependency issues which interfere[s] with upgrades or [is] otherwise harmful" we expect the package to be removed, period. Thus, the recommendation is changed to SHOULD. (I would go for "MUST", because *somebody* will have to do this, it's not clear *who*. Sometimes it'll be the person retiring the package, but most often it'll just be somebody who notices that the upgrade path is broken. Those events are often separated in time. Also, we can't/don't want to block package retirement. So it's "a packager SHOULD", not "the package MUST".) Also change the section title, because people might be looking how to obsolete a package, but the title suggested that the section is about renames only. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 8f8de4b..692bc48 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1697,7 +1697,7 @@ These have the effect of making the appropriate changes immediately upon package There are specific guidelines for handling tmpfiles.d configurations and directories (in /run and /run/lock): xref:Tmpfiles.d.adoc[Tmpfiles.d]. [#renaming-or-replacing-existing-packages] -== Renaming/Replacing Existing Packages +== Renaming/Replacing or Removing Existing Packages NOTE: FESCo has a https://fedoraproject.org/wiki/Package_Renaming_Process#Re-review_required[package renaming policy] that should be followed when renaming an existing package. @@ -1745,7 +1745,7 @@ Explicit `+Provides:+` need to be aware of whether the package is supplying thin Examples of packages that should explicitly provide only arch-specific `+Provides:+` include native code libraries or plug-ins and their associated -devel packages. Packages that should explicitly provide only arch-independent `+Provides:+` include most standalone programs (in addition to all noarch packages). Even though these programs may themselves be arch-specific, clients that run them should not care about their arch. A package that explicitly provides, for example, both a native code library as well as an interpreted language interface to that library should have both arch-specific (for clients of the native code library) and arch-independent (for clients of the interpreted language interface) `+Provides:+`. -If retired packages need to be removed from end user machines because they cause dependency issues which interfere with upgrades or are otherwise harmful, a packager MAY request that `+Obsoletes:+` be added to `+fedora-obsolete-packages+`. Simply file a bugzilla ticket https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&version=rawhide&component=fedora-obsolete-packages[here]. Please include information on which packages need to be obsoleted, the versions which need to be obsoleted, and the reasons why they cannot be allowed to remain installed. +If retired packages need to be removed from end user machines because they cause dependency issues which interfere with upgrades or are otherwise harmful, a packager SHOULD request that `+Obsoletes:+` be added to `+fedora-obsolete-packages+`. Simply file a bugzilla ticket https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&version=rawhide&component=fedora-obsolete-packages[here]. Please include information which packages need to be obsoleted, the versions which need to be obsoleted, and the reasons why they cannot be allowed to remain installed. If there is no standard naming for a package or other long term naming compatibility requirements involved with the rename, the Provides should be assumed to be deprecated and short lived and removed in the distro release after the next one (i.e., if introduced in FC-X, keep in all subsequent package revisions for distros FC-X and FC-(X+1), drop in FC-(X+2)), and the distro version where it is planned to be dropped documented in a comment in the specfile. Maintainers of affected packages should be notified and encouraged to switch to use the new name. Forward compatibility Provides: in older distro branches can be considered in order to make it possible for package maintainers to keep same simple specfiles between branches but still switch to the newer name.