From ed0d120dbb1f5cc930021280a1312d150d8ccd1a Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Oct 07 2021 17:22:19 +0000 Subject: [PATCH 1/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 ade71da..c26e749 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2041,7 +2041,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: https://docs.fedoraproject.org/en-US/package-maintainers/Package_Renaming_Process/[Package Renaming Process] should be followed when renaming an existing package. @@ -2165,7 +2165,7 @@ If the automatic checks and modifications break a package, there are two primary * The packager can elect to fix the shebang lines manually, using patches, scripting via sed, or other similar methods. * The packager can remove the executable permission from the script so that the checks and modifications are not made. -If (and only if) the script needs to remain executable and cannot be modified to pass the checks, then the maintainer MAY elect to disable the checks and modifications. It is also possible to disable the functionality for specific paths or for specific shebang lines by setting `+%__brp_mangle_shebangs_exclude_from+` and `+%__brp_mangle_shebangs_exclude+`, respectively, using the same syntax as the settings described in xref:AutoProvidesAndRequiresFiltering.adoc[Packaging:AutoProvidesAndRequiresFiltering]. It is also possible to disable the functionality entirely by adding `+%undefine __brp_mangle_shebangs+` near the beginning of the specfile. +If (and only if) the script needs to remain executable and cannot be modified to pass the checks, then the maintainer SHOULD elect to disable the checks and modifications. It is also possible to disable the functionality for specific paths or for specific shebang lines by setting `+%__brp_mangle_shebangs_exclude_from+` and `+%__brp_mangle_shebangs_exclude+`, respectively, using the same syntax as the settings described in xref:AutoProvidesAndRequiresFiltering.adoc[Packaging:AutoProvidesAndRequiresFiltering]. It is also possible to disable the functionality entirely by adding `+%undefine __brp_mangle_shebangs+` near the beginning of the specfile. == BRP (BuildRoot Policy) Scripts From c990e427b686175398bac09d98f1aa55607847be Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Oct 07 2021 17:38:16 +0000 Subject: [PATCH 2/2] Clean up Renaming/Replacing section a bit 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 c26e749..f9b465a 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2054,24 +2054,30 @@ 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. +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-1.0-3%\{?dist} with Epoch: 2. The following should be added to bar (and similarly for all subpackages as applicable): +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} .... -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. +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. -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:. +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 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.