From cb6ea9b513368be1881f6a614fd076039cc6e3ba Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 28 2021 00:07:14 +0000 Subject: SemBr for Explicit Requires section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index c9be548..91c1a62 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -838,13 +838,51 @@ that might provide that directory. === Explicit Requires -Explicit Requires are Requires added manually by the packager in the spec file. Packages must not contain unnecessary explicit Requires on libraries. We generally rely on rpmbuild to automatically add dependencies on library SONAMEs. Modern package management tools are capable of resolving such dependencies to determine the required packages in many cases. However, present versions of rpmbuild only add deps on library SONAMES, not the library's full version. This can be a problem if a library has added features over the course of time without backwards incompatibilities that would cause SONAMES to be changed. This can lead to a case where the user has an old version of a library installed, the new version of the library with new ABI is built in Fedora and an application using that ABI is built. If the user just attempts to install or update that one application without also updating the library, the application will install fine (because the SONAME dependency is satisfied) but will fail when run because the library installed on the system is missing features it needs. - -Although you do need to add explicit library dependencies to keep this from occurring, there are drawbacks to manually specifying this in all your packages. History has shown that such dependencies add confusion when library/files are moved from one package to another, when packages get renamed, when one out of multiple alternative packages would suffice, and when versioned explicit dependencies become out-of-date and inaccurate. Additionally, in some cases, old explicit dependencies on package names require unnecessary updates/rebuilds. For example, Fedora packages are only required to retain historical provides for two full release cycles. +Explicit Requires are Requires added manually by the packager in the spec file. +Packages must not contain unnecessary explicit Requires on libraries. +We generally rely on rpmbuild to automatically add dependencies +on library SONAMEs. +Modern package management tools are capable of resolving such dependencies +to determine the required packages in many cases. +However, present versions of rpmbuild only add deps on library SONAMES, +not the library's full version. +This can be a problem if a library has added features over the course of time +without backwards incompatibilities that would cause SONAMES to be changed. +This can lead to a case where the user has an old version +of a library installed, +the new version of the library with new ABI is built in Fedora +and an application using that ABI is built. +If the user just attempts to install or update that one application +without also updating the library, +the application will install fine +(because the SONAME dependency is satisfied) +but will fail when run because the library installed +on the system is missing features it needs. + +Although you do need to add explicit library dependencies +to keep this from occurring, +there are drawbacks to manually specifying this in all your packages. +History has shown that such dependencies add confusion +when library/files are moved from one package to another, +when packages get renamed, +when one out of multiple alternative packages would suffice, +and when versioned explicit dependencies become out-of-date and inaccurate. +Additionally, in some cases, +old explicit dependencies on package names +require unnecessary updates/rebuilds. +For example, +Fedora packages are only required to retain historical provides +for two full release cycles. -Because of this and because we hope to have this fixed in rpmbuild, this is something to be aware of but it's not required that you explicitly specify the libraries you require with their version information. +Because of this and because we hope to have this fixed in rpmbuild, +this is something to be aware of +but it's not required that you explicitly specify the libraries you require +with their version information. -When explicit library Requires are necessary, explicit library dependencies should typically be arch-specific (unless the packages involved are noarch) and there should be a spec file comment justifying it: +When explicit library Requires are necessary, +explicit library dependencies should typically be arch-specific +(unless the packages involved are noarch) +and there should be a spec file comment justifying it: .... # The automatic dependency on libfubar.so.1 is insufficient, @@ -852,7 +890,11 @@ When explicit library Requires are necessary, explicit library dependencies shou Requires: libfubar%{?_isa} >= 0:1.2.3-7 .... -Packagers should revisit an explicit dependency as appropriate to avoid it becoming inaccurate and superfluous. For instance in the example above, when no current Fedora release shipped with libfubar < 1.2.3-7, it is no longer necessary to list the explicit, versioned requirement. +Packagers should revisit an explicit dependency +as appropriate to avoid it becoming inaccurate and superfluous. +For instance in the example above, +when no current Fedora release shipped with libfubar < 1.2.3-7, +it is no longer necessary to list the explicit, versioned requirement. === Filtering Auto-Generated Requires