From 9a4c6436ed4f923c43a9ee44bfcec0bc4bd296ba Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 1/38] SemBr for Applicability section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 7c75854..f841d43 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -48,9 +48,27 @@ toc::[] == Applicability -In general, these guidelines apply to the currently released, non-end-of-life versions of Fedora, as well as the development version of Fedora (Rawhide). If a particular portion of these guidelines is relevant only to a subset of those releases, this will be specifically noted. However, please note that Rawhide can change rapidly, and there will be times when changes are visible there which are not yet reflected here. - -The guidelines also to some degree cover packages for EPEL, but only when combined with the https://fedoraproject.org/wiki/EPEL:Packaging[EPEL packaging guidelines]. Fedora packaging changes far more rapidly than EPEL packaging, so over time these guidelines will drift further away from any particular EPEL release and for the older supported EPEL release the differences can be quite significant. Portions of these guidelines which do not apply to EPEL will not generally be indicated. +In general, +these guidelines apply to the currently released, +non-end-of-life versions of Fedora, +as well as the development version of Fedora (Rawhide). +If a particular portion of these guidelines is relevant +only to a subset of those releases, +this will be specifically noted. +However, please note that Rawhide can change rapidly, +and there will be times when changes are visible there +which are not yet reflected here. + +The guidelines also to some degree cover packages for EPEL, +but only when combined with the +https://fedoraproject.org/wiki/EPEL:Packaging[EPEL packaging guidelines]. +Fedora packaging changes far more rapidly than EPEL packaging, +so over time these guidelines will drift further away +from any particular EPEL release +and for the older supported EPEL release +the differences can be quite significant. +Portions of these guidelines which do not apply to EPEL +will not generally be indicated. == General Exception Policy From 2de3e29abe7d4df6a94e315ce6c69bf6a93e1875 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 2/38] SemBr for General Exception Policy section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index f841d43..89dcb53 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -72,11 +72,25 @@ will not generally be indicated. == General Exception Policy -As these guidelines can never cover all possible contingencies, there will always be packages which need exceptions. It is the packager's responsibility to follow these guidelines as closely as is feasible and to clearly document, as comments in the package specfile, instances where they cannot be followed. - -If, in a guideline, the language "should" or "is suggested" is used and it is not feasible for the package to conform to that guideline, the packager may deviate from the it. The nature of the deviation and the reasoning behind it MUST be documented in the specfile. - -Where the language "must", "is required to" or "needs to" is used, the packager may deviate from the guideline only with approval from the packaging committee. Please follow the procedure at the https://fedoraproject.org/wiki/Packaging_Committee#Bringing_Issues_to_the_Committee[Packaging Committee] page for making these requests. +As these guidelines can never cover all possible contingencies, +there will always be packages which need exceptions. +It is the packager's responsibility to follow these guidelines +as closely as is feasible and to clearly document, +as comments in the package specfile, +instances where they cannot be followed. + +If, in a guideline, the language "should" or "is suggested" is used +and it is not feasible for the package to conform to that guideline, +the packager may deviate from the it. +The nature of the deviation and the reasoning behind it +MUST be documented in the specfile. + +Where the language "must", "is required to" or "needs to" is used, +the packager may deviate from the guideline +only with approval from the packaging committee. +Please follow the procedure at the +https://fedoraproject.org/wiki/Packaging_Committee#Bringing_Issues_to_the_Committee[Packaging Committee] +page for making these requests. == Allowed Packages From c14688f48260643b563b615d554c782d5d4cb861 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 3/38] SemBr for Allowed Packages section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 89dcb53..cab336b 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -94,7 +94,9 @@ page for making these requests. == Allowed Packages -Please review xref:what-can-be-packaged.adoc[What Can Be Packaged] to ensure that what is to be packaged is allowed in Fedora. +Please review +xref:what-can-be-packaged.adoc[What Can Be Packaged] +to ensure that what is to be packaged is allowed in Fedora. == Naming From c75a1999fd4d561b6249e3fa325ec7a093a08226 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 4/38] SemBr for Naming section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index cab336b..6c38a80 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -100,7 +100,9 @@ to ensure that what is to be packaged is allowed in Fedora. == Naming -You should go through the xref:Naming.adoc[Naming Guidelines] to ensure that your package is named appropriately. +You should go through the +xref:Naming.adoc[Naming Guidelines] +to ensure that your package is named appropriately. == Version and Release From 19a2c8c04ffa6f284daa277571033ffc8df86155 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 5/38] SemBr for Version and Release section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 6c38a80..3eb036c 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -106,7 +106,8 @@ to ensure that your package is named appropriately. == Version and Release -Documentation covering the proper way to use the Version and Release fields can be found xref:Versioning.adoc[here]. +Documentation covering the proper way to use the Version and Release fields +can be found xref:Versioning.adoc[here]. == Licensing From fa069e849be56f1257af3c7df79023ed8dc57c7a Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 6/38] SemBr for Licensing section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 3eb036c..d16cd21 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -111,7 +111,11 @@ can be found xref:Versioning.adoc[here]. == Licensing -You should review https://fedoraproject.org/wiki/Licensing:Main and the xref:LicensingGuidelines.adoc[Licensing Guidelines] to ensure that your package is licensed appropriately and that the license is properly indicated. +You should review +https://fedoraproject.org/wiki/Licensing:Main +and the xref:LicensingGuidelines.adoc[Licensing Guidelines] +to ensure that your package is licensed appropriately +and that the license is properly indicated. === Fedora trademarks From 84b67b1cf65237d59ee5c34f048fd5b16f5215bb Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 7/38] SemBr for Fedora trademarks section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index d16cd21..7187220 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -119,14 +119,26 @@ and that the license is properly indicated. === Fedora trademarks -Packagers *MUST NOT* add any Fedora trademark assets including the Fedora logo, Fedora logo icons, or graphics that include the Fedora logo. +Packagers *MUST NOT* add any Fedora trademark assets +including the Fedora logo, +Fedora logo icons, +or graphics that include the Fedora logo. Those assets *MUST* be added to the fedora-logos package. Your packages(s) install the logos by depending on the fedora-logos package. -If the upstream contains Fedora trademark assets that you believe are used inappropriately, email legal@fedoraproject.org +If the upstream contains Fedora trademark assets +that you believe are used inappropriately, +email legal@fedoraproject.org -This is because the Fedora logo is a trademark, which are handled under a different legal framework than code. +This is because the Fedora logo is a trademark, +which are handled under a different legal framework than code. It must only be distributed under terms that protect the trademark. -Keeping Fedora trademarks separate in their own package instead of scattered across various other packages is also an essential practice for enabling remixes that necessarily must https://fedoraproject.org/wiki/Legal:Trademark_guidelines#Secondary_Mark[not use the Fedora trademark], and instead roll their own *-logos package or use the generic-logos package. +Keeping Fedora trademarks separate in their own package +instead of scattered across various other packages +is also an essential practice for enabling remixes +that necessarily must +https://fedoraproject.org/wiki/Legal:Trademark_guidelines#Secondary_Mark[not use the Fedora trademark], +and instead roll their own *-logos package +or use the generic-logos package. == Libraries and Applications From 9a21818a09265d338d5db318ee0f2cc816c1ad93 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 8/38] SemBr for Library of Application section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 7187220..7f14eb0 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -150,13 +150,22 @@ may include applications, so the distinction is not always clear. === Library or Application? -* If the primary purpose of a package is to provide executables to be run by users, it SHOULD be packaged as an application. If it also includes libraries which may be imported or linked to by other code, see <> below. -* If the primary purpose of a package is to provide libraries intended to be imported or loaded into other code, it is considered a library and MUST be packaged as such. If it contains utility programs that can be run by users as well, see <> below. - -It is left to the packager to determine the primary purpose of a -package. Often times upstream will already have done this with their -choice of naming and that choice SHOULD be followed by the Fedora -packager. +* If the primary purpose of a package +is to provide executables to be run by users, +it SHOULD be packaged as an application. +If it also includes libraries which may be imported +or linked to by other code, +see <> below. +* If the primary purpose of a package +is to provide libraries intended to be imported or loaded into other code, +it is considered a library and MUST be packaged as such. +If it contains utility programs that can be run by users as well, +see <> below. + +It is left to the packager to determine the primary purpose of a package. +Often times upstream will already have done this +with their choice of naming +and that choice SHOULD be followed by the Fedora packager. === Mixed Use Packages From f45e8958d227ae4185a63e59dcb26dfeabdfc345 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 9/38] SemBr for Mixed Use Packages section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 7f14eb0..66e1fcf 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -169,12 +169,14 @@ and that choice SHOULD be followed by the Fedora packager. === Mixed Use Packages -Many packages, regardless of their primary purpose, include both -applications and libraries. In this case one or both SHOULD -be packaged in subpackages in order to allow other applications to depend -on only the library and not the associated application(s). Installing an -application that depends on a library or service should not automatically -pull in other applications associated with that library or service. +Many packages, regardless of their primary purpose, +include both applications and libraries. +In this case one or both SHOULD be packaged in subpackages +in order to allow other applications to depend on only the library +and not the associated application(s). +Installing an application that depends on a library or service +should not automatically pull in other applications +associated with that library or service. == Package Independence From 6d16b1a70a9f4c6c0baf795b85e4563e0e3984a9 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 10/38] SemBr for Package Independence section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 66e1fcf..a94ea90 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -184,20 +184,27 @@ Packages SHOULD be installable independently whenever this is technically feasib but they MUST specify dependencies of correct type on other packages if necessary, see <> below. -Desktop applications MUST NOT depend on other desktop applications unless strictly required. -In particular, packages that contain a visible `.desktop` file (a `.desktop` file that does not contain the line -`+NoDisplay=true+`) SHOULD NOT have a `Requires`, `Recommends`, or `Supplements` -on any other package containing a visible desktop file, directly or indirectly. - -For example, it would be reasonable for a video game level editor to -require the associated video game in order to function, or for an application's plugin to -require the associated application. But it would not be reasonable for an application that happens -to use a database library to depend on a database management suite associated -with that library, or for an application that happens to use a particular programming language +Desktop applications MUST NOT depend on other desktop applications +unless strictly required. +In particular, packages that contain a visible `.desktop` file +(a `.desktop` file that does not contain the line `+NoDisplay=true+`) +SHOULD NOT have a `Requires`, +`Recommends`, +or `Supplements` +on any other package containing a visible desktop file, +directly or indirectly. + +For example, it would be reasonable for a video game level editor +to require the associated video game in order to function, +or for an application's plugin to require the associated application. +But it would not be reasonable for an application +that happens to use a database library +to depend on a database management suite associated with that library, +or for an application that happens to use a particular programming language to depend on management tools associated with that programming language. -If a source package provides multiple graphical applications, those -applications SHOULD be packaged in separate subpackages when feasible. +If a source package provides multiple graphical applications, +those applications SHOULD be packaged in separate subpackages when feasible. == Spec Files From ef0c7907d10a736df4076a75482bfbc5cb88693c Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 11/38] SemBr for Spec Files section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index a94ea90..bc90313 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -208,7 +208,13 @@ those applications SHOULD be packaged in separate subpackages when feasible. == Spec Files -The spec file ("spec") is a fundamental element in the packaging workflow. Any change that is made to the package will include a change to the spec. Because packages in Fedora are maintained by a community of packagers as well as automated tooling, it is important for the specs to follow certain conventions. The bulk of these packaging guidelines involves what goes into a spec, but here are a few general items. +The spec file ("spec") is a fundamental element in the packaging workflow. +Any change that is made to the package will include a change to the spec. +Because packages in Fedora are maintained by a community of packagers +as well as automated tooling, +it is important for the specs to follow certain conventions. +The bulk of these packaging guidelines involves what goes into a spec, +but here are a few general items. === Spec File Naming From bbc781702fbfce90a2c88afac4a82513e400a380 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 12/38] SemBr for Spec File Naming section. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index bc90313..5d58db1 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -218,7 +218,9 @@ but here are a few general items. === Spec File Naming -The spec file MUST be named `+%{name}.spec+`. That is, if your package is named `+example+`, the spec file must be named `+example.spec+`. +The spec file MUST be named `+%{name}.spec+`. +That is, if your package is named `+example+`, +the spec file must be named `+example.spec+`. === Spec Legibility From 8f62c07bb087171f726a7f864657c1f94139ba3b Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 13/38] SemBr for Spec Legibility section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 5d58db1..c9d542d 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -224,9 +224,16 @@ the spec file must be named `+example.spec+`. === Spec Legibility -All spec files MUST be legible and maintained in such a way that the community of packagers is able to understand and work with them. - -To help facilitate legibility, only macros and conditionals for Fedora and EPEL are allowed to be used in Fedora Packages. Use of macros and conditionals for other distributions, including Fedora derivatives, is not permitted in spec files of packages in the main Fedora repositories unless those macros and conditionals are also present in Fedora. +All spec files MUST be legible and maintained in such a way +that the community of packagers is able to understand and work with them. + +To help facilitate legibility, +only macros and conditionals for Fedora and EPEL +are allowed to be used in Fedora Packages. +Use of macros and conditionals for other distributions, +including Fedora derivatives, +is not permitted in spec files of packages in the main Fedora repositories +unless those macros and conditionals are also present in Fedora. === Spec file Encoding From 33ed696574728f724afbfedc9570e094088a07ac Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 14/38] SemBr for Spec file Encoding section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index c9d542d..0f9d018 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -237,7 +237,14 @@ unless those macros and conditionals are also present in Fedora. === Spec file Encoding -Unless you need to use characters outside the https://commons.wikimedia.org/wiki/File:Ascii_full.png[ASCII repertoire], you will not need to be concerned about the encoding of the spec file. If you do need non-ASCII characters, save your spec files as UTF-8. If you're in doubt as to what characters are ASCII, please refer to https://commons.wikimedia.org/wiki/File:Ascii_full.png[this chart]. +Unless you need to use characters outside the +https://commons.wikimedia.org/wiki/File:Ascii_full.png[ASCII repertoire], +you will not need to be concerned about the encoding of the spec file. +If you do need non-ASCII characters, +save your spec files as UTF-8. +If you're in doubt as to what characters are ASCII, +please refer to +https://commons.wikimedia.org/wiki/File:Ascii_full.png[this chart]. ==== Non-ASCII Filenames From f676834bc53a486f5bb69827a9041cf41534f031 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 15/38] SemBr for Non-ASCII Filenames section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 0f9d018..877f4fa 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -248,7 +248,15 @@ https://commons.wikimedia.org/wiki/File:Ascii_full.png[this chart]. ==== Non-ASCII Filenames -Similarly, filenames that contain non-ASCII characters must be encoded as UTF-8. Since there's no way to note which encoding the filename is in, using the same encoding for all filenames is the best way to ensure users can read the filenames properly. If upstream ships filenames that are not encoded in UTF-8 you can use a utility like convmv (from the convmv package) to convert the filename in your %install section. +Similarly, filenames that contain non-ASCII characters +must be encoded as UTF-8. +Since there's no way to note which encoding the filename is in, +using the same encoding for all filenames is the best way +to ensure users can read the filenames properly. +If upstream ships filenames that are not encoded in UTF-8 +you can use a utility like convmv +(from the convmv package) +to convert the filename in your %install section. === Spec Maintenance and Canonicity From 588a076802accd7ff3ff4b7e6e89b45c11117835 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 16/38] SemBr for Spec Maintenance and Canonicity section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 877f4fa..29c381c 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -260,7 +260,18 @@ to convert the filename in your %install section. === Spec Maintenance and Canonicity -Fedora's git repository is the canonical location for Fedora spec files. Maintainers MUST expect that other maintainers and automated tooling will make changes to their packages, potentially without communicating prior to doing so (though communication is always encouraged). If some maintainers are also attempting to keep copies of a spec in an outside repository, they MUST be prepared to merge changes made to the spec in Fedora's repository, and MUST NOT overwrite those changes with a copy from an external repository or using `+fedpkg import+`. +Fedora's git repository is the canonical location for Fedora spec files. +Maintainers MUST expect that other maintainers +and automated tooling will make changes to their packages, +potentially without communicating prior to doing so +(though communication is always encouraged). +If some maintainers are also attempting +to keep copies of a spec in an outside repository, +they MUST be prepared to merge changes made to the spec +in Fedora's repository, +and MUST NOT overwrite those changes +with a copy from an external repository +or using `+fedpkg import+`. == Source File Verification From 62c32d81c376e9e0dc14d784158a68d3bbed101e Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:30 +0000 Subject: [PATCH 17/38] SemBr for Source File Verification section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 29c381c..896d059 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -278,10 +278,14 @@ or using `+fedpkg import+`. Where the upstream project publishes OpenPGP signatures of their releases, Fedora packages *SHOULD* verify that signature as part of the RPM build process. -Although a checksum in the sources file certifies that a file retreived from the lookaside cache is the one that the packager uploaded, +Although a checksum in the sources file certifies +that a file retreived from the lookaside cache +is the one that the packager uploaded, it is silent on whether the file is what the upstream project released. -A signature by the upstream developers certifies that the source is identical to what they released. -Verifying the signature as part of the build ensures that packagers don't forget to verify it. +A signature by the upstream developers certifies +that the source is identical to what they released. +Verifying the signature as part of the build ensures +that packagers don't forget to verify it. === Obtaining the Correct Keys From 361228ee9ab04ffcc7a7295ef4043a389b0cf1f4 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:31 +0000 Subject: [PATCH 18/38] SemBr for Obtaining the Correct Keys section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 896d059..b1760b8 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -291,7 +291,8 @@ that packagers don't forget to verify it. The verification method requires an OpenPGP keyring file with one or more public keys from the upstream project. -The keyring shall contain all the keys that are trusted to certify the authenticity of the sources, +The keyring shall contain all the keys that are trusted +to certify the authenticity of the sources, and *MUST NOT* contain any other keys. Ideally the upstream project publishes such a keyring as a downloadable file. @@ -300,12 +301,15 @@ and do everything you reasonably can to verify that it is authentic. Then you shall add it unmodified to the package SCM, and provide its URL in the spec file so that others can verify it. -The URL *MUST* use HTTPS or a similarly authenticated protocol if at all possible. +The URL *MUST* use HTTPS +or a similarly authenticated protocol if at all possible. Even if you are unable to verify the key at the first addition, it still enhances security in a trust-on-first-use way. -It will ensure that future attacks will be detected if the key is the right one, -or that a current attack will be detected later if future releases are signed by the correct key. +It will ensure that future attacks will be detected +if the key is the right one, +or that a current attack will be detected later +if future releases are signed by the correct key. === Verifying Signatures From c63b490ecfe30f4f5036d45d83850855e399065f Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:31 +0000 Subject: [PATCH 19/38] SemBr for Verifying Signatures section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index b1760b8..c1ee873 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -318,7 +318,8 @@ it *MUST* be done first in the `%prep` section of the spec file, before any potentially compromised code is executed. The verification *MUST* be done with the macro `+%{gpgverify}+`, which expands into a command -whose parameters shall be the pathnames of the keyring, the signature and the signed file. +whose parameters shall be the pathnames of the keyring, +the signature and the signed file. `BuildRequires: gnupg2` is necessary for the verification to work. Any detached signature file From b37666de4dd37cce641236cf9a7db17f6eb3087b Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:31 +0000 Subject: [PATCH 20/38] SemBr for Source File Verification/Exceptions section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index c1ee873..33261ec 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -348,24 +348,31 @@ and the third one is the keyring. If the upstream tarball of a package needs to be modified, for example because it contains forbidden items, then the tarball cannot be verified as part of the build process. -In this case the upstream OpenPGP keyring must still be included in the package SCM -and the instructions/script used to build the stripped-down tarball needs to verify the upstream source. +In this case +the upstream OpenPGP keyring must still be included in the package SCM +and the instructions/script used to build the stripped-down tarball +needs to verify the upstream source. If the upstream project does not publish a keyring file (for example if they publish only a fingerprint on their website and refer to a keyserver network for downloading the key), then you may need to create a keyring after you have verified the key. In this case there is no upstream URL to the keyring, -so instead you should document how you created the keyring in a comment in the spec file. -A minimal keyring with the key with the fingerprint `7D33D762FD6C35130481347FDB4B54CBA4826A18` can be created with the following command: +so instead you should document how you created the keyring +in a comment in the spec file. +A minimal keyring with the key with the fingerprint +`7D33D762FD6C35130481347FDB4B54CBA4826A18` +can be created with the following command: .... gpg2 --export --export-options export-minimal 7D33D762FD6C35130481347FDB4B54CBA4826A18 > gpgkey-7D33D762FD6C35130481347FDB4B54CBA4826A18.gpg .... If upstream signed a tarball differently, -for example by signing only the uncompressed tarball but distributing a compressed version, -then the verification step must be adjusted accordingly, for example: +for example by signing only the uncompressed tarball +but distributing a compressed version, +then the verification step must be adjusted accordingly, +for example: .... Source0: ftp://ftp.example.com/pub/foo/%{name}-%{version}.tar.xz @@ -379,7 +386,8 @@ xzcat '%{SOURCE0}' | %{gpgverify} --keyring='%{SOURCE2}' --signature='%{SOURCE1} .... Packages that are vital during bootstrapping of Fedora -may use a <> to skip the verification before GnuPG has been built. +may use a <> +to skip the verification before GnuPG has been built. === Help From bca43878a506ffa86fb9df60eb27cfc74feae16b Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:31 +0000 Subject: [PATCH 21/38] SemBr for Source File Verification/Help section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 33261ec..7396484 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -393,7 +393,8 @@ to skip the verification before GnuPG has been built. If you need help getting your package compliant to this guideline, or if you do not know what to do if a build fails on a signature verification, -then you should seek help on the Fedora devel mailing list before circumventing the check, +then you should seek help on the Fedora devel mailing list +before circumventing the check, to make sure that you do not build compromised software. == Architecture Support From b28413214a6fe59d15201c85ec18a86a10422b02 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:31 +0000 Subject: [PATCH 22/38] SemBr for Architecture Support section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 7396484..a29d51c 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -399,9 +399,16 @@ to make sure that you do not build compromised software. == Architecture Support -All Fedora packages must successfully compile and build into binary rpms on at least one supported primary architecture, except where the package is useful only on a secondary architecture (such as an architecture-specific boot utility, microcode loader, or hardware configuration tool). Fedora packagers should make every effort to support all https://fedoraproject.org/wiki/Architectures#Primary_Architectures[primary architectures]. - -Content, code which does not need to compile or build, and architecture independent code (noarch) are notable exceptions. +All Fedora packages must successfully compile and build +into binary rpms on at least one supported primary architecture, +except where the package is useful only on a secondary architecture +(such as an architecture-specific boot utility, microcode loader, +or hardware configuration tool). +Fedora packagers should make every effort to support all +https://fedoraproject.org/wiki/Architectures#Primary_Architectures[primary architectures]. + +Content, code which does not need to compile or build, +and architecture independent code (noarch) are notable exceptions. === Architecture Build Failures From 7fba7ae747146ad167cc1fcd5c920a5429d29ae5 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 19:57:31 +0000 Subject: [PATCH 23/38] SemBr for Architecture Build Failures --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index a29d51c..3e2f3af 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -412,7 +412,21 @@ and architecture independent code (noarch) are notable exceptions. === Architecture Build Failures -If a Fedora package does not successfully compile, build or work on an architecture, then those architectures should be listed in the spec in `+ExcludeArch+`. Each architecture listed in `+ExcludeArch+` needs to have a bug filed in bugzilla, describing the reason that the package does not compile/build/work on that architecture. The bug number should then be placed in a comment, next to the corresponding `+ExcludeArch+` line. New packages will not have bugzilla entries during the review process, so they should put this description in the comment until the package is approved, then file the bugzilla entry, and replace the long explanation with the bug number. The bug should be marked as blocking one (or more) of the following bugs to simplify tracking such issues: +If a Fedora package does not successfully compile, build or work on an architecture, +then those architectures should be listed in the spec in `+ExcludeArch+`. +Each architecture listed in `+ExcludeArch+` +needs to have a bug filed in bugzilla, +describing the reason that the package does not +compile/build/work on that architecture. +The bug number should then be placed in a comment, +next to the corresponding `+ExcludeArch+` line. +New packages will not have bugzilla entries during the review process, +so they should put this description in the comment +until the package is approved, +then file the bugzilla entry, +and replace the long explanation with the bug number. +The bug should be marked as blocking one (or more) +of the following bugs to simplify tracking such issues: * https://bugzilla.redhat.com/show_bug.cgi?id=F-ExcludeArch-x86[F-ExcludeArch-x86] * https://bugzilla.redhat.com/show_bug.cgi?id=F-ExcludeArch-x64[F-ExcludeArch-x64] From bf64ba748873d828974bd78e1cbcde4e56f88ffd Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 21:21:23 +0000 Subject: [PATCH 24/38] SemBr for Noarch with Unported Dependencies section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 3e2f3af..68c3d40 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -437,7 +437,16 @@ of the following bugs to simplify tracking such issues: === Noarch with Unported Dependencies -Sometimes you are working on a noarch package that can only run in locations that a different, arched package builds on. This is common for packages written in a scripting language which depend on the language's interpreter package, for instance. If the arched package that your package deps on isn't available on all architectures Fedora (or EPEL) targets you run into a situation where you may need to exclude your package from certain architectures' package repositories or prevent it from building on certain architectures in the buildsystem. +Sometimes you are working on a noarch package +that can only run in locations that a different, +arched package builds on. +This is common for packages written in a scripting language +which depend on the language's interpreter package, for instance. +If the arched package that your package deps on isn't available +on all architectures Fedora (or EPEL) targets +you run into a situation where you may need to exclude your package +from certain architectures' package repositories +or prevent it from building on certain architectures in the buildsystem. ==== Arch-Specific Runtime and Build-Time Dependencies From 38cbdeed8aa59be268ef8b350e342e44254ba352 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 21:24:41 +0000 Subject: [PATCH 25/38] SemBr for Arch-Specific Runtime and Build-Time Dependencies --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 68c3d40..0f25e53 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -450,7 +450,9 @@ or prevent it from building on certain architectures in the buildsystem. ==== Arch-Specific Runtime and Build-Time Dependencies -You can limit both the architectures used to build a noarch package, and the repositories to which the built noarch package will be added, by using either the `+ExcludeArch:+` or `+ExclusiveArch:+` tags: +You can limit both the architectures used to build a noarch package, +and the repositories to which the built noarch package will be added, +by using either the `+ExcludeArch:+` or `+ExclusiveArch:+` tags: .... BuildArch: noarch @@ -458,7 +460,14 @@ BuildArch: noarch ExclusiveArch: %{ix86} %{arm} x86_64 noarch .... -Sometimes a language runtime you are packaging for will provide a macro for the arches it's available on, for instance, `+%{nodejs_arches}+`. If it does exist, then you can use something like `+ExclusiveArch: %{nodejs_arches} noarch+` in your spec file. Take a look at the guidelines for the language to see if such a macro exists. +Sometimes a language runtime you are packaging for will provide a macro +for the arches it's available on, for instance, +`+%{nodejs_arches}+`. +If it does exist, then you can use something like +`+ExclusiveArch: %{nodejs_arches} noarch+` +in your spec file. +Take a look at the guidelines for the language +to see if such a macro exists. === No Arch-Specific Sources or Patches === From 37b2288ff7d17cfdd7132f59d565b98a7a7c55a2 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 21:40:50 +0000 Subject: [PATCH 26/38] SemBr for Multilib Exempt Locations section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 0f25e53..c71dc1b 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -548,7 +548,15 @@ more appropriate for their distro). === Multilib Exempt Locations -If a package is exempt from multilib, it may use `+%{_prefix}/lib+` instead of `+%{_libdir}+`. Packages that contain architecture specific files that would ordinarily be installed into `+%{_libexecdir}+` are always considered ineligible for multilib. However, you should be sure that the (sub)package that they are in does not have other content that would be considered eligible for multilib. If this is not the case for the files you wish to do this in for your package or you are just unsure, ask FESCo for an explicit multilib exemption. +If a package is exempt from multilib, +it may use `+%{_prefix}/lib+` instead of `+%{_libdir}+`. +Packages that contain architecture specific files +that would ordinarily be installed into `+%{_libexecdir}+` +are always considered ineligible for multilib. +However, you should be sure that the (sub)package that they are in +does not have other content that would be considered eligible for multilib. +If this is not the case for the files you wish to do this in for your package +or you are just unsure, ask FESCo for an explicit multilib exemption. === `+/run+` From 745ef8fa42f270b112d15b5f0da889c12641e71f Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 21:41:28 +0000 Subject: [PATCH 27/38] SemBr for /run section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index c71dc1b..e00f045 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -560,7 +560,11 @@ or you are just unsure, ask FESCo for an explicit multilib exemption. === `+/run+` -System services should store small volatile run-time data in `+/run+`. This is a tmpfs backed directory that is mounted in very early boot, before any services are started (and before `+/var+` is available). `+/var/run+` is a legacy symlink to `+/run+`. +System services should store small volatile run-time data in `+/run+`. +This is a tmpfs backed directory that is mounted in very early boot, +before any services are started +(and before `+/var+` is available). +`+/var/run+` is a legacy symlink to `+/run+`. === No Files or Directories under /srv, /usr/local, or /home/$USER From b7e97fb3c6c983d5240604d45195b34706fb1765 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 22:02:53 +0000 Subject: [PATCH 28/38] SemBr for No Files or Directories under... section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index e00f045..5541a26 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -579,14 +579,31 @@ Distributions must take care not to remove locally placed files in these directories without administrator permission." .... -The FHS is explicitly handing control of the directory structure under `+/srv+` to the system administrator rather than the distribution. Therefore, no Fedora packages can have any files or directories under `+/srv+`, come preconfigured to use specific files or directories under `+/srv+`, to remove files there, or to modify the files there in any way. - -In addition, no Fedora package can contain files or directories or modify files under: - -* `+/usr/local+` as these directories are not permitted to be used by Distributions in the FHS -* `+/home/$USER+` as users can arbitrarily modify the files in their home directories and rpm packages that modify those files run the risk of destroying user data. Additionally, sites may be nfs mounting `+/home+` on many different types of systems or even network automounting them on demand. Modifying files in home directories that are thus configured will have negative effects in both of these situations. - -It is important to note that the software in a Fedora package, once installed and configured by a user, can use `+/srv+` as a location for data. The package simply must not do this out of the box +The FHS is explicitly handing control of the directory structure +under `+/srv+` to the system administrator rather than the distribution. +Therefore, no Fedora packages can have any files or directories under `+/srv+`, +come preconfigured to use specific files or directories under `+/srv+`, +to remove files there, or to modify the files there in any way. + +In addition, no Fedora package can +contain files or directories or modify files under: + +* `+/usr/local+` +as these directories are not permitted to be used +by Distributions in the FHS +* `+/home/$USER+` +as users can arbitrarily modify the files in their home directories +and rpm packages that modify those files run the risk of destroying user data. +Additionally, sites may be nfs mounting `+/home+` +on many different types of systems +or even network automounting them on demand. +Modifying files in home directories that are thus configured +will have negative effects in both of these situations. + +It is important to note that the software in a Fedora package, +once installed and configured by a user, +can use `+/srv+` as a location for data. +The package simply must not do this out of the box === Limited usage of /opt, /etc/opt, and /var/opt From 5047903a88c87862f2f081a77419481e21e77b46 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 22:20:30 +0000 Subject: [PATCH 29/38] SemBr for Limited usage of /opt... section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 5541a26..b146bac 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -607,11 +607,34 @@ The package simply must not do this out of the box === Limited usage of /opt, /etc/opt, and /var/opt -`+/opt+` and its related directories (`+/etc/opt+` and `+/var/opt+`) is reserved for the use of vendors in the FHS. We have reserved the `+fedora+` name with http://www.lanana.org/lsbreg/providers/providers.txt[LANANA] for our use. If a package installs files into `+/opt+` it may only use directories in the `+/opt/fedora+` hierarchy. Fedora attempts to organize this directory by allocating a subdirectory of our `+/opt/fedora+` directory for specific subsystems. If you think you need to use `+/opt/fedora+` please file an FPC ticket to decide whether it's a valid use of `+/opt+` and what subdirectory should be allocated for your use. - -Currently, we have allocated `+/opt/fedora/scls+`, `+/etc/opt/fedora/scls+`, and `+/var/opt/fedora/scls+` for use by {scl-guidelines}. - -Because the Google-supplied Chrome packaging has chosen a specific file location for extension-specific files which, if used, would conflicts with the above guidelines, the Packaging Committee has approved the following exception: A package MAY install files into the `+/etc/opt/chrome/native-messaging-hosts+` directory, and may create that directory hierarchy, as long as package as a whole also supports Chromium. (The Chromium support MAY be in a different subpackage.) If Chrome in the future allows a more standard directory to be used for this purpose, this exception will be removed. +`+/opt+` and its related directories (`+/etc/opt+` and `+/var/opt+`) +is reserved for the use of vendors in the FHS. +We have reserved the `+fedora+` name with +http://www.lanana.org/lsbreg/providers/providers.txt[LANANA] +for our use. +If a package installs files into `+/opt+` +it may only use directories in the `+/opt/fedora+` hierarchy. +Fedora attempts to organize this directory by allocating a subdirectory +of our `+/opt/fedora+` directory for specific subsystems. +If you think you need to use `+/opt/fedora+` +please file an FPC ticket to decide whether it's a valid use of `+/opt+` +and what subdirectory should be allocated for your use. + +Currently, we have allocated +`+/opt/fedora/scls+`, `+/etc/opt/fedora/scls+`, and `+/var/opt/fedora/scls+` +for use by {scl-guidelines}. + +Because the Google-supplied Chrome packaging has chosen +a specific file location for extension-specific files which, +if used, would conflicts with the above guidelines, +the Packaging Committee has approved the following exception: +A package MAY install files into the +`+/etc/opt/chrome/native-messaging-hosts+` directory, +and may create that directory hierarchy, +as long as package as a whole also supports Chromium. +(The Chromium support MAY be in a different subpackage.) +If Chrome in the future allows a more standard directory +to be used for this purpose, this exception will be removed. === Effect of the UsrMove Fedora Feature From 9fc2336c7157b99c2895f8d686c6a37eb94c224a Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 22:43:30 +0000 Subject: [PATCH 30/38] SemBr for the Effect of the UsrMove... section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index b146bac..24fc134 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -638,7 +638,8 @@ to be used for this purpose, this exception will be removed. === Effect of the UsrMove Fedora Feature -Fedora has merged several directories in `+/+` with their counterparts in `+/usr/+`. +Fedora has merged several directories in `+/+` +with their counterparts in `+/usr/+`. /bin @@ -656,16 +657,34 @@ Fedora has merged several directories in `+/+` with their counterparts in `+/usr /usr/lib aka %\{_prefix}/lib -For example, end users will find that `+/bin/sh+` is the same file as `+/usr/bin/sh+`. +For example, end users will find that `+/bin/sh+` +is the same file as `+/usr/bin/sh+`. -However, rpm file dependencies don't work according to what's on the filesystem, they work according to the path specified in the rpm `+%files+` section. So an rpm which specified: +However, +rpm file dependencies don't work according to what's on the filesystem, +they work according to the path specified in the rpm `+%files+` section. +So an rpm which specified: .... %files /bin/sh .... -would be able to satisfy a file dependency for `+/bin/sh+` but not for `+/usr/bin/sh+`. As a packager you may need to pay attention to where other packages expect to find your files. Things that history has placed into `+/bin+`, `+/sbin+`, `+/lib+`, or `+/lib64+` should be listed in the `+%files+` section as being in those directories. Things that history placed in `+/usr/bin+`, `+/usr/sbin+`, etc, should be listed in the `+%files+` section as being in `+%{_bindir}+`, `+%{_sbindir}+`, etc. If you feel that there is some historical confusion as to which directory a program is placed in, you can use a Virtual Provides to list the alternate path. For instance: +would be able to satisfy a file dependency for `+/bin/sh+` +but not for `+/usr/bin/sh+`. +As a packager you may need to pay attention +to where other packages expect to find your files. +Things that history has placed into +`+/bin+`, `+/sbin+`, `+/lib+`, or `+/lib64+` +should be listed in the `+%files+` section as being in those directories. +Things that history placed in +`+/usr/bin+`, `+/usr/sbin+`, etc, +should be listed in the `+%files+` section as being in +`+%{_bindir}+`, `+%{_sbindir}+`, etc. +If you feel that there is some historical confusion +as to which directory a program is placed in, +you can use a Virtual Provides to list the alternate path. +For instance: .... Provides: %{_sbindir}/ifconfig @@ -674,7 +693,11 @@ Provides: %{_sbindir}/ifconfig /sbin/ifconfig .... -If you are a packager who uses file dependencies to Require the proper dependencies then you may need to make sure that the file dependencies are pointing to the location that the packager of that file specified to rpm. Here's an example of doing this: +If you are a packager who uses file dependencies +to Require the proper dependencies +then you may need to make sure that the file dependencies +are pointing to the location that the packager of that file specified to rpm. +Here's an example of doing this: .... $ rpm -ql $(rpm -qf /usr/sbin/ifconfig)|grep sbin/ifconfig From 764c4a77276e15d75193da390e62d57dfff101f9 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 22:47:54 +0000 Subject: [PATCH 31/38] SemBr for Use rpmlint section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 24fc134..249537b 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -708,7 +708,19 @@ So you'd want to use `+Requires: /sbin/ifconfig+` in your spec file. == Use rpmlint -Run rpmlint on binary and source rpms to examine them for common errors, and fix them (unless rpmlint is wrong, which can happen, too). If you find rpmlint's output cryptic, the `+-i+` switch to it can be used to get more verbose descriptions of most errors and warnings. Note that rpmlint will perform additional checks if given the name of an installed package. For example, `+dnf install foo-1.0-1.f20.x86_64.rpm; rpmlint foo+` will perform a set of tests on the foo package that `+rpmlint foo-1.0-1.f20.x86_64.rpm+` cannot. A community-maintained page on rpmlint issues can be found https://fedoraproject.org/wiki/Common_Rpmlint_issues[here]. +Run rpmlint on binary and source rpms to examine them for common errors, +and fix them (unless rpmlint is wrong, which can happen, too). +If you find rpmlint's output cryptic, +the `+-i+` switch to it can be used +to get more verbose descriptions of most errors and warnings. +Note that rpmlint will perform additional checks +if given the name of an installed package. +For example, +`+dnf install foo-1.0-1.f20.x86_64.rpm; rpmlint foo+` +will perform a set of tests on the foo package that +`+rpmlint foo-1.0-1.f20.x86_64.rpm+` cannot. +A community-maintained page on rpmlint issues can be found +https://fedoraproject.org/wiki/Common_Rpmlint_issues[here]. == Tags and Sections From f8390ba0340cfeeb9445e262161c13489331e600 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 22:49:12 +0000 Subject: [PATCH 32/38] SemBr for Tags and Sections section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 249537b..87ee2e0 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -724,11 +724,18 @@ https://fedoraproject.org/wiki/Common_Rpmlint_issues[here]. == Tags and Sections -* The `+Copyright:+`, `+Packager:+`, `+Vendor:+` and `+PreReq:+` tags MUST NOT be used. -* The `+BuildRoot:+` tag, `+Group:+` tag, and `+%clean+` section SHOULD NOT be used. -* The contents of the buildroot SHOULD NOT be removed in the first line of `+%install+`. +* The `+Copyright:+`, `+Packager:+`, `+Vendor:+` and `+PreReq:+` tags +MUST NOT be used. +* The `+BuildRoot:+` tag, `+Group:+` tag, and `+%clean+` section +SHOULD NOT be used. +* The contents of the buildroot SHOULD NOT be removed +in the first line of `+%install+`. * The `+Summary:+` tag value SHOULD NOT end in a period. -* The `+Source:+` tags document where to find the upstream sources for the package. In most cases this SHOULD be a complete URL to the upstream tarball. For special cases, please see the xref:SourceURL.adoc[SourceURL Guidelines]. +* The `+Source:+` tags document where to find +the upstream sources for the package. +In most cases this SHOULD be a complete URL to the upstream tarball. +For special cases, please see the +xref:SourceURL.adoc[SourceURL Guidelines]. == Package Dependencies From 47e629cd2c98bfe7d986301cb56d0e9c0cbeda10 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 23:32:20 +0000 Subject: [PATCH 33/38] SemBr for Package Dependencies section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 87ee2e0..e904f7a 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -739,11 +739,18 @@ xref:SourceURL.adoc[SourceURL Guidelines]. == Package Dependencies -All package dependencies (build-time or runtime, regular, weak or otherwise) MUST ALWAYS be satisfiable within the official Fedora repositories. +All package dependencies +(build-time or runtime, regular, weak or otherwise) +MUST ALWAYS be satisfiable within the official Fedora repositories. -RPM can automatically determine dependencies for most compiled libraries and for some scripting languages such as Perl. Automatically determined dependencies MUST NOT be duplicated by manual dependencies. +RPM can automatically determine dependencies for most compiled libraries +and for some scripting languages such as Perl. +Automatically determined dependencies MUST NOT be duplicated +by manual dependencies. -Build dependencies, however, cannot be automatically determined and MUST be explicitly listed. Refer to the <>. +Build dependencies, however, +cannot be automatically determined and MUST be explicitly listed. +Refer to the <>. Versioned dependencies (build-time or runtime) SHOULD ONLY be used when actually necessary to guarantee @@ -753,7 +760,9 @@ by a version present in three previous Fedora releases then a versioned dependency is not needed and a regular unversioned dependency SHOULD be used instead. -A versioned dependency on a package with a defined Epoch MUST be included in that dependency. Otherwise the dependency will not function as expected. +A versioned dependency on a package with a defined Epoch +MUST be included in that dependency. +Otherwise the dependency will not function as expected. === Dependency types From 7069ffd573f63cd9ffaf5761804219272bf132f5 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 23:33:44 +0000 Subject: [PATCH 34/38] SemBr for Dependency types section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index e904f7a..d57ad49 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -766,13 +766,19 @@ Otherwise the dependency will not function as expected. === Dependency types -`Requires` MUST be used if the dependency is required for the software to function correctly. - -If the package functions correctly but in diminished capacity, then -`Recommends` or `Suggests` SHOULD be used. -If the functionality should be available by default for users, `Recommends` SHOULD be used, and `Suggests` otherwise. -Alternatively, the reverse dependencies `Supplements` or `Enhances` may be used in the other package. -See xref:WeakDependencies.adoc[Packaging:WeakDependencies] for guidelines on using those dependency types. +`Requires` MUST be used if the dependency is required +for the software to function correctly. + +If the package functions correctly but in diminished capacity, +then `Recommends` or `Suggests` SHOULD be used. +If the functionality should be available by default for users, +`Recommends` SHOULD be used, +and `Suggests` otherwise. +Alternatively, the reverse dependencies +`Supplements` or `Enhances + may be used in the other package. +See xref:WeakDependencies.adoc[Packaging:WeakDependencies] +for guidelines on using those dependency types. === Architecture-specific Dependencies From 98a1a31ccf76fab590fdc65bb38f025c4d5d1da4 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 27 2021 23:59:49 +0000 Subject: [PATCH 35/38] SemBr for Architecture-specific Dependencies section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index d57ad49..d157947 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -782,7 +782,9 @@ for guidelines on using those dependency types. === Architecture-specific Dependencies -A dependency is made arch-specific by appending the macro `+%{?_isa}+` to the package name. For example: +A dependency is made arch-specific by appending the macro `+%{?_isa}+` +to the package name. +For example: .... Requires: foo @@ -794,7 +796,10 @@ becomes: Requires: foo%{?_isa} .... -If the foo-devel package has a foo-config script, you can try doing a foo-config --libs and foo-config --cflags to get strong hints what packages should be marked as foo's requirements. For example: +If the foo-devel package has a foo-config script, +you can try doing a foo-config --libs and foo-config --cflags +to get strong hints what packages should be marked as foo's requirements. +For example: .... $ gtk-config --cflags From 522dce0982ddb794a70450b8dea327a91eb6cc7c Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 28 2021 00:00:54 +0000 Subject: [PATCH 36/38] SemBr for Rich/Boolean dependencies section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index d157947..9cdca1c 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -814,7 +814,9 @@ This means that gtk+-devel should contain === Rich/Boolean dependencies -Packages MAY make full use of the https://rpm-software-management.github.io/rpm/manual/boolean_dependencies.html[rich (or Boolean) dependency feature] supported in RPM. +Packages MAY make full use of the +https://rpm-software-management.github.io/rpm/manual/boolean_dependencies.html[rich (or Boolean) dependency feature] +supported in RPM. === File and Directory Dependencies From 07122b94e21d256ecdca18f3afb61d1d801b961b Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 28 2021 00:02:37 +0000 Subject: [PATCH 37/38] SemBr for File and Directory Dependencies section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 9cdca1c..c9be548 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -820,13 +820,21 @@ supported in RPM. === File and Directory Dependencies -RPM gives you the ability to depend on arbitrary files or directories instead of packages. Packages SHOULD NOT include file dependencies outside of the following directories: +RPM gives you the ability to depend on arbitrary files or directories +instead of packages. +Packages SHOULD NOT include file dependencies +outside of the following directories: * /usr/bin * /usr/sbin * /etc -Please also note that it is not uncommon for multiple packages to provide the same directory. Directory dependencies SHOULD ONLY be used to express the dependency on that directory existing, not on any other functionality of any other package that might provide that directory. +Please also note that it is not uncommon +for multiple packages to provide the same directory. +Directory dependencies SHOULD ONLY be used +to express the dependency on that directory existing, +not on any other functionality of any other package +that might provide that directory. === Explicit Requires From cb6ea9b513368be1881f6a614fd076039cc6e3ba Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 28 2021 00:07:14 +0000 Subject: [PATCH 38/38] 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