From 0fd2cb177da7328aefe62e4f7b0d9f8063cdc91e Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 11 2021 19:54:41 +0000 Subject: [PATCH 1/53] SemBr for Filtering Auto-Generated Requires section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 723c4f8..cd60b74 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -898,7 +898,12 @@ it is no longer necessary to list the explicit, versioned requirement. === Filtering Auto-Generated Requires -RPM attempts to auto-generate Requires (and Provides) at build time, but in some situations, the auto-generated Requires/Provides are not correct or not wanted. For more details on how to filter out auto-generated Requires or Provides, please see: xref:AutoProvidesAndRequiresFiltering.adoc[Packaging:AutoProvidesAndRequiresFiltering]. +RPM attempts to auto-generate Requires (and Provides) at build time, +but in some situations, +the auto-generated Requires/Provides are not correct or not wanted. +For more details on how to filter out auto-generated Requires or Provides, +please see: +xref:AutoProvidesAndRequiresFiltering.adoc[Packaging:AutoProvidesAndRequiresFiltering]. [#buildrequires] == Build-Time Dependencies (BuildRequires) From f196402b4ec03b314cce97b408feb6bf9ac3ce96 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 16:46:14 +0000 Subject: [PATCH 2/53] SemBr for BuildRequires section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index cd60b74..4224d93 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -908,18 +908,29 @@ xref:AutoProvidesAndRequiresFiltering.adoc[Packaging:AutoProvidesAndRequiresFilt [#buildrequires] == Build-Time Dependencies (BuildRequires) -It is important that your package list all necessary build dependencies using the `+BuildRequires:+` tag. You MAY assume that enough of an environment exists for RPM to function, to build packages and execute basic shell scripts, but you SHOULD NOT assume any other packages are present as RPM dependencies and anything brought into the buildroot by the build system can change over time. +It is important that your package list all necessary build dependencies +using the `+BuildRequires:+` tag. +You MAY assume that enough of an environment exists for RPM to function, +to build packages and execute basic shell scripts, +but you SHOULD NOT assume any other packages are present +as RPM dependencies +and anything brought into the buildroot by the build system +can change over time. === BuildRequires and %\{_isa} -You MUST NOT use arched BuildRequires. The arch ends up in the built SRPM but SRPMs need to be architecture independent. For instance, if you did this: +You MUST NOT use arched BuildRequires. +The arch ends up in the built SRPM +but SRPMs need to be architecture independent. +For instance, if you did this: .... # Example of what *not* to do BuildRequires: foo%{?_isa} >= 3.3 .... -Then the SRPM that is built in Fedora would have one of these Requirements depending on what builder the SRPM was created on: +Then the SRPM that is built in Fedora would have one of these Requirements +depending on what builder the SRPM was created on: .... foo(x86-32) >= 3.3 @@ -927,11 +938,17 @@ foo(x86-32) >= 3.3 foo(x86-64) >= 3.3 .... -This would prevent yum-builddep or similar tools that use the SRPM's requirements from operating correctly. +This would prevent yum-builddep +or similar tools that use the SRPM's requirements +from operating correctly. === BuildRequires based on pkg-config -Fedora packages which use `+pkg-config+` to build against a library (e.g. 'foo') on which they depend, *SHOULD* express their build dependency correctly as `+pkgconfig(foo)+`. For more information, see xref:PkgConfigBuildRequires.adoc[Packaging:PkgConfigBuildRequires]. +Fedora packages which use `+pkg-config+` +to build against a library (e.g. 'foo') on which they depend, +*SHOULD* express their build dependency correctly as `+pkgconfig(foo)+`. +For more information, see +xref:PkgConfigBuildRequires.adoc[Packaging:PkgConfigBuildRequires]. == Conditional build-time dependencies From 46af49978ff9f9b2381c872d3de72b08a8e9af0e Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 16:52:02 +0000 Subject: [PATCH 3/53] SemBr for Conditional build-time deps section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 4224d93..16e82a0 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -952,7 +952,15 @@ xref:PkgConfigBuildRequires.adoc[Packaging:PkgConfigBuildRequires]. == Conditional build-time dependencies -If the spec file contains conditional dependencies selected based on presence of optional `+--with(out) foo+` arguments to `+rpmbuild+`, build the source RPM to be submitted with the default options, i.e., so that none of these arguments are present in the `+rpmbuild+` command line. The reason is that those requirements get "serialized" into the resulting source RPM, i.e., the conditionals no longer apply. +If the spec file contains conditional dependencies +selected based on presence of optional +`+--with(out) foo+` arguments to `+rpmbuild+`, +build the source RPM to be submitted with the default options, +i.e., so that none of these arguments are present +in the `+rpmbuild+` command line. +The reason is that those requirements get "serialized" +into the resulting source RPM, +i.e., the conditionals no longer apply. == Summary and description From fcaed09d1db6ae6b41bd0a75a627d2d132dc3f02 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 16:57:30 +0000 Subject: [PATCH 4/53] Sembr for Summary and Description section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 16e82a0..ffd0599 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -964,16 +964,35 @@ i.e., the conditionals no longer apply. == Summary and description -The summary should be a short and concise description of the package. The description expands upon this. Do not include installation instructions in the description; it is not a manual. If the package requires some manual configuration or there are other important instructions to the user, refer the user to the documentation in the package. Add a _README.Fedora_, or similar, if you feel this is necessary. Also, please make sure that there are no lines in the description longer than 80 characters. - -Please put personal preferences aside and use American English spelling in the summary and description. Packages can contain additional translated summary/description for supported Non-English languages, if available. +The summary should be a short and concise description of the package. +The description expands upon this. +Do not include installation instructions in the description; +it is not a manual. +If the package requires some manual configuration +or there are other important instructions to the user, +refer the user to the documentation in the package. +Add a _README.Fedora_, or similar, +if you feel this is necessary. +Also, please make sure that there are no lines in the description +longer than 80 characters. + +Please put personal preferences aside +and use American English spelling in the summary and description. +Packages can contain additional translated summary/description +for supported Non-English languages, +if available. === Trademarks in Summary or Description -Packagers should be careful how they use trademarks in Summary or Description. There are a few rules to follow: +Packagers should be careful how they use trademarks +in Summary or Description. +There are a few rules to follow: -* Never use `\(TM)` or `\(R)` (or the Unicode equivalents, ™/®). It is incredibly complicated to use these properly, so it is actually safer for us to not use them at all. -* Use trademarks in a way that is not ambiguous. Avoid phrasing like "similar to" or "like". Some examples: +* Never use `\(TM)` or `\(R)` (or the Unicode equivalents, ™/®). +It is incredibly complicated to use these properly, +so it is actually safer for us to not use them at all. +* Use trademarks in a way that is not ambiguous. +Avoid phrasing like "similar to" or "like". Some examples: * *BAD:* It is similar to Adobe Photoshop. * *GOOD:* It supports Adobe Photoshop PSD files, ... @@ -981,7 +1000,10 @@ Packagers should be careful how they use trademarks in Summary or Description. T * *BAD:* A Linux version of Microsoft Office * *GOOD:* A word-processor with support for Microsoft Office DOC files -If you're not sure, ask yourself, is there any chance someone may get confused and think that this package is the trademarked item? When in doubt, try to leave the trademark out. +If you're not sure, ask yourself, +is there any chance someone may get confused +and think that this package is the trademarked item? +When in doubt, try to leave the trademark out. == Documentation From 78aad469cd9ee305b616537d3bb670f782a34766 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 17:32:15 +0000 Subject: [PATCH 5/53] SemBr for Documentation section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index ffd0599..b653db2 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1007,21 +1007,63 @@ When in doubt, try to leave the trademark out. == Documentation -Any relevant documentation included in the source distribution should be included in the package in the proper documentation directory. Irrelevant documentation includes build instructions, the omnipresent _INSTALL_ file containing generic build instructions, for example, and documentation for non-Linux systems, e.g. _README.MSDOS_. Also pay attention about which subpackage you include documentation in. For example API documentation belongs in the `+-devel+` subpackage, not the main one. Or if there's a lot of documentation, consider putting it into a subpackage. In this case, it is recommended to use `+*-doc+` as the subpackage name. - -Marking a _relative_ path with `+%doc+` in the `+%files+` section will cause RPM to copy the referenced file or directory from `+%_builddir+` to the proper location for documentation. Files can also be placed in `+%_pkgdocdir+`, and the build scripts of the software being packaged may do this automatically when called in `+%install+`. However, mixing these methods is problematic and may result in duplicated or conflicting files, so use of `+%doc+` with _relative_ paths and installation of files directly into `+%_pkgdocdir+` in the same source package is forbidden. - -Files marked as documentation must not cause the package to pull in more dependencies than it would without the documentation. One simple way to ensure this in most cases is to remove all executable permissions from files in `+%_pkgdocdir+`. - -Files located in `+%_pkgdocdir+` must not affect the runtime of the packaged software. The software must function properly and with unchanged functionality if those files are modified, removed or not installed at all. - -Although license files are documentation, they are treated specially (including using a different tag). Please see xref:LicensingGuidelines.adoc[Licensing Guidelines] for how to handle them. +Any relevant documentation included in the source distribution +should be included in the package in the proper documentation directory. +Irrelevant documentation includes build instructions, +the omnipresent _INSTALL_ file containing generic build instructions, +or example, +and documentation for non-Linux systems, e.g. _README.MSDOS_. +Also pay attention about which subpackage you include documentation in. +For example API documentation belongs in the `+-devel+` subpackage, +not the main one. +Or if there's a lot of documentation, +consider putting it into a subpackage. +In this case, it is recommended to use `+*-doc+` as the subpackage name. + +Marking a _relative_ path with `+%doc+` in the `+%files+` section +will cause RPM to copy the referenced file or directory +from `+%_builddir+` to the proper location for documentation. +Files can also be placed in `+%_pkgdocdir+`, +and the build scripts of the software being packaged may do this automatically +when called in `+%install+`. +However, mixing these methods is problematic +and may result in duplicated or conflicting files, +so use of `+%doc+` with _relative_ paths and installation of files +directly into `+%_pkgdocdir+` in the same source package is forbidden. + +Files marked as documentation must not cause the package +to pull in more dependencies than it would without the documentation. +One simple way to ensure this in most cases +is to remove all executable permissions from files in `+%_pkgdocdir+`. + +Files located in `+%_pkgdocdir+` must not affect the runtime +of the packaged software. +The software must function properly +and with unchanged functionality +if those files are modified, removed or not installed at all. + +Although license files are documentation, +they are treated specially (including using a different tag). +Please see xref:LicensingGuidelines.adoc[Licensing Guidelines] +for how to handle them. === Separate Documentation Packages -If building documentation requires many additional dependencies then you MAY elect to not build it in the main package and instead create a separate *-doc source package which builds only the documentation. This separately packaged documentation MUST correspond to the version of the packaged software. In other words, if a new release of the software includes changes to the documentation, then the documentation package MUST also be updated. But if the new version of the software does not include documentation changes, then you MAY choose not to update the documentation package. - -A comment SHOULD be added near Version tag of the main package to remind maintainers to update the separate *-doc package when needed. +If building documentation requires many additional dependencies +then you MAY elect to not build it in the main package +and instead create a separate *-doc source package +which builds only the documentation. +This separately packaged documentation MUST correspond +to the version of the packaged software. +In other words, +if a new release of the software includes changes to the documentation, +then the documentation package MUST also be updated. +But if the new version of the software +does not include documentation changes, +then you MAY choose not to update the documentation package. + +A comment SHOULD be added near Version tag of the main package +to remind maintainers to update the separate *-doc package when needed. [#changelogs] == Changelogs From 007d9bb43feb70ec461469fe27542a10a1df08c0 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 17:37:29 +0000 Subject: [PATCH 6/53] SemBr for Changelogs section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index b653db2..2a54f1b 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1068,9 +1068,15 @@ to remind maintainers to update the separate *-doc package when needed. [#changelogs] == Changelogs -_Every time_ you make changes, that is, whenever you increment the E-V-R of a package, add a changelog entry. This is important not only to have an idea about the history of a package, but also to enable users, fellow packagers, and QA people to easily spot the changes that you make. +_Every time_ you make changes, that is, +whenever you increment the E-V-R of a package, +add a changelog entry. +This is important not only to have an idea about the history of a package, +but also to enable users, fellow packagers, and QA people +to easily spot the changes that you make. -If a particular change is related to a Bugzilla bug, include the bug ID in the changelog entry for easy reference, e.g. +If a particular change is related to a Bugzilla bug, +include the bug ID in the changelog entry for easy reference, e.g. .... * Wed Jun 14 2003 Joe Packager - 1.0-2 @@ -1095,23 +1101,40 @@ You must use one of the following formats: - And fix the link syntax. .... -Changelog entries should provide a brief summary of the changes done to the package between releases, including noting updating to a new version, adding a patch, fixing other spec sections, note bugs fixed, and CVE's if any. They must never simply contain an entire copy of the source CHANGELOG entries. The intent is to give the user a hint as to what changed in a package update without overwhelming them with the technical details. Links to upstream changelogs can be entered for those who want additional information. -If you wish to "scramble" or "obfuscate" your email address in the changelog, you may do so, provided that it is still understandable by humans. +Changelog entries should provide a brief summary +of the changes done to the package between releases, +including noting updating to a new version, +adding a patch, fixing other spec sections, +note bugs fixed, and CVE's if any. +They must never simply contain an entire copy of the source CHANGELOG entries. +The intent is to give the user a hint as to what changed +in a package update without overwhelming them with the technical details. +Links to upstream changelogs can be entered +for those who want additional information. +If you wish to "scramble" or "obfuscate" your email address in the changelog, +you may do so, provided that it is still understandable by humans. === Multiple Changelog Entries per Release -In some situations, it may be useful for packagers to have multiple changelog entries in the spec file, but not increment the release field for each one. There are two supported methods for doing this: +In some situations, it may be useful for packagers +to have multiple changelog entries in the spec file, +but not increment the release field for each one. +There are two supported methods for doing this: ==== Updating and replacing the existing date line -In this situation, you have added this changelog entry, but have not built the package yet: +In this situation, you have added this changelog entry, +but have not built the package yet: .... * Nov 12 2010 Toshio Kuratomi - 1.0-1 - Fix spelling errors in package description .... -The next day, you make additional changes to the spec, and need to add a new changelog line, then you would update the existing date line for 1.0-1, and append any new notes, making the changelog look like this: +The next day, you make additional changes to the spec, +and need to add a new changelog line, +then you would update the existing date line for 1.0-1, +and append any new notes, making the changelog look like this: .... * Nov 13 2010 Toshio Kuratomi - 1.0-1 @@ -1121,18 +1144,26 @@ The next day, you make additional changes to the spec, and need to add a new cha Please remember that this is only acceptable if 1.0-1 has not yet been built. -You can do this any number of times, until you actually build 1.0-1 in the buildsystem. Once you've done that, you must change the E-V-R and any new entries should be added as described in <>. +You can do this any number of times, +until you actually build 1.0-1 in the buildsystem. +Once you've done that, +you must change the E-V-R and any new entries should be added +as described in <>. ==== Repeat the old version release with a new entry -In this situation, you have added this changelog entry, but have not built the package yet: +In this situation, you have added this changelog entry, +but have not built the package yet: .... * Nov 12 2010 Toshio Kuratomi - 1.0-1 - Fix spelling errors in package description .... -The next day, you make additional changes to the spec, and need to add a new changelog line. Now, you can add an additional changelog item with the new date, but the same Version-Release, so your new changelog looks like this: +The next day, you make additional changes to the spec, +and need to add a new changelog line. +Now, you can add an additional changelog item with the new date, +but the same Version-Release, so your new changelog looks like this: .... * Nov 13 2010 Toshio Kuratomi - 1.0-1 @@ -1144,7 +1175,10 @@ The next day, you make additional changes to the spec, and need to add a new cha Please remember that this is only acceptable if 1.0-1 has not yet been built. -You can do this any number of times, until you actually build 1.0-1 in the buildsystem. Once you've done that, you must change the E-V-R and any new entries should be added as described in <>. +You can do this any number of times, +until you actually build 1.0-1 in the buildsystem. +Once you've done that, you must change the E-V-R +and any new entries should be added as described in <>. == Manpages From 8a85677383d8f901ef9fd3485a3a7e5149935d67 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 17:45:37 +0000 Subject: [PATCH 7/53] SemBr for Compiler section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 2a54f1b..5822bf1 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1207,14 +1207,22 @@ Thus it is not necessary to use `+%doc+`. [#compiler] == Compiler -Fedora packages should default to using gcc as the compiler (for all languages that gcc supports) or clang if upstream does not support building with gcc. However, if there is a good technical reason, packagers may choose not to use the default compiler. Examples of valid technical reasons to not use the default compiler, include but are not limited to: +Fedora packages should default to using gcc as the compiler +(for all languages that gcc supports) +or clang if upstream does not support building with gcc. +However, if there is a good technical reason, +packagers may choose not to use the default compiler. +Examples of valid technical reasons to not use the default compiler, +include but are not limited to: * The default compiler cannot build a package correctly. -* The packager needs to disable a compiler feature (e.g. LTO) in order for the default compiler to correctly compile their package. +* The packager needs to disable a compiler feature (e.g. LTO) +in order for the default compiler to correctly compile their package. * The default compiler takes significantly longer to build a package. * The default compiler is missing a feature that would benefit the package. -Packagers choosing to use a non-default compiler should document the reason for this decision in a comment in the spec file. +Packagers choosing to use a non-default compiler +should document the reason for this decision in a comment in the spec file. == Compiler macros From 014750f50d9fe25871bb7978a0a4080368c2e6fc Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 17:48:52 +0000 Subject: [PATCH 8/53] SemBr for Compiler macros section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 5822bf1..c94f8e9 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1226,22 +1226,29 @@ should document the reason for this decision in a comment in the spec file. == Compiler macros -If clang is being used to build a package, packagers must set the %toolchain macro to clang: +If clang is being used to build a package, +packagers must set the %toolchain macro to clang: .... %global toolchain clang .... -This ensures that Fedora's clang-specific compiler flags are used when compiling. +This ensures that Fedora's clang-specific compiler flags are used +when compiling. -If a packager wants to use conditional macros in a spec file to make it easier to switch between two different compilers, then the following macros names should be used: +If a packager wants to use conditional macros in a spec file +to make it easier to switch between two different compilers, +then the following macros names should be used: .... %bcond_with toolchain_clang %bcond_with toolchain_gcc .... -Packagers may also use the %build_cc, %build_cxx, or %build_cpp macros in the spec file in place of hard-coding the compiler name. The values of these variables are controled by setting the %toolchain macro to either clang or gcc. +Packagers may also use the %build_cc, %build_cxx, or %build_cpp macros +in the spec file in place of hard-coding the compiler name. +The values of these variables are controled by setting the %toolchain macro +to either clang or gcc. == Compiler flags From 2bb38ada4f6c1f6148b92f3368e886a242d6fa58 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 17:53:30 +0000 Subject: [PATCH 9/53] SemBr for Compiler flags section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index c94f8e9..ffa8951 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1253,16 +1253,39 @@ to either clang or gcc. == Compiler flags -Compilers used to build packages must honor the applicable compiler flags set in the system rpm configuration. Honoring means that the contents of that variable is used as the basis of the flags actually used by the compiler during the package build. - -For C, {cpp}, and Fortran code, the xref:RPMMacros.adoc#build-flags-macros-and-variables[%\{optflags} macro] contains these flags. -Overriding these flags for performance optimizations (for instance, -O3 instead of -O2) is generally discouraged. If you can present benchmarks that show a significant speedup for this particular code, this could be revisited on a case-by-case basis. Adding to and overriding or filtering parts of these flags is permitted if there's a good reason to do so; the rationale for doing so must be documented in the specfile. - -There are certain, security related flags that are commonly allowed. These flags may degrade performance slightly but the increased security can be worthwhile for some programs. +Compilers used to build packages must honor the applicable compiler flags +set in the system rpm configuration. +Honoring means that the contents of that variable is used +as the basis of the flags actually used by the compiler +during the package build. + +For C, {cpp}, and Fortran code, +the xref:RPMMacros.adoc#build-flags-macros-and-variables[%\{optflags} macro] +contains these flags. +Overriding these flags for performance optimizations +(for instance, -O3 instead of -O2) +is generally discouraged. +If you can present benchmarks that show a significant speedup +for this particular code, +this could be revisited on a case-by-case basis. +Adding to and overriding or filtering parts of these flags is permitted +if there's a good reason to do so; +the rationale for doing so must be documented in the specfile. + +There are certain, security related flags that are commonly allowed. +These flags may degrade performance slightly +but the increased security can be worthwhile for some programs. === PIE -PIE adds security to executables by composing them entirely of position-independent code. Position-independent code (PIC) is machine instruction code that executes properly regardless of where in memory it resides. PIE allows Exec Shield to use address space layout randomization to prevent attackers from knowing where existing executable code is during a security attack using exploits that rely on knowing the offset of the executable code in the binary, such as return-to-libc attacks. +PIE adds security to executables +by composing them entirely of position-independent code. +Position-independent code (PIC) is machine instruction code +that executes properly regardless of where in memory it resides. +PIE allows Exec Shield to use address space layout randomization +to prevent attackers from knowing where existing executable code is +during a security attack using exploits that rely on knowing the offset +of the executable code in the binary, such as return-to-libc attacks. In Fedora, PIE is enabled by default. To disable it in your spec, add: @@ -1274,7 +1297,9 @@ spec, add: If your package meets any of the following criteria you MUST NOT disable the PIE compiler flags: -* Your package is long running. This means it's likely to be started and keep running until the machine is rebooted, not start on demand and quit on idle. +* Your package is long running. +This means it's likely to be started and keep running +until the machine is rebooted, not start on demand and quit on idle. * Your package has suid binaries, or binaries with capabilities. From b544e8c96e6ac7518a5efbc72af01ff03468e2ea Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 18:23:18 +0000 Subject: [PATCH 10/53] SemBr for Debuginfo packages section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index ffa8951..fd48988 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1307,7 +1307,13 @@ until the machine is rebooted, not start on demand and quit on idle. == Debuginfo packages -Packages should produce useful `+-debuginfo+` packages, or explicitly disable them when it is not possible to generate a useful one but rpmbuild would do it anyway. Whenever a `+-debuginfo+` package is explicitly disabled, an explanation why it was done is required in the specfile. Debuginfo packages are discussed in more detail in a separate document, xref:Debuginfo.adoc[Packaging:Debuginfo]. +Packages should produce useful `+-debuginfo+` packages, +or explicitly disable them when it is not possible to generate a useful one +but rpmbuild would do it anyway. +Whenever a `+-debuginfo+` package is explicitly disabled, +an explanation why it was done is required in the specfile. +Debuginfo packages are discussed in more detail in a separate document, +xref:Debuginfo.adoc[Packaging:Debuginfo]. == Devel Packages From 34b57a96282ce782751a41cd404d87617a7e132a Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 19:53:49 +0000 Subject: [PATCH 11/53] SemBr for Devel Packages section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index fd48988..79f56dc 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1317,11 +1317,19 @@ xref:Debuginfo.adoc[Packaging:Debuginfo]. == Devel Packages -Fedora packages must be designed with a logical separation of files. Specifically, -devel packages must be used to contain files which are intended solely for development or needed only at build-time. This is done to minimize the install footprint for users. There are some types of files which almost always belong in a -devel package: +Fedora packages must be designed with a logical separation of files. +Specifically, -devel packages must be used to contain files +which are intended solely for development or needed only at build-time. +This is done to minimize the install footprint for users. +There are some types of files which almost always belong in a -devel package: * Header files (foo.h), usually found in /usr/include -* Static library files when the package does not provide any matching shared library files. See <> for more information about this scenario. -* Unversioned shared system library files, when a matching versioned shared system library file is also present. For example, if your package contains: +* Static library files +when the package does not provide any matching shared library files. +See <> for more information about this scenario. +* Unversioned shared system library files, +when a matching versioned shared system library file is also present. +For example, if your package contains: .... /usr/lib/libfoo.so.3.0.0 @@ -1329,22 +1337,68 @@ Fedora packages must be designed with a logical separation of files. Specificall /usr/lib/libfoo.so .... -The versioned shared library files (/usr/lib/libfoo.so.3.2.0 and /usr/lib/libfoo.so.3) are necessary for users to run programs linked against libfoo, so they belong in the base package. The other, unversioned, shared library file (/usr/lib/libfoo.so) is only used to actually link libfoo to code being compiled, and is not necessary to be installed on a users system. This means that it belongs in a -devel package. Please note that in most cases, only the fully versioned shared library file (/usr/lib/libfoo.so.3.2.0) is an actual file, all of the other files are symbolic links to it. -When a shared library file is only provided in an unversioned format, the packager should ask upstream to consider providing a properly versioned library file. However, in such cases, if the shared library file is necessary for users to run programs linked against it, it must go into the base package. If upstream versions the shared library file at a future point, packagers must be careful to move to the versioned layout described above. - -As an additional complication, some software generates unversioned shared objects which are not intended to be used as system libraries. These files are usually plugins or modular functionality specific to an application, and are not located in the ld library paths or cache. This means that they are not located directly in /usr/lib or /usr/lib64, or in a directory listed as a library path in /etc/ld.so.conf (or an /etc/ld.so.conf.d/config file). Usually, these unversioned shared objects can be found in a dedicated subdirectory under /usr/lib or /usr/lib64 (e.g. /usr/lib/purple-2/ is the plugin directory used for libpurple applications). In these cases, the unversioned shared objects do not need to be placed in a -devel package. +The versioned shared library files +(/usr/lib/libfoo.so.3.2.0 and /usr/lib/libfoo.so.3) +are necessary for users to run programs linked against libfoo, +so they belong in the base package. +The other, unversioned, shared library file (/usr/lib/libfoo.so) +is only used to actually link libfoo to code being compiled, +and is not necessary to be installed on a users system. +This means that it belongs in a -devel package. +Please note that in most cases, +only the fully versioned shared library file (/usr/lib/libfoo.so.3.2.0) +is an actual file, all of the other files are symbolic links to it. +When a shared library file is only provided in an unversioned format, +the packager should ask upstream +to consider providing a properly versioned library file. +However, in such cases, if the shared library file is necessary +for users to run programs linked against it, +it must go into the base package. +If upstream versions the shared library file at a future point, +packagers must be careful to move to the versioned layout described above. + +As an additional complication, +some software generates unversioned shared objects +which are not intended to be used as system libraries. +These files are usually plugins or modular functionality +specific to an application, +and are not located in the ld library paths or cache. +This means that they are not located directly in /usr/lib or /usr/lib64, +or in a directory listed as a library path in /etc/ld.so.conf +(or an /etc/ld.so.conf.d/config file). +Usually, these unversioned shared objects can be found +in a dedicated subdirectory under /usr/lib or /usr/lib64 +(e.g. /usr/lib/purple-2/ is the plugin directory +used for libpurple applications). +In these cases, +the unversioned shared objects do not need to be placed in a -devel package. There are some notable exceptions to this packaging model, specifically: -* compilers often include development files in the main package because compilers are themselves only used for software development, thus, a split package model does not make any sense. +* compilers often include development files in the main package +because compilers are themselves only used for software development, +thus, a split package model does not make any sense. -When in doubt as to whether a file belongs in the base package or in -devel, packagers should consider whether the file is necessary to be present for a user to use or execute the functionality in the base package properly, or if it is only necessary for development. If it is only necessary for development, it must go into a -devel package. +When in doubt as to whether a file belongs in the base package or in -devel, +packagers should consider whether the file is necessary to be present +for a user to use or execute the functionality in the base package properly, +or if it is only necessary for development. +If it is only necessary for development, it must go into a -devel package. -As with all Fedora Packaging Guidelines, it is recognized that there are unique situations that fall outside of the boundaries of this model. Should you come across such a case, please open a ticket with the {packaging-committee} and explain it to us so that we can extend the Guidelines to address it. +As with all Fedora Packaging Guidelines, +it is recognized that there are unique situations +that fall outside of the boundaries of this model. +Should you come across such a case, +please open a ticket with the {packaging-committee} +and explain it to us so that we can extend the Guidelines to address it. === Pkgconfig Files (foo.pc) -The placement of pkgconfig(.pc) files depends on their usecase. Since they are almost always used for development purposes, they should be placed in a -devel package. A reasonable exception is when the main package itself is a development tool not installed in a user runtime, e.g. gcc or gdb. +The placement of pkgconfig(.pc) files depends on their usecase. +Since they are almost always used for development purposes, +they should be placed in a -devel package. +A reasonable exception is when the main package itself is a development tool +not installed in a user runtime, e.g. gcc or gdb. == Requiring Base Package From dd5e5b6da6d5a7de20e2fef3ec47e2b7b205cb74 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:01:01 +0000 Subject: [PATCH 12/53] SemBr for Requiring Base Package section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 79f56dc..552994a 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1402,11 +1402,26 @@ not installed in a user runtime, e.g. gcc or gdb. == Requiring Base Package -Subpackages are often extensions for their base package and in that case they should require their base package. It is almost always better to over specify the version, so it is best practice to just use a fully versioned dependency: Requires: %\{name}%\{?_isa} = %\{version}-%\{release}. Devel packages are an example of a package that must require their base packages using a fully versioned dependency. -libs subpackages which only contain shared libraries do not normally need to explicitly depend on %\{name}%\{?_isa} = %\{version}-%\{release}, as they usually do not need the base package to be functional libraries. - -If you end up in a situation where the main package depends on the subpackage and the subpackage on the main package you should think carefully about why you don't have everything in the main package. - -When a subpackage requires the base package, it must do so using a fully versioned arch-specific (for non-noarch packages) dependency: +Subpackages are often extensions for their base package +and in that case they should require their base package. +It is almost always better to over specify the version, +so it is best practice to just use a fully versioned dependency: +Requires: %\{name}%\{?_isa} = %\{version}-%\{release}. +Devel packages are an example of a package +that must require their base packages using a fully versioned dependency. +-libs subpackages which only contain shared libraries +do not normally need to explicitly depend on +%\{name}%\{?_isa} = %\{version}-%\{release}, +as they usually do not need the base package to be functional libraries. + +If you end up in a situation where the main package depends on the subpackage +and the subpackage on the main package +you should think carefully +about why you don't have everything in the main package. + +When a subpackage requires the base package, +it must do so using a fully versioned arch-specific +(for non-noarch packages) dependency: .... Requires: %{name}%{?_isa} = %{version}-%{release} From 56a3abd2bdf305be9538b8359e595a890769561d Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:13:34 +0000 Subject: [PATCH 13/53] SemBr for Shared Libraries section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 552994a..75b7b40 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1447,13 +1447,21 @@ this change might remain unnoticed and cause problems like broken dependencies However, if the use of globs is deemed useful by the packager - for example, if the `Y` and `Z` parts of a library named `libfoo.so.X.Y.Z` change frequently, using something like `libfoo.so.X*` is recommended instead, -since dependent packages usually don't have to be rebuilt for changes of this kind. +since dependent packages usually don't have to be rebuilt +for changes of this kind. === Downstream .so name versioning -In cases where upstream ships unversioned .so *library* (so this is not needed for plugins, drivers, etc.), the packager *MUST* try to convince upstream to start versioning it. +In cases where upstream ships unversioned .so *library* +(so this is not needed for plugins, drivers, etc.), +the packager *MUST* try to convince upstream to start versioning it. -If that fails due to unwilling or unresposive upstream, the packager may start versioning downstream but this must be done with caution and ideally only in rare cases. We don't want to create a library that could conflict with upstream if they later start providing versioned shared libraries. Under no circumstances should the unversioned library be shipped in Fedora. +If that fails due to unwilling or unresposive upstream, +the packager may start versioning downstream +but this must be done with caution and ideally only in rare cases. +We don't want to create a library that could conflict with upstream +if they later start providing versioned shared libraries. +Under no circumstances should the unversioned library be shipped in Fedora. For downstream versioning, the name should be composed like this: @@ -1461,27 +1469,46 @@ For downstream versioning, the name should be composed like this: libfoobar.so.0.n .... -The _n_ should initially be a small integer (for instance, "1"). we use two digits here ("0.n") because the common practice with upstreams is to use only a single digit here. Using multiple digits helps us avoid potential future conflicts. Do not forget to add the SONAME field (see below) to the library. +The _n_ should initially be a small integer (for instance, "1"). +we use two digits here ("0.n") +because the common practice with upstreams is to use only a single digit here. +Using multiple digits helps us avoid potential future conflicts. +Do not forget to add the SONAME field (see below) to the library. -When new versions of the library are released, you should use an {abi-comparison-tool} to check for ABI differences in the built shared libraries. If it detects any incompatibilities, bump the _n_ number by one. +When new versions of the library are released, +you should use an {abi-comparison-tool} to check for ABI differences +in the built shared libraries. +If it detects any incompatibilities, bump the _n_ number by one. ==== SONAME handling -When running an executable linked to shared object with SONAME field, the -dynamic linker checks for this field instead of filename to determine the -object with which it should link. This allows developers to simply link against the -unversioned library symlink and the dynamic linker will link against the -correct object. +When running an executable linked to shared object with SONAME field, +the dynamic linker checks for this field +instead of filename to determine the object with which it should link. +This allows developers to simply link against the unversioned library symlink +and the dynamic linker will link against the correct object. -Keep in mind that although the filename is usually the library's SONAME plus an incrementing minor version there's nothing that intrinsically links these. ldconfig uses the SONAME as the value for a symlink to the actual filename. The dynamic linker then uses that symlink to find the library, disregarding the actual filename. The dynamic linker merely does a simple equality check on the field and does not check for ABI incompatibilities or similar problems. This is the main reason for using an {abi-comparison-tool} and incrementing the SONAME. +Keep in mind that although the filename is usually the library's SONAME +plus an incrementing minor version +there's nothing that intrinsically links these. +ldconfig uses the SONAME as the value for a symlink to the actual filename. +The dynamic linker then uses that symlink to find the library, +disregarding the actual filename. +The dynamic linker merely does a simple equality check on the field +and does not check for ABI incompatibilities or similar problems. +This is the main reason for using an +{abi-comparison-tool} and incrementing the SONAME. -The SONAME field is written to the shared object by linker, using (at least in case of `+ld+`) the `+-soname SONAME+` flags. This can be passed as an option to `+gcc+` like this: +The SONAME field is written to the shared object by linker, +using (at least in case of `+ld+`) the `+-soname SONAME+` flags. +This can be passed as an option to `+gcc+` like this: .... $ gcc $CFLAGS -Wl,-soname,libfoo.so.0.n -o libfoo.so.0.n .... -If you want to check if the SONAME field is set and what value it has, use the `+objdump+` command (from `+binutils+`): +If you want to check if the SONAME field is set and what value it has, +use the `+objdump+` command (from `+binutils+`): .... $ objdump -p /path/to/libfoo.so.0.n | grep 'SONAME' From 8cef62b508ae908c552bf63a2f2faf1f48a8be15 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:23:02 +0000 Subject: [PATCH 14/53] SemBr for Packaging Static Libraries section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 75b7b40..56fe15f 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1517,50 +1517,106 @@ $ objdump -p /path/to/libfoo.so.0.n | grep 'SONAME' [#packaging-static-libraries] == Packaging Static Libraries -Packages including libraries SHOULD exclude static libs as far as possible (e.g., by configuring with _--disable-static_). Applications linking against libraries SHOULD link against shared libraries not static versions. - -Libtool archives, _foo.la_ files, SHOULD NOT be included. Packages using libtool will install these by default even if you configure with _--disable-static_, so they may need to be removed before packaging. Due to bugs in older versions of libtool or bugs in programs that use it, there are times when it is not always possible to remove *.la files without modifying the program. In most cases it is fairly easy to work with upstream to fix these issues. Note that if you are updating a library in a stable release (not devel) and the package already contains *.la files, removing the *.la files SHOULD be treated as an API/ABI change -- i.e., removing them changes the interface that the library gives to the rest of the world thus MUST follow Fedora policies for potentially destabilizing updates. +Packages including libraries SHOULD exclude static libs as far as possible +(e.g., by configuring with _--disable-static_). +Applications linking against libraries SHOULD link against shared libraries +not static versions. + +Libtool archives, _foo.la_ files, SHOULD NOT be included. +Packages using libtool will install these by default +even if you configure with _--disable-static_, +so they may need to be removed before packaging. +Due to bugs in older versions of libtool or bugs in programs that use it, +there are times when it is not always possible to remove *.la files +without modifying the program. +In most cases it is fairly easy to work with upstream to fix these issues. +Note that if you are updating a library in a stable release (not devel) +and the package already contains *.la files, +removing the *.la files SHOULD be treated as an API/ABI change +-- i.e., removing them changes the interface that the library gives +to the rest of the world thus MUST follow Fedora policies +for potentially destabilizing updates. === Packaging Static Libraries * In general, packagers SHOULD NOT ship static libraries. -* We want to be able to track which packages are using static libraries (so we can find which packages need to be rebuilt if a security flaw in a static library is fixed, for instance). There are two scenarios in which static libraries are packaged: - -1. *Static libraries and shared libraries.* In this case, the static libraries MUST be placed in a _*-static_ subpackage. Separating the static libraries from the other development files in _*-devel_ allow us to track this usage by checking which packages `+BuildRequire+` the _*-static_ package. The intent is that whenever possible, packages will move away from using these static libraries, to the shared libraries. If the _*-static_ subpackage requires headers or other files from _*-devel_ in order to be useful it MUST require the _*-devel_ subpackage. -2. *Static libraries only.* When a package only provides static libraries you MAY place all the static library files in the _*-devel_ subpackage. When doing this you also MUST have a virtual Provide for the _*-static_ package: +* We want to be able to track which packages are using static libraries +(so we can find which packages need to be rebuilt +if a security flaw in a static library is fixed, for instance). +There are two scenarios in which static libraries are packaged: + +1. *Static libraries and shared libraries.* +In this case, the static libraries MUST be placed in a _*-static_ subpackage. +Separating the static libraries from the other development files +in _*-devel_ allow us to track this usage by checking which packages +`+BuildRequire+` the _*-static_ package. +The intent is that whenever possible, +packages will move away from using these static libraries, +to the shared libraries. +If the _*-static_ subpackage requires headers or other files +from _*-devel_ in order to be useful it MUST require the _*-devel_ subpackage. +2. *Static libraries only.* +When a package only provides static libraries +you MAY place all the static library files in the _*-devel_ subpackage. +When doing this you also MUST have a virtual Provide +for the _*-static_ package: .... %package devel Provides: foo-static = %{version}-%{release} .... -Packages which explicitly need to link against the static version MUST `+BuildRequire: foo-static+`, so that the usage can be tracked. +Packages which explicitly need to link against the static version +MUST `+BuildRequire: foo-static+`, +so that the usage can be tracked. -* If (and only if) a package has shared libraries which require static libraries to be functional, the static libraries can be included in the _*-devel_ subpackage. The devel subpackage must have a virtual Provide for the _*-static_ package, and packages dependent on it must `+BuildRequire+` the _*-static_ package. +* If (and only if) a package has shared libraries +which require static libraries to be functional, +the static libraries can be included in the _*-devel_ subpackage. +The devel subpackage must have a virtual Provide for the _*-static_ package, +and packages dependent on it must `+BuildRequire+` the _*-static_ package. === Packaging Header Only Libraries -Certain libraries, especially some {cpp} template libraries, are header only libraries. Since the code is generated during compile time, they act just like static libraries and need to be treated as such. +Certain libraries, especially some {cpp} template libraries, +are header only libraries. +Since the code is generated during compile time, +they act just like static libraries and need to be treated as such. -Place all of the header files in the _*-devel_ subpackage and then you must have a virtual Provide for the _*-static_ package: +Place all of the header files in the _*-devel_ subpackage +and then you must have a virtual Provide for the _*-static_ package: .... %package devel Provides: foo-static = %{version}-%{release} .... -Packages which use the header library must `+BuildRequire: foo-static+`, so that the usage can be tracked. +Packages which use the header library must `+BuildRequire: foo-static+`, +so that the usage can be tracked. ==== Do not use noarch -It may be tempting to make the header library package noarch, since the header files themselves are simply text. However, a library should have tests which should be run on all architectures. Also, the install process may modify the installed headers depending on the build architecture. For these reasons, header-only packages must not be marked noarch. +It may be tempting to make the header library package noarch, +since the header files themselves are simply text. +However, a library should have tests which should be run on all architectures. +Also, the install process may modify the installed headers +depending on the build architecture. +For these reasons, header-only packages must not be marked noarch. === Statically Linking Executables -Executables and libraries SHOULD NOT be linked statically against libraries which come from other packages. (It is of course acceptable for files generated during a package's build process to be linked statically against `+.a+` files generated as part of that build process.) - -If it is necessary to link against `+.a+` files from a different package, a build dependency on the `+-static+` package (not just the `+-devel+` package) which provides those files MUST be present so that the usage can be tracked. +Executables and libraries SHOULD NOT be linked statically against libraries +which come from other packages. +(It is of course acceptable for files generated +during a package's build process +to be linked statically against `+.a+` files +generated as part of that build process.) + +If it is necessary to link against `+.a+` files from a different package, +a build dependency on the `+-static+` package +(not just the `+-devel+` package) +which provides those files MUST be present so that the usage can be tracked. [#bundling] == Bundling and Duplication of system libraries From c8a40fa8bcb27ec86acd1fb6a783e58c9246695e Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:27:07 +0000 Subject: [PATCH 15/53] SemBr for Bundling section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 56fe15f..581321d 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1621,30 +1621,64 @@ which provides those files MUST be present so that the usage can be tracked. [#bundling] == Bundling and Duplication of system libraries -Fedora packages SHOULD make every effort to avoid having multiple, separate, upstream projects bundled together in a single package. +Fedora packages SHOULD make every effort to avoid having +multiple, separate, upstream projects +bundled together in a single package. -All packages whose upstreams allow them to be built against system libraries MUST be built against system libraries. +All packages whose upstreams allow them to be built against system libraries +MUST be built against system libraries. In this case, bundled libraries (and/or their source code) MUST be explicitly deleted during `+%prep+`. Build scripts may need to be patched to deal with this situation. -Whenever possible, the patch should conditionalize the use of the bundled libraries, +Whenever possible, +the patch should conditionalize the use of the bundled libraries, so that the patch can be sent upstream for consideration. -All packages whose upstreams have no mechanism to build against system libraries MAY opt to carry bundled libraries, but if they do, they MUST include an indication of what they bundle. This provides a mechanism for locating libraries with bundled code which can, for example, assist in locating packages which may have particular security vulnerabilities. - -To indicate an instance of bundling, first determine the name and version of the bundled library: - -* If the bundled package also exists separately in the distribution, use the name of that package. Otherwise consult the xref:Naming.adoc[Naming Guidelines] to determine an appropriate name for the library as if it were entering the distribution as a separate package. - -* Use the xref:Versioning.adoc[Versioning Guidelines] to determine an appropriate version for the library, if possible. If the library has been forked from an upstream, use the upstream version that was most recently merged in or rebased onto, or the version the original library carried at the time of the fork. - -Then at an appropriate place in your spec, add `+Provides: bundled() = +` where `++` and `++` are the name and version you determined above. If it was not possible to determine a version, use `+Provides: bundled()+` instead. - -In addition to indicating bundling in this manner, packages whose upstreams have no mechanism to build against system libraries must be contacted publicly about a path to supporting system libraries. If upstream refuses, this must be recorded in the spec file, either in comments placed adjacent to the Provides: above, or in an additional file checked into the SCM and referenced by a comment placed adjacent to the `+Provides:+` above. +All packages whose upstreams have no mechanism to build against system libraries +MAY opt to carry bundled libraries, +but if they do, they MUST include an indication of what they bundle. +This provides a mechanism for locating libraries with bundled code which can, +for example, assist in locating packages +which may have particular security vulnerabilities. + +To indicate an instance of bundling, +first determine the name and version of the bundled library: + +* If the bundled package also exists separately in the distribution, +use the name of that package. +Otherwise consult the xref:Naming.adoc[Naming Guidelines] +to determine an appropriate name for the library +as if it were entering the distribution as a separate package. + +* Use the xref:Versioning.adoc[Versioning Guidelines] +to determine an appropriate version for the library, if possible. +If the library has been forked from an upstream, +use the upstream version that was most recently merged in or rebased onto, +or the version the original library carried at the time of the fork. + +Then at an appropriate place in your spec, +add `+Provides: bundled() = +` +where `++` and `++` +are the name and version you determined above. +If it was not possible to determine a version, +use `+Provides: bundled()+` instead. + +In addition to indicating bundling in this manner, +packages whose upstreams have no mechanism to build against system libraries +must be contacted publicly about a path to supporting system libraries. +If upstream refuses, this must be recorded in the spec file, +either in comments placed adjacent to the Provides: above, +or in an additional file checked into the SCM +and referenced by a comment placed adjacent to the `+Provides:+` above. === Avoid bundling of fonts in other packages -Fonts in general-purpose formats such as Type1, OpenType TT (TTF) or OpenType CFF (OTF) are subject to specific packaging guidelines (xref:FontsPolicy.adoc[Packaging/FontsPolicy]), and should always be packaged in the system-wide font repositories instead of private application directories. +Fonts in general-purpose formats such as +Type1, OpenType TT (TTF) or OpenType CFF (OTF) +are subject to specific packaging guidelines +(xref:FontsPolicy.adoc[Packaging/FontsPolicy]), +and should always be packaged in the system-wide font repositories +instead of private application directories. For more information, see: xref:FontsPolicy.adoc[Packaging/FontsPolicy]. == Beware of Rpath From 9c7b3bba6a1ab6e1f94e71a3ec20ccd4b220419c Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:31:34 +0000 Subject: [PATCH 16/53] SemBr for rpath section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 581321d..6c8f749 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1683,9 +1683,22 @@ For more information, see: xref:FontsPolicy.adoc[Packaging/FontsPolicy]. == Beware of Rpath -Sometimes, code will hardcode specific library paths when linking binaries (using the -rpath or -R flag). This is commonly referred to as an rpath. Normally, the dynamic linker and loader (ld.so) resolve the executable's dependencies on shared libraries and load what is required. However, when -rpath or -R is used, the location information is then hardcoded into the binary and is examined by ld.so in the beginning of the execution. Since the Linux dynamic linker is usually smarter than a hardcoded path, we usually do not permit the use of rpath in Fedora. - -There is a tool called _check-rpaths_ which is included in the _rpmdevtools_ package. It is a good idea to add it to the `+%__arch_install_post+` macro in your `+~/.rpmmacros+` config file: +Sometimes, code will hardcode specific library paths when linking binaries +(using the -rpath or -R flag). +This is commonly referred to as an rpath. +Normally, the dynamic linker and loader (ld.so) +resolve the executable's dependencies on shared libraries +and load what is required. +However, when -rpath or -R is used, +the location information is then hardcoded into the binary +and is examined by ld.so in the beginning of the execution. +Since the Linux dynamic linker is usually smarter than a hardcoded path, +we usually do not permit the use of rpath in Fedora. + +There is a tool called _check-rpaths_ which is included +in the _rpmdevtools_ package. +It is a good idea to add it to the `+%__arch_install_post+` macro +in your `+~/.rpmmacros+` config file: .... %__arch_install_post \ @@ -1703,7 +1716,14 @@ Any rpath flagged by check-rpaths *MUST* be removed. === Rpath for Internal Libraries -When a program installs internal libraries they are often not installed in the system path. These internal libraries are only used for the programs that are present in the package (for example, to factor out code that's common to the executables). These libraries are not intended for use outside of the package. When this occurs, it is acceptable for the programs within the package to use an rpath to find these libraries. +When a program installs internal libraries +they are often not installed in the system path. +These internal libraries are only used for the programs +that are present in the package +(for example, to factor out code that's common to the executables). +These libraries are not intended for use outside of the package. +When this occurs, it is acceptable for the programs within the package +to use an rpath to find these libraries. Example: @@ -1718,25 +1738,41 @@ readelf -d /usr/bin/myapp | grep RPATH 0x0000000f (RPATH) Library rpath: [/usr/lib/myapp] .... -TIP: *Non-Internal Libraries*: When programs outside of the package are supposed to link against the library, it is better to use the <> or simply move the libraries into `+%{_libdir}+` instead. That way the dynamic linker can find the libraries without having to link all the programs with an rpath. +TIP: *Non-Internal Libraries*: When programs outside of the package +are supposed to link against the library, +it is better to use the +<> +or simply move the libraries into `+%{_libdir}+` instead. +That way the dynamic linker can find the libraries +without having to link all the programs with an rpath. [#alternatives-to-rpath] === Alternatives to Rpath -Often, rpath is used because a binary is looking for libraries in a non-standard location (standard locations are /lib, /usr/lib, /lib64, /usr/lib64). If you are storing a library in a non-standard location (e.g. /usr/lib/foo/), you should include a custom config file in /etc/ld.so.conf.d/. For example, if I was putting 32 bit libraries of libfoo in /usr/lib/foo, I would want to make a file called "foo32.conf" in /etc/ld.so.conf.d/, which contained the following: +Often, rpath is used because a binary is looking for libraries +in a non-standard location +(standard locations are /lib, /usr/lib, /lib64, /usr/lib64). +If you are storing a library in a non-standard location (e.g. /usr/lib/foo/), +you should include a custom config file in /etc/ld.so.conf.d/. +For example, if I was putting 32 bit libraries of libfoo in /usr/lib/foo, +I would want to make a file called "foo32.conf" +in /etc/ld.so.conf.d/, which contained the following: .... /usr/lib/foo .... -Make sure that you also make a 64bit version of this file (e.g. foo64.conf) as well (unless the package is disabled for 64bit architectures, of course). +Make sure that you also make a 64bit version of this file (e.g. foo64.conf) +as well (unless the package is disabled for 64bit architectures, of course). === Removing Rpath There are several different ways to fix the rpath issue: -* If the application uses configure, try passing the _--disable-rpath_ flag to configure. -* If the application uses a local copy of libtool, add the following lines to the spec after %configure: +* If the application uses configure, +try passing the _--disable-rpath_ flag to configure. +* If the application uses a local copy of libtool, +add the following lines to the spec after %configure: .... %configure @@ -1744,14 +1780,20 @@ sed -i 's|^hardcode_libdir_flag_spec=.*|hardcode_libdir_flag_spec=""|g' libtool sed -i 's|^runpath_var=LD_RUN_PATH|runpath_var=DIE_RPATH_DIE|g' libtool .... -* Sometimes, the code/Makefiles can be patched to remove the _-rpath_ or _-R_ flag from being called. This is not always easy or sane to do, however. -* As a last resort, Fedora has a package called _chrpath_. When this package is installed, you can run `+chrpath --delete+` on the files which contain rpaths. So, in our earlier example, we'd run: +* Sometimes, the code/Makefiles can be patched +to remove the _-rpath_ or _-R_ flag from being called. +This is not always easy or sane to do, however. +* As a last resort, Fedora has a package called _chrpath_. +When this package is installed, +you can run `+chrpath --delete+` on the files which contain rpaths. +So, in our earlier example, we'd run: .... chrpath --delete $RPM_BUILD_ROOT%{_bindir}/xapian-tcpsrv .... -Make sure that you remember to add a *BuildRequires: chrpath* if you end up using this method. +Make sure that you remember to add a +*BuildRequires: chrpath* if you end up using this method. == Configuration files From 1afcc47ec40ba8b734c1fff673a38c954904bf74 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:33:16 +0000 Subject: [PATCH 17/53] SemBr for Configuration files section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 6c8f749..1547875 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1803,7 +1803,8 @@ As a rule of thumb, use `+%config(noreplace)+` instead of plain `+%config+` unless your best, educated guess is that doing so will break things. In other words, -think hard before overwriting local changes in configuration files n package upgrades. +think hard before overwriting local changes +in configuration files n package upgrades. An example case when *not* to use `+noreplace+` is when a package's configuration file changes so that the new package revision wouldn't work @@ -1811,11 +1812,14 @@ with the config file from the previous package revision. Whenever plain `+%config+` is used, add a brief comment to the specfile explaining why. -Don't use %config or %config(noreplace) under /usr. /usr is deemed to not contain configuration files in Fedora. +Don't use %config or %config(noreplace) under /usr. +/usr is deemed to not contain configuration files in Fedora. === Configuration of Package Managers -Packages MUST NOT install repository configuration files which violate the https://docs.fedoraproject.org/en-US/fesco/Third_Party_Repository_Policy/[Third Party Repository Policy], unless those files are installed under `+%{_docdir}+`. +Packages MUST NOT install repository configuration files which violate +the https://docs.fedoraproject.org/en-US/fesco/Third_Party_Repository_Policy/[Third Party Repository Policy], +unless those files are installed under `+%{_docdir}+`. == Per-product Configuration From da9905baea8949cfc98d3e1f8de31b4a1ffa6ceb Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:35:09 +0000 Subject: [PATCH 18/53] SemBr for Per-product Configuration section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 1547875..5116af0 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1823,7 +1823,15 @@ unless those files are installed under `+%{_docdir}+`. == Per-product Configuration -In the Fedora.next world, we will have a set of curated Fedora Products as well as the availability of classic Fedora. Historically, we have maintained a single set of configuration defaults for all Fedora installs but different target use-cases have different needs. Please see the xref:Per-Product_Configuration.adoc[Per-Product Configuration Guidelines] for instructions on how to create packages that need to behave differently between Fedora.next Products. +In the Fedora.next world, +we will have a set of curated Fedora Products +as well as the availability of classic Fedora. +Historically, we have maintained a single set of configuration defaults +for all Fedora installs but different target use-cases have different needs. +Please see the +xref:Per-Product_Configuration.adoc[Per-Product Configuration Guidelines] +for instructions on how to create packages +that need to behave differently between Fedora.next Products. == Initscripts From 9b517fc8fda641658c7542cf90b18295f58b0fef Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:36:41 +0000 Subject: [PATCH 19/53] SemBr for Initscripts section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 5116af0..6024841 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1835,7 +1835,8 @@ that need to behave differently between Fedora.next Products. == Initscripts -SystemV-style initscripts are forbidden in Fedora. Systemd units must be used instead. +SystemV-style initscripts are forbidden in Fedora. +Systemd units must be used instead. == Systemd units From 37776d9c93e1341f721f3042aeac6dea926b2b23 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:37:01 +0000 Subject: [PATCH 20/53] SemBr for Systemd units section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 6024841..54091d6 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1840,7 +1840,8 @@ Systemd units must be used instead. == Systemd units -Detailed guidelines for packaging systemd units and systemd-managed services are xref:Systemd.adoc[here]. +Detailed guidelines for packaging systemd units +and systemd-managed services are xref:Systemd.adoc[here]. == Desktop files From a3bcb2ebc2bc0a201ff25f8ce7c65e44154f7d49 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:40:43 +0000 Subject: [PATCH 21/53] SemBr for Desktop files section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 54091d6..16364a1 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1845,7 +1845,18 @@ and systemd-managed services are xref:Systemd.adoc[here]. == Desktop files -If a package contains a GUI application, then it needs to also include a properly installed .desktop file. For the purposes of these guidelines, a GUI application is defined as any application which draws an X window and runs from within that window. Installed .desktop files MUST follow the https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html[desktop-entry-spec], paying particular attention to validating correct usage of Name, GenericName, https://standards.freedesktop.org/menu-spec/latest/apa.html[Categories], https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt[StartupNotify] entries. +If a package contains a GUI application, +then it needs to also include a properly installed .desktop file. +For the purposes of these guidelines, +a GUI application is defined as any application which draws an X window +and runs from within that window. +Installed .desktop files MUST follow the +https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html[desktop-entry-spec], +paying particular attention to validating correct usage of +Name, GenericName, +https://standards.freedesktop.org/menu-spec/latest/apa.html[Categories], +https://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt[StartupNotify] +entries. === Icon tag in Desktop Files @@ -1859,11 +1870,19 @@ The icon tag can be specified in two ways: `+Icon=comical+` -The short name without file extension is preferred, because it allows for icon theming (it assumes .png by default, then tries .svg and finally .xpm), but either method is acceptable. +The short name without file extension is preferred, +because it allows for icon theming +(it assumes .png by default, then tries .svg and finally .xpm), +but either method is acceptable. === .desktop file creation -If the package doesn't already include and install its own .desktop file, you need to make your own. You can do this by including a .desktop file you create as a Source: (e.g. Source3: %\{name}.desktop) or generating it in the spec file. Here are the contents of a sample .desktop file (comical.desktop): +If the package doesn't already include and install its own .desktop file, +you need to make your own. +You can do this by including a .desktop file you create as a Source: +(e.g. Source3: %\{name}.desktop) +or generating it in the spec file. +Here are the contents of a sample .desktop file (comical.desktop): .... [Desktop Entry] @@ -1879,8 +1898,17 @@ Categories=Graphics; === desktop-file-install usage -It is not simply enough to just include the .desktop file in the package, one MUST run `+desktop-file-install+` (in `+%install+`) OR `+desktop-file-validate+` (in `+%check+` or `+%install+`) and have `+BuildRequires: desktop-file-utils+`, to help ensure .desktop file safety and spec-compliance. `+desktop-file-install+` MUST be used if the package does not install the file or there are changes desired to the .desktop file (such as add/removing categories, etc). `+desktop-file-validate+` MAY be used instead if the .desktop file's content/location does not need modification. Here are some examples of -usage: +It is not simply enough to just include the .desktop file in the package, +one MUST run `+desktop-file-install+` (in `+%install+`) +OR `+desktop-file-validate+` (in `+%check+` or `+%install+`) +and have `+BuildRequires: desktop-file-utils+`, +to help ensure .desktop file safety and spec-compliance. +`+desktop-file-install+` MUST be used if the package does not install the file +or there are changes desired to the .desktop file +(such as add/removing categories, etc). +`+desktop-file-validate+` MAY be used instead +if the .desktop file's content/location does not need modification. +Here are some examples of usage: .... desktop-file-install \ From c4ce15d38e531dce155f48c17e54b7b8c16bcbd0 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:41:19 +0000 Subject: [PATCH 22/53] SemBr for Appdata files section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 16364a1..755a1fe 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1932,7 +1932,8 @@ Do *not* apply a vendor tag to .desktop files (using --vendor). == AppData files -Packages containing graphical applications should include AppData files. See xref:AppData.adoc[Packaging:AppData] for the relevant guidelines. +Packages containing graphical applications should include AppData files. +See xref:AppData.adoc[Packaging:AppData] for the relevant guidelines. == Macros From 1f5b3ba3521b24bee26f4563106794d9959d8672 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:52:10 +0000 Subject: [PATCH 23/53] SemBr for Macros section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 755a1fe..aef53c9 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1937,16 +1937,36 @@ See xref:AppData.adoc[Packaging:AppData] for the relevant guidelines. == Macros -Packagers are strongly encouraged to use macros instead of hard-coded directory names (see xref:RPMMacros.adoc[RPMMacros]). However, in situations where the macro is longer than the path it represents, or situations where the packager feels it is cleaner to use the actual path, the packager is permitted to use the actual path instead of the macro. There are several caveats to this approach: - -* The package must be consistent. For any given path, within the same spec, use either a hard-coded path or a macro, not a combination of the two. -* %\{_libdir} must always be used for binary libraries due to multi-lib, you may not substitute a hard-coded path. - -Macro forms of system executables SHOULD NOT be used except when there is a need to allow the location of those executables to be configurable. For example, `+rm+` should be used in preference to `+%{__rm}+`, but `+%{__python3}+` is acceptable. - -Having macros in a Source: or Patch: line is a matter of style. Some people enjoy the ready readability of a source line without macros. Others prefer the ease of updating for new versions when macros are used. In all cases, remember to be consistent in your spec file and verify that the URLs you list are valid. spectool (from the rpmdevtools package) can aid you in checking that whether the URL contains macros or not. - -If you need to determine the actual string when it contains macros, you can use rpm. For example, to determine the actual Source: value, you can run: +Packagers are strongly encouraged to use macros +instead of hard-coded directory names (see xref:RPMMacros.adoc[RPMMacros]). +However, in situations where the macro is longer than the path it represents, +or situations where the packager feels it is cleaner to use the actual path, +the packager is permitted to use the actual path instead of the macro. +There are several caveats to this approach: + +* The package must be consistent. +For any given path, within the same spec, +use either a hard-coded path or a macro, not a combination of the two. +* %\{_libdir} must always be used for binary libraries due to multi-lib, +you may not substitute a hard-coded path. + +Macro forms of system executables SHOULD NOT be used +except when there is a need to allow the location +of those executables to be configurable. +For example, `+rm+` should be used in preference to `+%{__rm}+`, +but `+%{__python3}+` is acceptable. + +Having macros in a Source: or Patch: line is a matter of style. +Some people enjoy the ready readability of a source line without macros. +Others prefer the ease of updating for new versions when macros are used. +In all cases, remember to be consistent in your spec file +and verify that the URLs you list are valid. +spectool (from the rpmdevtools package) +can aid you in checking that whether the URL contains macros or not. + +If you need to determine the actual string when it contains macros, +you can use rpm. +For example, to determine the actual Source: value, you can run: .... rpm -q --specfile foo.spec --qf "$(grep -i ^Source foo.spec)\n" @@ -1954,11 +1974,24 @@ rpm -q --specfile foo.spec --qf "$(grep -i ^Source foo.spec)\n" === `+%autosetup+` -As an alternative to the usual `+%setup+` macro, the `+%autosetup+` can be used. In addition to the normal %setup tasks, it will apply all defined Patch# items in the spec automatically. It is also capable of handling VCS formatted patch files, but this will require additional BuildRequires, and assumes that _all_ patch files in the spec are formatted for that single VCS type. For this reason, it is not recommended that you specify a VCS with `+%autosetup+`. For more details on proper use of `+%autosetup+`, refer to the https://rpm-software-management.github.io/rpm/manual/autosetup.html[RPM documentation]. +As an alternative to the usual `+%setup+` macro, +the `+%autosetup+` can be used. +In addition to the normal %setup tasks, +it will apply all defined Patch# items in the spec automatically. +It is also capable of handling VCS formatted patch files, +but this will require additional BuildRequires, +and assumes that _all_ patch files in the spec are formatted +for that single VCS type. +For this reason, it is not recommended that you specify a VCS +with `+%autosetup+`. +For more details on proper use of `+%autosetup+`, +refer to the +https://rpm-software-management.github.io/rpm/manual/autosetup.html[RPM documentation]. === Using %\{buildroot} and %\{optflags} vs $RPM_BUILD_ROOT and $RPM_OPT_FLAGS -There are two styles of defining the rpm Build Root and Optimization Flags in a spec file: +There are two styles of defining the rpm Build Root and Optimization Flags +in a spec file: |========================================== | |macro style |variable style @@ -1966,24 +1999,48 @@ There are two styles of defining the rpm Build Root and Optimization Flags in a |Opt. Flags |%\{optflags} |$RPM_OPT_FLAGS |========================================== -There is very little value in choosing one style over the other, since they will resolve to the same values in all scenarios. You should pick a style and use it consistently throughout your packaging. +There is very little value in choosing one style over the other, +since they will resolve to the same values in all scenarios. +You should pick a style and use it consistently throughout your packaging. -Mixing the two styles, while valid, is bad from a QA and usability point of view, and should not be done in Fedora packages. +Mixing the two styles, while valid, +is bad from a QA and usability point of view, +and should not be done in Fedora packages. === Why the %makeinstall macro should not be used -Fedora's RPM includes a `+%makeinstall+` macro but it must *NOT* be used when make install DESTDIR=%\{buildroot} works. %makeinstall is a kludge that can work with Makefiles that don't make use of the DESTDIR variable but it has the following potential issues: - -* `+%makeinstall+` overrides a set of Make variables during "make install" and prepends the %\{buildroot} path, i.e. it performs make prefix="%\{buildroot}%\{_prefix}" libdir="%\{buildroot}%\{_libdir} ...". -* It is error-prone and can have unexpected effects when run against less than perfect Makefiles, e.g., the buildroot path may be included in installed files where variables are substituted at install-time. -* It can trigger unnecessary and wrong rebuilds when executing "make install", since the Make variables have different values compared with the %build section. -* If a package contains libtool archives, it can cause broken *.la files to be installed. - -Instead, Fedora packages should use: `+%make_install+` (Note the "_" !), `+make DESTDIR=%{buildroot} install+` or `+make DESTDIR=$RPM_BUILD_ROOT install+`. Those all do the same thing. +Fedora's RPM includes a `+%makeinstall+` macro +but it must *NOT* be used when make install DESTDIR=%\{buildroot} works. +%makeinstall is a kludge that can work with Makefiles +that don't make use of the DESTDIR variable +but it has the following potential issues: + +* `+%makeinstall+` overrides a set of Make variables during "make install" +and prepends the %\{buildroot} path, +i.e. it performs +make prefix="%\{buildroot}%\{_prefix}" libdir="%\{buildroot}%\{_libdir} ...". +* It is error-prone and can have unexpected effects +when run against less than perfect Makefiles, +e.g., the buildroot path may be included in installed files +where variables are substituted at install-time. +* It can trigger unnecessary and wrong rebuilds when executing "make install", +since the Make variables have different values compared with the %build section. +* If a package contains libtool archives, +it can cause broken *.la files to be installed. + +Instead, Fedora packages should use: `+%make_install+` (Note the "_" !), +`+make DESTDIR=%{buildroot} install+` +or `+make DESTDIR=$RPM_BUILD_ROOT install+`. +Those all do the same thing. === Source RPM Buildtime Macros -All macros in `+Summary:+` and `+%description+` need to be expandable at srpm buildtime. Because SRPMs are built without the package's BuildRequires installed, depending on macros defined outside of the spec file can easily lead to the unexpanded macros showing up in the built SRPM. One way to check is to create a minimal chroot and build the srpm: +All macros in `+Summary:+` and `+%description+` +need to be expandable at srpm buildtime. +Because SRPMs are built without the package's BuildRequires installed, +depending on macros defined outside of the spec file +can easily lead to the unexpanded macros showing up in the built SRPM. +One way to check is to create a minimal chroot and build the srpm: .... mock --init @@ -1995,23 +2052,41 @@ rpmbuild -bs --nodeps [SRPM] rpm -qpiv /builddir/build/SRPMS/[SRPM] .... -Check the `+rpm+` output for unexpanded macros (`+%{foo}+`) or missing information (when`+%{?foo}+` is expanded to the empty string). Even easier is to simply avoid macros in `+Summary:+` and `+%description+` unless they are defined in the current spec file. +Check the `+rpm+` output for unexpanded macros (`+%{foo}+`) +or missing information (when`+%{?foo}+` is expanded to the empty string). +Even easier is to simply avoid macros in `+Summary:+` and `+%description+` +unless they are defined in the current spec file. === Improper use of %_sourcedir -Packages which use files itemized as Source# files, must refer to those files by their `+Source#+` macro name, and must not use `+$RPM_SOURCE_DIR+` or `+%{sourcedir}+` to refer to those files. See xref:RPM_Source_Dir.adoc[Packaging:RPM_Source_Dir] for full details. +Packages which use files itemized as Source# files, +must refer to those files by their `+Source#+` macro name, +and must not use `+$RPM_SOURCE_DIR+` or `+%{sourcedir}+` +to refer to those files. +See xref:RPM_Source_Dir.adoc[Packaging:RPM_Source_Dir] for full details. === Software Collection Macros -{scl-guidelines} are to be kept to separate packages from mainstream packages similar to how xref:MinGW.adoc[MingW packages] are managed. +{scl-guidelines} are to be kept to separate packages from mainstream packages +similar to how xref:MinGW.adoc[MingW packages] are managed. -In the past, SCL macros were allowed to be present inside of mainstream packages if they were not used. Since we're now building SCLs, we are now enforcing a strict separation. Packages *MUST* be updated to restrict SCL macros to only those packages particularly approved as part of an SCL. +In the past, SCL macros were allowed to be present +inside of mainstream packages if they were not used. +Since we're now building SCLs, we are now enforcing a strict separation. +Packages *MUST* be updated to restrict SCL macros +to only those packages particularly approved as part of an SCL. === Packaging of Additional RPM Macros -Additional RPM macros must be stored in %\{_rpmmacrodir}. They must be named using the syntax "macros.$PACKAGE" (e.g. macros.perl). +Additional RPM macros must be stored in %\{_rpmmacrodir}. +They must be named using the syntax "macros.$PACKAGE" (e.g. macros.perl). -Normally, these files are packaged in the -devel subpackage, since they are usually only needed for building other packages. However, in some situations, this is not always ideal and packagers are encouraged to use their best judgment when determining the proper package for these files. RPM macro files MUST NOT be marked as `+%config+`. +Normally, these files are packaged in the -devel subpackage, +since they are usually only needed for building other packages. +However, in some situations, this is not always ideal +and packagers are encouraged to use their best judgment +when determining the proper package for these files. +RPM macro files MUST NOT be marked as `+%config+`. == Scripting inside of spec files From 416a4a1fde3ef075909522d793de9437ab32914b Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:54:22 +0000 Subject: [PATCH 24/53] SemBr for Scripting inside... section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index aef53c9..38c1769 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2090,16 +2090,26 @@ RPM macro files MUST NOT be marked as `+%config+`. == Scripting inside of spec files -Sometimes it is necessary to write a short script (perhaps a one-liner) that is executed in the %prep, %build, or %install sections of a spec file to get some information about the build environment. In order to simplify the dependency graph, spec files should only use the following languages for this purpose: +Sometimes it is necessary to write a short script (perhaps a one-liner) +that is executed in the %prep, %build, or %install sections of a spec file +to get some information about the build environment. +In order to simplify the dependency graph, +spec files should only use the following languages for this purpose: . Python . Perl . Standard programs used in shell programing, for instance gawk or sed . Lua (as supported by the native lua interpreter in rpm) -Additionally, if your package cannot build without a specific scripting language (such as Ruby, or Tcl), and therefore already has a BuildRequires on that language, it may also be called from the spec file. +Additionally, +if your package cannot build without a specific scripting language +(such as Ruby, or Tcl), +and therefore already has a BuildRequires on that language, +it may also be called from the spec file. -Note: If you call Perl or Python in your spec file (and it is not already a BuildRequires for the package), you need to explicitly add a BuildRequires for Perl or Python. +Note: If you call Perl or Python in your spec file +(and it is not already a BuildRequires for the package), +you need to explicitly add a BuildRequires for Perl or Python. == %global preferred over %define From e37013f6b738aa8bbd09208f6ed1d61c0af3b151 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 20:55:30 +0000 Subject: [PATCH 25/53] SemBr for %global preferred... section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 38c1769..1f6f09a 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2113,13 +2113,22 @@ you need to explicitly add a BuildRequires for Perl or Python. == %global preferred over %define -Use `+%global+` instead of `+%define+`, unless you really need only locally defined submacros within other macro definitions (a very rare case). - -Rationale: The two macro defining statements behave the same when they are at the top level of rpm's nesting level. - -But when they are used in nested macro expansions (like in `+%{!?foo: ... }+` constructs, `+%define+` theoretically only lasts until the end brace (local scope), while `+%global+` definitions have global scope. - -Note that %define and %global differ in more ways than just scope: the body of a %define'd macro is lazily expanded (i.e., when used), but the body of %global is expanded at definition time. It's possible to use %%-escaping to force lazy expansion of %global. +Use `+%global+` instead of `+%define+`, +unless you really need only locally defined submacros +within other macro definitions (a very rare case). + +Rationale: The two macro defining statements behave the same +when they are at the top level of rpm's nesting level. + +But when they are used in nested macro expansions +(like in `+%{!?foo: ... }+` constructs, +`+%define+` theoretically only lasts until the end brace (local scope), +while `+%global+` definitions have global scope. + +Note that %define and %global differ in more ways than just scope: +the body of a %define'd macro is lazily expanded (i.e., when used), +but the body of %global is expanded at definition time. +It's possible to use %%-escaping to force lazy expansion of %global. == Handling Locale Files From 6593a5a4666e56c291df032bc0bd27320890f2e6 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 21:08:13 +0000 Subject: [PATCH 26/53] SemBr for Handling Locale Files section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 1f6f09a..e0c215a 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2132,7 +2132,10 @@ It's possible to use %%-escaping to force lazy expansion of %global. == Handling Locale Files -Translation files may be handled by different programs for different frameworks. Make sure you add BuildRequires: for the correct package or else your package could fail to generate translation files in the buildroot. +Translation files may be handled by different programs +for different frameworks. +Make sure you add BuildRequires: for the correct package +or else your package could fail to generate translation files in the buildroot. If the package uses gettext for translations, add @@ -2140,20 +2143,41 @@ If the package uses gettext for translations, add BuildRequires: gettext .... -For Qt-based packages that use the Linguist tool chain, for the localization utilities add +For Qt-based packages that use the Linguist tool chain, +for the localization utilities add .... BuildRequires: qt-devel .... -If you have few enough locale files that they can all go into one package, you can use the `+%find_lang+` macro. (If you need to split your package into separate language packs, please see xref:Langpacks.adoc[the langpack guidelines].) This macro will locate all of the them belonging to your package (by name), and put this list in a file. You can then use that file to include all of the locales. `+%find_lang+` should be run in the %install section of your spec file, after all of the files have been installed into the buildroot. The correct syntax for `+%find_lang+` is usually: +If you have few enough locale files that they can all go into one package, +you can use the `+%find_lang+` macro. +(If you need to split your package into separate language packs, +please see xref:Langpacks.adoc[the langpack guidelines].) +This macro will locate all of the them belonging to your package (by name), +and put this list in a file. +You can then use that file to include all of the locales. +`+%find_lang+` should be run in the %install section of your spec file, +after all of the files have been installed into the buildroot. +The correct syntax for `+%find_lang+` is usually: .... %find_lang %{name} .... -In some cases, the application may use a different "name" for its locales. You may have to look at the locale files and see what they are named. If they are named `+myapp.mo+`, then you will need to pass `+myapp+` to `+%find_lang+` instead of `+%{name}+`. -After `+%find_lang+` is run, it will generate a file in the active directory (by default, the top level of the source dir). This file will be named based on what you passed as the option to the `+%find_lang+` macro. Usually, it will be named `+%{name}.lang+`. You should then use this file in the `+%files+` list to include the locales detected by `+%find_lang+`. To do this, you should include it with the -f parameter to `+%files+`. +In some cases, the application may use a different "name" for its locales. +You may have to look at the locale files and see what they are named. +If they are named `+myapp.mo+`, +then you will need to pass `+myapp+` to `+%find_lang+` instead of `+%{name}+`. +After `+%find_lang+` is run, +it will generate a file in the active directory +(by default, the top level of the source dir). +This file will be named based on what you passed as the option +to the `+%find_lang+` macro. +Usually, it will be named `+%{name}.lang+`. +You should then use this file in the `+%files+` list +to include the locales detected by `+%find_lang+`. +To do this, you should include it with the -f parameter to `+%files+`. .... %files -f %{name}.lang @@ -2161,7 +2185,8 @@ After `+%find_lang+` is run, it will generate a file in the active directory (by ... .... -Note that `+%find_lang+` by default searches for gettext locales, but it can also handle Qt translations, localised manpages and help files. +Note that `+%find_lang+` by default searches for gettext locales, +but it can also handle Qt translations, localised manpages and help files. To process GNOME help files put into `+/usr/share/gnome/help/+` use @@ -2181,7 +2206,8 @@ To process Qt's `+.qm+` binary translation files use %find_lang %{name} --with-qt .... -To process localised manpages (doesn't include the default, non-localised one), use +To process localised manpages +(doesn't include the default, non-localised one), use .... %find_lang %{name} --with-man @@ -2189,9 +2215,12 @@ To process localised manpages (doesn't include the default, non-localised one), To see all the options, run `+/usr/lib/rpm/find-lang.sh+` in the terminal. -Names different from `+%{name}+` (e.g. multiple manpages) must be handled via separate calls to `+%find_lang+`. +Names different from `+%{name}+` (e.g. multiple manpages) +must be handled via separate calls to `+%find_lang+`. -Here is an example of proper usage of `+%find_lang+`, in `+foo.spec+` with the "foo" application localised using gettext and man pages named "bar" instead of "foo": +Here is an example of proper usage of `+%find_lang+`, +in `+foo.spec+` with the "foo" application localised +using gettext and man pages named "bar" instead of "foo": .... Name: foo @@ -2224,10 +2253,13 @@ make DESTDIR=%{buildroot} install === Why do we need to use %find_lang? -Using `+%find_lang+` helps keep the spec file simple, and helps avoid several other packaging mistakes. +Using `+%find_lang+` helps keep the spec file simple, +and helps avoid several other packaging mistakes. -* Packages that use `+%{_datadir}/*+` to grab all the locale files in one line also grab ownership of the locale directories, which is not permitted. -* Most packages that have locales have lots of locales. Using `+%find_lang+` is much easier in the spec file than having to do: +* Packages that use `+%{_datadir}/*+` to grab all the locale files in one line +also grab ownership of the locale directories, which is not permitted. +* Most packages that have locales have lots of locales. +Using `+%find_lang+` is much easier in the spec file than having to do: .... %{_datadir}/locale/ar/LC_MESSAGES/%{name}.mo @@ -2238,9 +2270,14 @@ Using `+%find_lang+` helps keep the spec file simple, and helps avoid several ot ... .... -* As new locale files appear in later package revisions, `+%find_lang+` will automatically include them when it is run, preventing you from having to update the spec any more than is necessary. +* As new locale files appear in later package revisions, +`+%find_lang+` will automatically include them when it is run, +preventing you from having to update the spec any more than is necessary. -Keep in mind that usage of `+%find_lang+` in packages containing locales is a MUST unless the locale files are broken out into langpacks. In which case, you should follow xref:Langpacks.adoc[the langpack guidelines]. +Keep in mind that usage of `+%find_lang+` +in packages containing locales is a MUST +unless the locale files are broken out into langpacks. +In which case, you should follow xref:Langpacks.adoc[the langpack guidelines]. == Log Files From 63c3ba12e5fcb983ea252b8ba63da852e98cfc1d Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 21:17:10 +0000 Subject: [PATCH 27/53] SemBr for Log Files section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index e0c215a..0e2b6b0 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2281,13 +2281,23 @@ In which case, you should follow xref:Langpacks.adoc[the langpack guidelines]. == Log Files -Packages which generate log files should write out their logfiles in a package-specific (and package owned) directory under %\{_localstatedir}/log. Unless the software being packaged rotates its own logs, it must also ship a logrotate config file to rotate its log file(s). +Packages which generate log files should write out their logfiles +in a package-specific (and package owned) directory +under %\{_localstatedir}/log. +Unless the software being packaged rotates its own logs, +it must also ship a logrotate config file to rotate its log file(s). === Logrotate config file -Logrotate config files should be named in a way that matches the daemon/software which is generating the logs, which is usually (though not always) the same name as the package. When unsure, use "%\{name}.conf". These files must be placed in %\{_sysconfdir}/logrotate.d, and should use standard file permissions (0644) and ownership (root:root). +Logrotate config files should be named in a way that matches +the daemon/software which is generating the logs, +which is usually (though not always) the same name as the package. +When unsure, use "%\{name}.conf". +These files must be placed in %\{_sysconfdir}/logrotate.d, +and should use standard file permissions (0644) and ownership (root:root). -Since these are config files, they must be marked as %config(noreplace) in the %files list. +Since these are config files, +they must be marked as %config(noreplace) in the %files list. ==== Example minimal logrotate config file From ebbdf5be70adb6ed6a20a359457a8b94e3d262af Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 21:17:55 +0000 Subject: [PATCH 28/53] SemBr for Timestamps section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 0e2b6b0..7eb51c9 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2312,9 +2312,16 @@ they must be marked as %config(noreplace) in the %files list. == Timestamps -When adding file copying commands in the spec file, consider using a command that preserves the files' timestamps, e.g., `+cp -p+` or `+install -p+`. - -When downloading sources, patches etc., consider using a client that preserves the upstream timestamps. For example `+wget -N+` or `+curl -R+`. To make the change global for wget, add this to your `+~/.wgetrc+`: `+timestamping = on+`, and for curl, add to your `+~/.curlrc+`: `+-R+`. +When adding file copying commands in the spec file, +consider using a command that preserves the files' timestamps, +e.g., `+cp -p+` or `+install -p+`. + +When downloading sources, patches etc., +consider using a client that preserves the upstream timestamps. +For example `+wget -N+` or `+curl -R+`. +To make the change global for wget, +add this to your `+~/.wgetrc+`: `+timestamping = on+`, +and for curl, add to your `+~/.curlrc+`: `+-R+`. == Parallel make From 7436285a13755fdcb2c8ab8a463cd3993e4cbd8b Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 21:29:02 +0000 Subject: [PATCH 29/53] SemBr for Parallel make section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 7eb51c9..2cb602e 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2333,13 +2333,16 @@ Whenever possible, invocations of `+make+` should be done as This generally speeds up builds and especially on SMP machines. -Do make sure, however, that the package builds cleanly this way as some make files do not support parallel building. Therefore you should consider adding +Do make sure, however, that the package builds cleanly this way +as some make files do not support parallel building. +Therefore you should consider adding .... %_smp_mflags -j3 .... -to your `+~/.rpmmacros+` file -- even on UP machines -- as this will expose most of these errors. +to your `+~/.rpmmacros+` file -- even on UP machines -- +as this will expose most of these errors. == Scriptlets From 4e17aa715869d523adc0691000332e9483560c10 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 21:47:14 +0000 Subject: [PATCH 30/53] SemBr for Scriptlets section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 2cb602e..3798fc7 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2346,11 +2346,19 @@ as this will expose most of these errors. == Scriptlets -Great care should be taken when using scriptlets in Fedora packages. If scriptlets are used, those scriptlets must be sane. Some common scriptlets are documented xref:Scriptlets.adoc[here]. +Great care should be taken when using scriptlets in Fedora packages. +If scriptlets are used, those scriptlets must be sane. +Some common scriptlets are documented xref:Scriptlets.adoc[here]. === Scriplets are only allowed to write in certain directories -Build scripts of packages (%prep, %build, %install, %check and %clean) may only alter files (create, modify, delete) under %\{buildroot}, %\{_builddir} and valid temporary locations like /tmp, /var/tmp (or $TMPDIR or %\{_tmppath} as set by the rpmbuild process) according to the following matrix +Build scripts of packages +(%prep, %build, %install, %check and %clean) +may only alter files (create, modify, delete) under +%\{buildroot}, %\{_builddir} +and valid temporary locations like /tmp, /var/tmp +(or $TMPDIR or %\{_tmppath} as set by the rpmbuild process) +according to the following matrix [cols=",,,",] |============================================================================= From 218237bd9a72af83d22f071fd903aa10913fbc4f Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 21:47:31 +0000 Subject: [PATCH 31/53] SemBr for Build packags with separate... section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 3798fc7..9f268ba 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2374,9 +2374,14 @@ Further clarification: That should hold true irrespective of the builder's uid. == Build packages with separate user accounts -When building software, which you have not conducted a full security-audit on, protect sensitive data, such as your GPG private key, in a separate user account. - -The same applies to reviewers/testers. Rebuild src.rpms in a separate account which does not have access to any sensitive data. +When building software, +which you have not conducted a full security-audit on, +protect sensitive data, such as your GPG private key, +in a separate user account. + +The same applies to reviewers/testers. +Rebuild src.rpms in a separate account +which does not have access to any sensitive data. == Relocatable packages From 81cbf9701f279a78e14b60e789a909d6c0983b9c Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 21:49:03 +0000 Subject: [PATCH 32/53] SemBr for Relocatable packages section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 9f268ba..6b119da 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2385,7 +2385,14 @@ which does not have access to any sensitive data. == Relocatable packages -The use of RPM's facility for generating relocatable packages is strongly discouraged. It is difficult to make work properly, impossible to use from the installer or from yum, and not generally necessary if other packaging guidelines are followed. However, in the unlikely event that you have a good reason to make a package relocatable, you MUST state this intent and reasoning in the request for package review. +The use of RPM's facility for generating relocatable packages +is strongly discouraged. +It is difficult to make work properly, +impossible to use from the installer or from yum, +and not generally necessary if other packaging guidelines are followed. +However, in the unlikely event that you have a good reason +to make a package relocatable, +you MUST state this intent and reasoning in the request for package review. == File and Directory Ownership From c1bc625abfa197fcc5944c1383eff33db2dd86de Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 22:38:36 +0000 Subject: [PATCH 33/53] SemBr for File and Directory Ownership section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 6b119da..b67dacb 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2396,30 +2396,58 @@ you MUST state this intent and reasoning in the request for package review. == File and Directory Ownership -Your package should own all of the files that are installed as part of the %install process. +Your package should own all of the files +that are installed as part of the %install process. -In most cases, it should not be necessary for multiple packages to contain identical copies of the same file. However, if it is necessary, multiple packages may contain identical copies of the same file, as long as the following requirements are met: +In most cases, +it should not be necessary for multiple packages +to contain identical copies of the same file. +However, if it is necessary, +multiple packages may contain identical copies of the same file, +as long as the following requirements are met: -* The packages sharing ownership of the identical files are built from a single SRPM. +* The packages sharing ownership of the identical files +are built from a single SRPM. OR -* The packages sharing ownership of the identical files are not in a dependency chain (e.g. if package A requires package B, they should not both contain identical files, either A or B must own the common files, but not both.) +* The packages sharing ownership of the identical files +are not in a dependency chain +(e.g. if package A requires package B, +they should not both contain identical files, +either A or B must own the common files, but not both.) -In addition, identical files are defined as files which are always identical in content, checksum, permissions, and location on the filesystem in each package. +In addition, +identical files are defined as files which are always identical in +content, checksum, permissions, and location on the filesystem +in each package. -Directory ownership is a little more complex than file ownership. Packages must own all directories they put files in, except for: +Directory ownership is a little more complex than file ownership. +Packages must own all directories they put files in, except for: -* any directories owned by the `+filesystem+`, `+man+`, or other explicitly created `+-filesystem+` packages -* any directories owned by other packages in your package's natural dependency chain +* any directories owned by the `+filesystem+`, `+man+`, +or other explicitly created `+-filesystem+` packages +* any directories owned by other packages +in your package's natural dependency chain -In this context, a package's "natural dependency chain" is defined as the set of packages necessary for that package to function normally. To be specific, you do not need to require a package for the sole fact that it happens to own a directory that your package places files in. If your package already requires that package for other reasons, then your package should not also own that directory. +In this context, a package's "natural dependency chain" is defined +as the set of packages necessary for that package to function normally. +To be specific, you do not need to require a package for the sole fact +that it happens to own a directory that your package places files in. +If your package already requires that package for other reasons, +then your package should not also own that directory. -In all cases we are guarding against unowned directories being present on a system. Please see xref:UnownedDirectories.adoc[Packaging:UnownedDirectories] for the details. +In all cases we are guarding against unowned directories +being present on a system. +Please see xref:UnownedDirectories.adoc[Packaging:UnownedDirectories] +for the details. -IMPORTANT: When co-owning directories, you *must* ensure that the ownership and permissions on the directory match in all packages that own it. +IMPORTANT: When co-owning directories, +you *must* ensure that the ownership and permissions +on the directory match in all packages that own it. -Here are examples that describe how to handle most cases of directory ownership. +Here are examples that describe how to handle most cases +of directory ownership. === The directory is wholly contained in your package, or involves core functionality of your package @@ -2429,7 +2457,8 @@ An example: gnucash places many files under the /usr/share/gnucash directory .... -Solution: the `+gnucash+` package should own the `+/usr/share/gnucash+` directory +Solution: the `+gnucash+` package should own +the `+/usr/share/gnucash+` directory === The directory is also owned by a package implementing required functionality of your package @@ -2441,11 +2470,15 @@ gdm places files into /etc/pam.d gdm depends on pam to function normally, and would Require: pam (either implicitly or explicitly) separate from the directory ownership. .... -Solution: the `+pam+` package should own the `+/etc/pam.d+` directory, and `+gdm+` should `+Require:+` the `+pam+` package. +Solution: the `+pam+` package should own the `+/etc/pam.d+` directory, +and `+gdm+` should `+Require:+` the `+pam+` package. === The directory is owned by a package which is not required for your package to function -Some packages create and own directories with the intention of permitting other packages to store appropriate files, but those other packages do not need that original package to be present to function properly. +Some packages create and own directories +with the intention of permitting other packages to store appropriate files, +but those other packages do not need that original package +to be present to function properly. An example: @@ -2456,32 +2489,83 @@ evolution does not need gtk-doc in order to function properly. Nothing in evolution's dependency chain owns /usr/share/gtk-doc/ .... -Solution: the `+evolution+` package should own the `+/usr/share/gtk-doc+` directory. There is no need to add an explicit Requires on gtk-doc solely for the directory ownership. - -Sometimes, it may be preferable for such directories to be owned by an "artificial filesystem" package, such as `+mozilla-filesystem+`. These packages are designed to be explicitly required when other packages store files in their directories, thus, in such situations, these packages should explicitly Require the artificial filesystem package and not multiply own those directories. Packagers should consider the number of affected directories and packages when determining whether to create artificial filesystem packages, and use their own best judgement to determine if this is necessary or not. - -TIP: *Rule of Thumb*: When determining whether this exception applies, packagers and reviewers should ask this question: Do the files in this common directory enhance or add functionality to another package, where that other package is not necessary to be present for the primary functionality of this package? +Solution: the `+evolution+` package should own the +`+/usr/share/gtk-doc+` directory. +There is no need to add an explicit Requires on gtk-doc +solely for the directory ownership. + +Sometimes, it may be preferable for such directories to be owned +by an "artificial filesystem" package, such as `+mozilla-filesystem+`. +These packages are designed to be explicitly required +when other packages store files in their directories, +thus, in such situations, +these packages should explicitly Require the artificial filesystem package +and not multiply own those directories. +Packagers should consider the number of +affected directories and packages +when determining whether to create artificial filesystem packages, +and use their own best judgement to determine if this is necessary or not. + +TIP: *Rule of Thumb*: When determining whether this exception applies, +packagers and reviewers should ask this question: +Do the files in this common directory enhance +or add functionality to another package, +where that other package is not necessary to be present +for the primary functionality of this package? === The package you depend on to provide a directory may choose to own a different directory in a later version and your package will run unmodified with that later version An example involving Perl modules: -Assume `+perl-A-B+` depends on `+perl-A+` and installs files into /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi/A/B. -The base Perl package guarantees that it will own /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi for as long as it remains compatible with version 5.8.8, but a future upgrade of the `+perl-A+` package may install into (and thus own) /usr/lib/perl5/vendor_perl/5.9.0/i386-linux-thread-multi/A. So the `+perl-A-B+` package needs to own /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi/A as well as /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi/A/B in order to maintain proper ownership. +Assume `+perl-A-B+` depends on `+perl-A+` +and installs files into +/usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi/A/B. +The base Perl package guarantees that it will own +/usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi +for as long as it remains compatible with version 5.8.8, +but a future upgrade of the `+perl-A+` package may install into +(and thus own) +/usr/lib/perl5/vendor_perl/5.9.0/i386-linux-thread-multi/A. +So the `+perl-A-B+` package needs to own +/usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi/A +as well as /usr/lib/perl5/vendor_perl/5.8.8/i386-linux-thread-multi/A/B +in order to maintain proper ownership. === Duplicate Files -A Fedora package must not list a file more than once in the spec file's %files listings. If you think your package is a valid exception to this, please bring it to the attention of the Packaging Committee so they can improve on this Guideline. +A Fedora package must not list a file more than once +in the spec file's %files listings. +If you think your package is a valid exception to this, +please bring it to the attention of the Packaging Committee +so they can improve on this Guideline. -One notable exception to this rule is around license texts. There are certain situations where it is required to duplicate the license text across multiple %files section within a package. For more details, please refer to xref:LicensingGuidelines.adoc#subpackage-licensing[Subpackage Licensing]. +One notable exception to this rule is around license texts. +There are certain situations where it is required to duplicate the license text +across multiple %files section within a package. +For more details, please refer to +xref:LicensingGuidelines.adoc#subpackage-licensing[Subpackage Licensing]. === File Permissions -Permissions on files MUST be set properly. Inside of /usr, files should be owned by root:root unless a more specific user or group is needed for security. They MUST be universally readable (and executable if appropriate). Outside of /usr, non-config and non-state files SHOULD be owned by root:root, universally readable (and executable if appropriate) unless circumstances require otherwise. - -The default file mode is 0644 or 0755. Directories should be mode 0755. Most well behaved build scripts and rpm will use these defaults. If the directory needs to be group writable, it SHOULD also have the setgid bit set so that files written there are owned by that group. These directories SHOULD have mode 2775. - -The %defattr directive in the %files list SHOULD ONLY be used when setting a non-default value, or to reset to the default value after having set a non-default value. +Permissions on files MUST be set properly. +Inside of /usr, files should be owned by root:root +unless a more specific user or group is needed for security. +They MUST be universally readable (and executable if appropriate). +Outside of /usr, non-config and non-state files SHOULD be owned by root:root, +universally readable (and executable if appropriate) +unless circumstances require otherwise. + +The default file mode is 0644 or 0755. +Directories should be mode 0755. +Most well behaved build scripts and rpm will use these defaults. +If the directory needs to be group writable, +it SHOULD also have the setgid bit set +so that files written there are owned by that group. +These directories SHOULD have mode 2775. + +The %defattr directive in the %files list +SHOULD ONLY be used when setting a non-default value, +or to reset to the default value after having set a non-default value. == Users and Groups From 3e47606f6a4462f37aa3ef3a1113c87c638a5d55 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 22:46:45 +0000 Subject: [PATCH 34/53] SemBr for Users and Groups section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index b67dacb..5529a57 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2569,9 +2569,14 @@ or to reset to the default value after having set a non-default value. == Users and Groups -Some packages require or benefit from dedicated runtime user and/or group accounts. Guidelines for handling these cases are in a xref:UsersAndGroups.adoc[separate document]. - -Note that system services packaged for Fedora MUST NOT run as the `+nobody+` user, but MUST instead allocate their own system user. +Some packages require or benefit from +dedicated runtime user and/or group accounts. +Guidelines for handling these cases are in a +xref:UsersAndGroups.adoc[separate document]. + +Note that system services packaged for Fedora +MUST NOT run as the `+nobody+` user, +but MUST instead allocate their own system user. == Web Applications From 3cab14f1cf30ae91dcd1130a82c1c43541ee33ee Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 22:47:33 +0000 Subject: [PATCH 35/53] SemBr for Web Applications section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 5529a57..f2002e5 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2580,10 +2580,14 @@ but MUST instead allocate their own system user. == Web Applications -Web applications packaged in Fedora should put their content into /usr/share/%\{name} and NOT into /var/www/. This is done because: - -* /var is supposed to contain variable data files and logs. /usr/share is much more appropriate for this. -* Many users already have content in /var/www, and we do not want any Fedora package to step on top of that. +Web applications packaged in Fedora should put their content into +/usr/share/%\{name} and NOT into /var/www/. +This is done because: + +* /var is supposed to contain variable data files and logs. +/usr/share is much more appropriate for this. +* Many users already have content in /var/www, +and we do not want any Fedora package to step on top of that. * /var/www is no longer specified by the Filesystem Hierarchy Standard == Conflicts From 231944b5cd7a4e6b3308a896babca443cce5527e Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 22:50:23 +0000 Subject: [PATCH 36/53] SemBr for Conflicts section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index f2002e5..7979bcb 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2592,17 +2592,29 @@ and we do not want any Fedora package to step on top of that. == Conflicts -Whenever possible, Fedora packages should avoid conflicting with each other. Unfortunately, this is not always possible. For full details on Fedora's Conflicts policy, see: xref:Conflicts.adoc[Conflicts]. +Whenever possible, Fedora packages should avoid conflicting with each other. +Unfortunately, this is not always possible. +For full details on Fedora's Conflicts policy, see: +xref:Conflicts.adoc[Conflicts]. -Tools such as Alternatives and Environment Modules can also help prevent package conflicts. +Tools such as Alternatives and Environment Modules +can also help prevent package conflicts. === Alternatives -The "alternatives" tool provides a means for parallel installation of packages which provide the same functionality by maintaining sets of symlinks. For full details on how to properly use alternatives, see xref:Alternatives.adoc[Alternatives]. +The "alternatives" tool provides a means for parallel installation of packages +which provide the same functionality by maintaining sets of symlinks. +For full details on how to properly use alternatives, +see xref:Alternatives.adoc[Alternatives]. === Environment Modules -When there are multiple variants that each serve the needs of some user and thus must be available simultaneously by users, the alternatives system simply isn't enough since it is system-wide. In such situations, use of Environment Modules can avoid conflicts. For full details on how to properly use Environment Modules, see xref:EnvironmentModules.adoc[Environment Modules]. +When there are multiple variants that each serve the needs of some user +and thus must be available simultaneously by users, +the alternatives system simply isn't enough since it is system-wide. +In such situations, use of Environment Modules can avoid conflicts. +For full details on how to properly use Environment Modules, +see xref:EnvironmentModules.adoc[Environment Modules]. == Patch Guidelines From 71723cd3df8798fbef4d24de61c5467707d9d442 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:00:35 +0000 Subject: [PATCH 37/53] SemBr for Patch Guidelines section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 7979bcb..88deb82 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2620,14 +2620,21 @@ see xref:EnvironmentModules.adoc[Environment Modules]. === All patches should have an upstream bug link or comment -All patches in Fedora spec files *SHOULD* have a comment above them about their upstream status. Any time you create a patch, it is best practice to file it in an upstream bug tracker, and include a link to that in the comment above the patch. For example: +All patches in Fedora spec files *SHOULD* have a comment above them +about their upstream status. +Any time you create a patch, +it is best practice to file it in an upstream bug tracker, +and include a link to that in the comment above the patch. +For example: .... # https://bugzilla.gnome.org/show_bug.cgi?id=12345 Patch0: gnome-panel-fix-frobnicator.patch .... -The above is perfectly acceptable; but if you prefer, a brief comment about what the patch does above can be helpful: +The above is perfectly acceptable; +but if you prefer, +a brief comment about what the patch does above can be helpful: .... # Don't crash with frobnicator applet @@ -2635,7 +2642,11 @@ The above is perfectly acceptable; but if you prefer, a brief comment about what Patch0: gnome-panel-fix-frobnicator.patch .... -Sending patches upstream and adding this comment will help ensure that Fedora is acting as a good FLOSS citizen (https://docs.fedoraproject.org/en-US/package-maintainers/Staying_Close_to_Upstream_Projects/[Staying Close to Upstream Projects]). It will help others (and even you) down the line in package maintenance by knowing what patches are likely to appear in a new upstream release. +Sending patches upstream and adding this comment +will help ensure that Fedora is acting as a good FLOSS citizen +(https://docs.fedoraproject.org/en-US/package-maintainers/Staying_Close_to_Upstream_Projects/[Staying Close to Upstream Projects]). +It will help others (and even you) down the line in package maintenance +by knowing what patches are likely to appear in a new upstream release. ==== If upstream doesn't have a bug tracker @@ -2662,11 +2673,37 @@ Patch0: jna-jni-path.patch === Applying patches -Normally, patches to a package SHOULD be listed in `+PatchN:+` tags in the RPM spec file and applied using the %patch or %autosetup macros. The files MUST then be checked into the Fedora Package revision control system (currently the git repos on pkgs.fedoraproject.org and commonly accessed via fedpkg). Storing the files in this way allows people to use standard tools to visualize the changes between revisions of the files and track additions and removals without a layer of indirection (as putting them into lookaside would do). - -Applying patches directly from RPM_SOURCE_DIR IS NOT ALLOWED. Please see xref:RPM_Source_Dir.adoc[Packaging:RPM_Source_Dir] for the complete rationale. - -The maintainer MAY deviate from this rule when the upstream of the package provides an extremely large patch or a tarball of patches against a base release. In this case the tarball of patches MAY be listed as a `+SourceN:+` line and the patches would be applied by untarring the archive and then applying the distributed patch(es) using the regular /usr/bin/patch command. Additional patches to the package (for instance, generated by the Fedora maintainer to fix bugs) MUST still be listed in `+PatchN:+` lines and be applied by %patch macros after the patches from the tarball were applied. Maintainers and reviewers should be cautious when exercising this exception as shipping an update as a patchset may be a sign that the patchset is not from the actual upstream or that the patches should be reviewed for correctness rather than simply accepted as the upstream code base. +Normally, patches to a package SHOULD be listed in `+PatchN:+` tags +in the RPM spec file and applied using the %patch or %autosetup macros. +The files MUST then be checked into the Fedora Package revision control system +(currently the git repos on pkgs.fedoraproject.org +and commonly accessed via fedpkg). +Storing the files in this way allows people to use standard tools +to visualize the changes between revisions of the files +and track additions and removals +without a layer of indirection (as putting them into lookaside would do). + +Applying patches directly from RPM_SOURCE_DIR IS NOT ALLOWED. +Please see +xref:RPM_Source_Dir.adoc[Packaging:RPM_Source_Dir] for the complete rationale. + +The maintainer MAY deviate from this rule +when the upstream of the package provides an extremely large patch +or a tarball of patches against a base release. +In this case the tarball of patches MAY be listed as a `+SourceN:+` line +and the patches would be applied by untarring the archive +and then applying the distributed patch(es) +using the regular /usr/bin/patch command. +Additional patches to the package +(for instance, generated by the Fedora maintainer to fix bugs) +MUST still be listed in `+PatchN:+` lines +and be applied by %patch macros +after the patches from the tarball were applied. +Maintainers and reviewers should be cautious when exercising this exception +as shipping an update as a patchset +may be a sign that the patchset is not from the actual upstream +or that the patches should be reviewed for correctness +rather than simply accepted as the upstream code base. == Use of Epochs From 7154adcc876d5fefe8fcf42f85ac659c15ee3e7d Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:02:55 +0000 Subject: [PATCH 38/53] SemBr for Epochs section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 88deb82..a7654de 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2707,7 +2707,13 @@ rather than simply accepted as the upstream code base. == Use of Epochs -RPM supports a field called "Epoch:", which is a numeric field, that, if set, adds another qualifier for RPM to use in doing package comparisons. Specifically, if set, the Epoch of a package trumps all other comparisons (except for a larger Epoch). If Epoch is not set in a package, RPM treats it the same as if it was set to 0. +RPM supports a field called "Epoch:", +which is a numeric field, that, if set, +adds another qualifier for RPM to use in doing package comparisons. +Specifically, if set, the Epoch of a package trumps all other comparisons +(except for a larger Epoch). +If Epoch is not set in a package, +RPM treats it the same as if it was set to 0. Example: @@ -2717,9 +2723,19 @@ Release: 3%{?dist} Epoch: 1 .... -A package with those definitions would be considered greater than a package with a higher version or a higher release. Since Epoch is confusing to humans (and can never be removed from a package once used), it should only be used in Fedora *as a last resort* to resolve upgrade ordering of a package, and should be avoided wherever possible. +A package with those definitions would be considered greater than +a package with a higher version or a higher release. +Since Epoch is confusing to humans +(and can never be removed from a package once used), +it should only be used in Fedora *as a last resort* +to resolve upgrade ordering of a package, +and should be avoided wherever possible. -Also, Epoch complicates normal packaging guidelines. If a package uses an Epoch, it must be referred to in any place where `+%{version}-%{release}+` is used. For example, if a package being depended upon has an Epoch, this must be listed when adding a versioned dependency: +Also, Epoch complicates normal packaging guidelines. +If a package uses an Epoch, +it must be referred to in any place where `+%{version}-%{release}+` is used. +For example, if a package being depended upon has an Epoch, +this must be listed when adding a versioned dependency: .... Requires: foo = %{epoch}:%{version}-%{release} @@ -2727,7 +2743,10 @@ Requires: foo = %{epoch}:%{version}-%{release} === Epochs from Third Party Repositories -If a package to be imported is or previously was present in a publicly accessible repository, the packager can optionally include an Epoch tag equal to that of the most recent version of the third-party package. +If a package to be imported is or previously was present +in a publicly accessible repository, +the packager can optionally include an Epoch tag +equal to that of the most recent version of the third-party package. == Symlinks From 018f4ea05dbcbd8117b05f7851542bd9a89fbe0d Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:09:59 +0000 Subject: [PATCH 39/53] SemBr for Symlinks section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index a7654de..d7c521d 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2750,11 +2750,17 @@ equal to that of the most recent version of the third-party package. == Symlinks -There are two ways of making a symlink, either as a relative link or an absolute link. In Fedora, neither method is required. Packagers should use their best judgement when deciding which method of symlink creation is appropriate. +There are two ways of making a symlink, +either as a relative link or an absolute link. +In Fedora, neither method is required. +Packagers should use their best judgement +when deciding which method of symlink creation is appropriate. === Relative Symlinks -A relative symlink is a symlink which points to a file or directory relative to the position of the symlink. For example, this command would create a relative symlink: +A relative symlink is a symlink which points to a file or directory +relative to the position of the symlink. +For example, this command would create a relative symlink: .... ln -s ../..%{_bindir}/foo %{buildroot}%{_bindir}/bar @@ -2767,13 +2773,16 @@ Pros: Cons: * Much more complicated to create than absolute symlinks -* Relative symlinks may break or behave unexpectedly when a part of a filesystem is mounted to a custom location. +* Relative symlinks may break or behave unexpectedly +when a part of a filesystem is mounted to a custom location. * Relative symlinks may break when bind mounting or symlinking directories. * Relative symlinks may make it more difficult to use rpm system macros. === Absolute Symlinks -An absolute symlink is a symlink which points to an absolute file or directory path. For example, this command would create an absolute symlink: +An absolute symlink is a symlink which points to an absolute file +or directory path. +For example, this command would create an absolute symlink: .... ln -s %{_bindir}/foo %{buildroot}%{_bindir}/bar @@ -2791,9 +2800,11 @@ Cons: == Replacing a symlink to a directory or a directory to any type file -In some cases replacing a symlink to a directory requires special handling. Replacing a directory with any type of file always requires special handling. +In some cases replacing a symlink to a directory requires special handling. +Replacing a directory with any type of file always requires special handling. -See xref:Directory_Replacement.adoc[Packaging:Directory_Replacement] for information about doing this. +See xref:Directory_Replacement.adoc[Packaging:Directory_Replacement] +for information about doing this. == Test Suites From ab2abd94213d03f3ec9348b64e4497b8d723eaf0 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:10:53 +0000 Subject: [PATCH 40/53] SemBr for Test Suites section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index d7c521d..69863e1 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2808,7 +2808,9 @@ for information about doing this. == Test Suites -If the source code of the package provides a test suite, it should be executed in the `+%check+` section, whenever it is practical to do so. +If the source code of the package provides a test suite, +it should be executed in the `+%check+` section, +whenever it is practical to do so. == binfmt.d, sysctl.d and tmpfiles.d From ef10639459711e71e68cb973c1ac8ad96ffe677e Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:12:26 +0000 Subject: [PATCH 41/53] SemBr for binfmt.d, sysctl.d section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 69863e1..e37275f 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2814,21 +2814,29 @@ whenever it is practical to do so. == binfmt.d, sysctl.d and tmpfiles.d -If you install a sysctl configuration snippet foobar.conf into %\{_sysctldir} (/usr/lib/sysctl.d/) you must invoke %sysctl_apply in your %post section: +If you install a sysctl configuration snippet foobar.conf +into %\{_sysctldir} (/usr/lib/sysctl.d/) +you must invoke %sysctl_apply in your %post section: .... %sysctl_apply foobar.conf .... -If you install a binfmt configuration snippet waldo.conf into %\{_binfmtdir} (/usr/lib/binfmt.d/) you must invoke %binfmt_apply in your %post section: +If you install a binfmt configuration snippet waldo.conf +into %\{_binfmtdir} (/usr/lib/binfmt.d/) +you must invoke %binfmt_apply in your %post section: .... %binfmt_apply waldo.conf .... -These have the effect of making the appropriate changes immediately upon package installation instead of requiring a reboot or manual activation. +These have the effect of making the appropriate changes +immediately upon package installation +instead of requiring a reboot or manual activation. -There are specific guidelines for handling tmpfiles.d configurations and directories (in /run and /run/lock): xref:Tmpfiles.d.adoc[Tmpfiles.d]. +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 or Removing Existing Packages From ec0b075e4efa6e35ac0b824799dfb6754add4d9e Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:24:54 +0000 Subject: [PATCH 42/53] SemBr for Renaming/Replacing section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index e37275f..927d989 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2841,39 +2841,127 @@ configurations and directories [#renaming-or-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. +NOTE: https://docs.fedoraproject.org/en-US/package-maintainers/Package_Renaming_Process/[Package Renaming Process] +should be followed when renaming an existing package. -In the event that it becomes necessary to rename or replace an existing package, the new package should make the change transparent to end users to the extent applicable. +In the event that it becomes necessary to rename or replace an existing package, +the new package should make the change transparent to end users +to the extent applicable. -If a package is being renamed without any functional changes, or is a compatible enough replacement to an existing package (where "enough" means that it includes only changes of magnitude that are commonly found in version upgrade changes), provide clean upgrade paths and compatibility with: +If a package is being renamed without any functional changes, +or is a compatible enough replacement to an existing package +(where "enough" means that it includes only changes of magnitude +that are commonly found in version upgrade changes), +provide clean upgrade paths and compatibility with: .... 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. - -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. - -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. - -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 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 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): +$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. + +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. + +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. + +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 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 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): .... 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} .... -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 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 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. - -For packages that are not usually pulled in by using the package name as the dependency such as library only packages (which are pulled in through library soname depenencies), there's usually no need to add the Provides. Note however that the -devel subpackages of lib packages are pulled in as build dependencies using the package name, so adding the Provides is often appropriate there. +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 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 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. + +For packages that are not usually pulled in +by using the package name as the dependency +such as library only packages +(which are pulled in through library soname depenencies), +there's usually no need to add the Provides. +Note however that the -devel subpackages of lib packages +are pulled in as build dependencies using the package name, +so adding the Provides is often appropriate there. == Deprecating Packages From aa081cb7f247238cf4ed5dff5086346f5ff90f43 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:25:15 +0000 Subject: [PATCH 43/53] SemBr for Deprecating Packages section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 927d989..7e259c3 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2965,7 +2965,9 @@ so adding the Provides is often appropriate there. == Deprecating Packages -A procedure exists for indicating that a package is deprecated and may leave the distribution in the future. See xref:deprecating-packages.adoc[Deprecating Packages]. +A procedure exists for indicating that a package is deprecated +and may leave the distribution in the future. +See xref:deprecating-packages.adoc[Deprecating Packages]. == Networking Support From 50165dddd30542fddf30923ad75183d337239e05 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:25:39 +0000 Subject: [PATCH 44/53] SemBr for Networking Support section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 7e259c3..2e90c79 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2971,7 +2971,9 @@ See xref:deprecating-packages.adoc[Deprecating Packages]. == Networking Support -If an application contains native and stable support for both IPv4 and IPv6, and support for IPv6 does not negatively affect IPv4 then both MUST be enabled in the Fedora package. +If an application contains native and stable support for both IPv4 and IPv6, +and support for IPv6 does not negatively affect IPv4 then both MUST be enabled +in the Fedora package. == Cron Files From 37f9ac1f3355f016a48ea51cca02e3df07639ef3 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:25:55 +0000 Subject: [PATCH 45/53] SemBr for Cron Files section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 2e90c79..0ac2f22 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2977,7 +2977,8 @@ in the Fedora package. == Cron Files -For details on how to package cron files, refer to: xref:CronFiles.adoc[CronFiles]. +For details on how to package cron files, refer to: +xref:CronFiles.adoc[CronFiles]. == Security Updates To Resolve Known CVE Issues From de45bafe322b1d3aa3c8cfec1cafd1f1925c6e46 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:26:21 +0000 Subject: [PATCH 46/53] SemBr for Security Updates section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 0ac2f22..51c76d2 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2982,7 +2982,10 @@ xref:CronFiles.adoc[CronFiles]. == Security Updates To Resolve Known CVE Issues -If an update to your package resolves a known security concern (at the time of the update) with a Common Vulnerabilities and Exposures (CVE) number assigned to it, you should mention the CVE number in the RPM changelog entry. +If an update to your package resolves a known security concern +(at the time of the update) +with a Common Vulnerabilities and Exposures (CVE) number assigned to it, +you should mention the CVE number in the RPM changelog entry. == Build time network access From da2ac7443097358cd4c0ad07dea0d7a11ed67877 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:27:10 +0000 Subject: [PATCH 47/53] SemBr for Build time network.... section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 51c76d2..834d77c 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2989,7 +2989,12 @@ you should mention the CVE number in the RPM changelog entry. == Build time network access -Packages in the Fedora buildsystem are built in a mock chroot with no access to the internet. Packages must not depend or or use any network resources that they don't themselves create (i.e., for tests). In no cases should source code be downloaded from any external sources, only from the lookaside cache and/or the Fedora git repository. +Packages in the Fedora buildsystem are built in a mock chroot +with no access to the internet. +Packages must not depend or or use any network resources +that they don't themselves create (i.e., for tests). +In no cases should source code be downloaded from any external sources, +only from the lookaside cache and/or the Fedora git repository. [#bootstrapping] == Bootstrapping From c82c5bc8cdbeababc44bfe136a0a087280a33015 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:28:04 +0000 Subject: [PATCH 48/53] SemBr for Bootstrapping section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 834d77c..c22b8d0 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2999,7 +2999,8 @@ only from the lookaside cache and/or the Fedora git repository. [#bootstrapping] == Bootstrapping -If your package introduces build time circular dependencies, you should use this macro to bootstrap your package: +If your package introduces build time circular dependencies, +you should use this macro to bootstrap your package: .... # When we are bootstrapping, we drop some dependencies, and/or build time tests. @@ -3035,7 +3036,9 @@ TIP: Since Fedora 31, by specifying `+%global __bootstrap %{nil}+` in your spec file. -If your package explicitly `+Provides:+` some functionality that is missing when bootstrapped, then that `+Provides:+` should look like: +If your package explicitly `+Provides:+` some functionality +that is missing when bootstrapped, +then that `+Provides:+` should look like: .... %if %{without bootstrap} @@ -3043,7 +3046,9 @@ Provides: bar(some_functionality) %endif .... -Please note that usage of pre-built binaries in bootstrap still needs an exception from the Packaging Committee as stated in <>. +Please note that usage of pre-built binaries +in bootstrap still needs an exception from the Packaging Committee +as stated in <>. == System cryptographic policies From f300c0838525db0909896cc34aed1e7d9b3d4fba Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:28:43 +0000 Subject: [PATCH 49/53] SemBr for System cryptographic policies section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index c22b8d0..da15475 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -3052,7 +3052,8 @@ as stated in <>. == System cryptographic policies -Applications which make use the SSL or TLS cryptographic protocols MUST follow xref:CryptoPolicies.adoc[Crypto Policies]. +Applications which make use the SSL or TLS cryptographic protocols +MUST follow xref:CryptoPolicies.adoc[Crypto Policies]. == Shebang lines From 063dd0a959e640d73a0537490260c5fd79b7c1a4 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:32:33 +0000 Subject: [PATCH 50/53] SemBr for Shebang lines section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index da15475..276f55c 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -3057,20 +3057,46 @@ MUST follow xref:CryptoPolicies.adoc[Crypto Policies]. == Shebang lines -When packaging script files, where the interpreter to be used is specified in the first line of the script (the shebang line) following `+#!+`, the following rules apply: - -* `+env+`, `+/bin/env+` and `+/usr/bin/env+` MUST NOT be used. The interpreter used to run packaged applications cannot depend upon what the user has in their personal `+$PATH+`. +When packaging script files, +where the interpreter to be used is specified in the first line of the script +(the shebang line) following `+#!+`, +the following rules apply: + +* `+env+`, `+/bin/env+` and `+/usr/bin/env+` MUST NOT be used. +The interpreter used to run packaged applications cannot depend upon +what the user has in their personal `+$PATH+`. * Files which are not installed as executables SHOULD NOT have shebang lines. * Language-specific guidelines may have additional restrictions. -Shebang lines for executable scripts are automatically modified to convert calls to `+env+` into direct use of the proper executable in `+/usr/bin+`. Various checks are also applied to verify that the shebang lines are valid, and the build process can fail as a result of these. Finally, other language-specific modifications may also be made. It is thus generally unnecessary, to manually modify executable scripts to fix `+env+` usage as long as this functionality is enabled. - -If the automatic checks and modifications break a package, there are two primary options: - -* 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. +Shebang lines for executable scripts are automatically modified +to convert calls to `+env+` into direct use of the proper executable +in `+/usr/bin+`. +Various checks are also applied to verify that the shebang lines are valid, +and the build process can fail as a result of these. +Finally, other language-specific modifications may also be made. +It is thus generally unnecessary, to manually modify executable scripts +to fix `+env+` usage as long as this functionality is enabled. + +If the automatic checks and modifications break a package, +there are two primary options: + +* 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. == BRP (BuildRoot Policy) Scripts From 9ba092655288222f6fbb0f85d4f2e575ea5389c2 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:34:03 +0000 Subject: [PATCH 51/53] SemBr for BRP Scripts section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 276f55c..fb1e446 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -3100,9 +3100,16 @@ near the beginning of the specfile. == BRP (BuildRoot Policy) Scripts -BRP scripts are injected at the end of `+%install+` (via the `+%__os_install_post+` macro) and perform some automatic sanity checks of, or adjustments to, files installed in the build root. +BRP scripts are injected at the end of `+%install+` +(via the `+%__os_install_post+` macro) +and perform some automatic sanity checks of, or adjustments to, +files installed in the build root. -All packages SHOULD always be subject to all the BRP scripts, but sometimes it is necessary for a package to opt-out of certain ones. It is possible to disable any BRP script simply by defining the corresponding variable to `+%{nil}+`. For example, to disable the brp-python-bytecompile script: +All packages SHOULD always be subject to all the BRP scripts, +but sometimes it is necessary for a package to opt-out of certain ones. +It is possible to disable any BRP script +simply by defining the corresponding variable to `+%{nil}+`. +For example, to disable the brp-python-bytecompile script: .... # Turn off Python bytecode compilation because this is a Jython @@ -3110,7 +3117,10 @@ All packages SHOULD always be subject to all the BRP scripts, but sometimes it i %global __brp_python_bytecompile %{nil} .... -Any package that disables a BRP script this way MUST also note the reason in an accompanying comment. For a list of the BRP scripts run by default, on F28 and newer invoke: `+fgrep '%__brp_' /usr/lib/rpm/redhat/macros+` +Any package that disables a BRP script this way MUST also note the reason +in an accompanying comment. +For a list of the BRP scripts run by default, +on F28 and newer invoke: `+fgrep '%__brp_' /usr/lib/rpm/redhat/macros+` == Packaging for EPEL From e08620fe786ec721af967586bdcd94a5af2e625a Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:34:41 +0000 Subject: [PATCH 52/53] SemBr for Packaging for EPEL section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index fb1e446..e1c4089 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -3124,7 +3124,13 @@ on F28 and newer invoke: `+fgrep '%__brp_' /usr/lib/rpm/redhat/macros+` == Packaging for EPEL -For the most part, these guidelines and the application-specific guidelines below cover packaging for both Fedora and EPEL. However, there are necessarily some differences. When packaging for EPEL, please also consult https://fedoraproject.org/wiki/EPEL:Packaging[the EPEL packaging guidelines] for additional information. +For the most part, these guidelines +and the application-specific guidelines below +cover packaging for both Fedora and EPEL. +However, there are necessarily some differences. +When packaging for EPEL, please also consult +https://fedoraproject.org/wiki/EPEL:Packaging[the EPEL packaging guidelines] +for additional information. == Domain Specific Guidelines From fdf6ddb66aeb39d75d0242a1e20d9a30960d618a Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 12 2021 23:35:07 +0000 Subject: [PATCH 53/53] SemBr for Domain Specific Guidelines section --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index e1c4089..cb829cc 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -3134,7 +3134,8 @@ for additional information. == Domain Specific Guidelines -Some applications, languages and build systems have specific guidelines written for them, located on their own pages: +Some applications, languages and build systems +have specific guidelines written for them, located on their own pages: * xref:Ada.adoc[Ada] * xref:C_and_C++.adoc[C and {cpp}]