From f467ab437caebd27745e00aa960118c82b50ab26 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 14 2025 18:14:15 +0000 Subject: [PATCH 1/10] Fix section nesting warning. --- diff --git a/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc b/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc index d8d28ea..8942283 100644 --- a/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc +++ b/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc @@ -38,7 +38,7 @@ sed -e "s/@PHP_APIVER@/%{apiver}/;s/@PHP_ZENDVER@/%{zendver}/;s/@PHP_PDOVER@/%{p < %{SOURCE3} > macros.php .... -=== Exceptions +== Exceptions When there is an available list of supplementary source files, it is permissible to use this list in conjunction with `+%{_sourcedir}+` From 5876b1b84d3fc687a42bffc615943989e60ec48f Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 14 2025 18:14:15 +0000 Subject: [PATCH 2/10] Fix section nesting warnings. --- diff --git a/guidelines/modules/ROOT/pages/manual-changelog.adoc b/guidelines/modules/ROOT/pages/manual-changelog.adoc index 45f7def..24494d6 100644 --- a/guidelines/modules/ROOT/pages/manual-changelog.adoc +++ b/guidelines/modules/ROOT/pages/manual-changelog.adoc @@ -42,14 +42,14 @@ You must use one of the following formats: 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 +== 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: -=== Updating and replacing the existing date line +== Updating and replacing the existing date line In this situation, you have added this changelog entry, but have not built the package yet: @@ -83,7 +83,7 @@ you must change the E-V-R and any new entries should be added as described in xref:index.adoc#changelogs[Changelogs]. -=== Repeat the old version release with a new entry +== 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: From f78fa0e39c347d86ee1031d6680fbcfbbc29ee95 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 14 2025 18:14:15 +0000 Subject: [PATCH 3/10] Fix two "invalid style for listing block" warnings. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index bdc50c0..73cbc80 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1155,7 +1155,6 @@ This is described in xref:manual-changelog.adoc[Manual Changelog]. The packager updates package to version 1.0 and creates a commit -[console] ---- $ git show commit 0000000000001234567890ABCDEF000000000000 @@ -1185,7 +1184,6 @@ index 5c77064c03..efcd53a61c 100644 When the package is built, an appropriate changelog entry will be generated. It can be previewed with `rpmautospec generate-changelog`: -[console] ---- $ rpmautospec generate-changelog * Wed Jun 14 2003 Joe Packager - 0.2-1 From 0967a3976377de1587acc027614caa9ad996930e Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 14 2025 18:14:15 +0000 Subject: [PATCH 4/10] Fix eight "section title out of sequence" warnings. --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index 2d3e84e..00d1238 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -298,7 +298,7 @@ Here is a short breakdown of exactly what each macro included in [#ansible_collection_url] -===== `+%ansible_collection_url+` +=== `+%ansible_collection_url+` *Usage:* @@ -320,7 +320,7 @@ See the link:#legacy_macros[Legacy Macros] section for more information. [#ansible_collection_build] -===== `+%ansible_collection_build+` +=== `+%ansible_collection_build+` *Usage:* @@ -334,7 +334,7 @@ This macro simply runs `+ansible-galaxy collection build+`. [#ansible_collection_install] -===== `+%ansible_collection_install+` +=== `+%ansible_collection_install+` *Usage:* @@ -351,7 +351,7 @@ metadata it previously extracted [#ansible_test_unit] -===== `+%ansible_test_unit+` +=== `+%ansible_test_unit+` *Usage:* @@ -367,7 +367,7 @@ script runs ansible-test units with the provided arguments. [#ansible_collection_filelist] -===== `+%{ansible_collection_filelist}+` +=== `+%{ansible_collection_filelist}+` *Usage:* @@ -394,7 +394,7 @@ Packagers are expected to use `+%ansible_collection_install+` and === Legacy macros [#collection_namespace] -===== `+%{collection_namepsace}+` +==== `+%{collection_namepsace}+` *Usage:* [source,rpm-spec] @@ -408,7 +408,7 @@ Now, the macros extract the collection namespace from the `galaxy.yml`. [#collection_name] -===== `+%{collection_name}+` +==== `+%{collection_name}+` *Usage:* @@ -423,7 +423,7 @@ Now, the macros extract the collection name from the `galaxy.yml`. [#ansible_collection_files] -===== `+%{ansible_collection_files}+` +==== `+%{ansible_collection_files}+` *Usage:* From 099f08950f112d62e4307ead3c675747a54060cb Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 14 2025 18:14:15 +0000 Subject: [PATCH 5/10] Fix many unescaped macros which caused warnings. --- diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc index 12914b0..55106a1 100644 --- a/guidelines/modules/ROOT/pages/OCaml.adoc +++ b/guidelines/modules/ROOT/pages/OCaml.adoc @@ -113,7 +113,7 @@ The packager should attempt to ship native code compiled binaries in preference The OCaml native code compiler (`ocamlopt`) contains code generators for popular architectures, but not for every architecture that Fedora might support. On such architectures, the spec file should still build bytecode libraries and binaries. -To test for presence of the native compiler, use the `%{ocaml_native_compiler}` macro. +To test for presence of the native compiler, use the `+%{ocaml_native_compiler}+` macro. Define conditional sections in %build, %install and %files if necessary. For example: @@ -148,12 +148,12 @@ This is because OCaml scripts are recompiled each time they run. The following macros are available to use in spec files: -* `%{ocaml_native_compiler}`: the architectures for which native compilation is available -* `%{ocaml_natdynlink}`: the architectures for which native dynamic linking is available -* `%{ocamldir}`: top-level installation directory for OCaml packages, currently equivalent to `%{_libdir}/ocaml` -* `%{ocaml_files}`: generate a list of installed files, in files named `.ofiles` (for the main package) and .ofiles-devel (for the devel subpackage), unless `-s` or `-n` is given. This macro requires that python3 be available in the buildroot. Flags: +* `+%{ocaml_native_compiler}+`: the architectures for which native compilation is available +* `+%{ocaml_natdynlink}+`: the architectures for which native dynamic linking is available +* `+%{ocamldir}+`: top-level installation directory for OCaml packages, currently equivalent to `+%{_libdir}+/ocaml` +* `+%{ocaml_files}+`: generate a list of installed files, in files named `.ofiles` (for the main package) and .ofiles-devel (for the devel subpackage), unless `-s` or `-n` is given. This macro requires that python3 be available in the buildroot. Flags: ** `-n`: there is no devel subpackage. All files are listed in `.ofiles`. -** `-s`: separate installation; each subdirectory of `%{ocamldir}` is a separate RPM package. For each subdirectory, `.ofiles-` and `.ofiles--devel` is generated (unless `-n` is also given). +** `-s`: separate installation; each subdirectory of `+%{ocamldir}+` is a separate RPM package. For each subdirectory, `.ofiles-` and `.ofiles--devel` is generated (unless `-n` is also given). == Examples @@ -170,7 +170,7 @@ RPM macros are available to make building with dune simple. ** `--`: separate flags for this macro from flags to pass to dune * `%dune_install`: Invoke dune to install all installable artifacts. Flags: ** `-n`: there is no devel subpackage. All files are associated with the main package. -** `-s`: separate installation; each subdirectory of `%{ocamldir}` is a separate RPM package. Otherwise, all files are associated with a single main package. +** `-s`: separate installation; each subdirectory of `+%{ocamldir}+` is a separate RPM package. Otherwise, all files are associated with a single main package. ** `--`: separate flags for this macro from flags to pass to dune * `%dune_check`: Invoke dune to run tests for all installable artifacts. Flags: ** `-j `: number of jobs that can be run in parallel. This is automatically set to `%{?_smp_mflags}`, so is typically used only to eliminate parallelism with `-j 1`. From 202157a17dc9d1c6b3c69a43a0ac6c6943a2fc40 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 14 2025 18:14:15 +0000 Subject: [PATCH 6/10] Properly escape some macros. --- diff --git a/guidelines/modules/ROOT/pages/KDEPackaging.adoc b/guidelines/modules/ROOT/pages/KDEPackaging.adoc index c593a74..e4484fd 100644 --- a/guidelines/modules/ROOT/pages/KDEPackaging.adoc +++ b/guidelines/modules/ROOT/pages/KDEPackaging.adoc @@ -49,16 +49,16 @@ For Plasma 5, the following macros can simply have their version number changed [cols="20%m,30%m,50%",options="header"] |================================= | macro | definition | comment -| +%{_kf6_prefix}+ | %{_prefix} | -| +%{_kf6_archdatadir}+| %{_qt6_archdatadir} | default: `/usr/lib64/qt6` +| +%{_kf6_prefix}+ | +%{_prefix}+ | +| +%{_kf6_archdatadir}+| +%{_qt6_archdatadir}+ | default: `/usr/lib64/qt6` | +%{_kf6_bindir}+ | +%{_kf6_prefix}+/bin | | +%{_kf6_datadir}+ | +%{_datadir}+ | default: `/usr/share` | +%{_kf6_includedir}+ | +%{_includedir}+/KF6 | default: `/usr/include/KF6` | +%{_kf6_libdir}+ | +%{_exec_prefix}/%{_lib}+ | default: `+/usr/%{_lib}+` | +%{_kf6_libexecdir}+ | +%{_libexecdir}+/kf6 | default: `/usr/libexec/kf6` | +%{_kf6_metainfodir}+| +%{_metainfodir}+ | default: `/usr/share/metainfo` -| +%{_kf6_qtplugindir}+| +%{_qt6_plugindir}+ | default: `+/usr/%{_lib}+/qt6/plugins` -| +%{_kf6_plugindir}+ | +%{_qt6_plugindir}+/kf6 | default: `+/usr/%{_lib}+/qt6/plugins/kf6` +| +%{_kf6_qtplugindir}+| +%{_qt6_plugindir}+ | default: `+/usr/%{_lib}/qt6/plugins+` +| +%{_kf6_plugindir}+ | +%{_qt6_plugindir}+/kf6 | default: `+/usr/%{_lib}/qt6/plugins/kf6+` | +%{_kf6_sysconfdir}+ | +%{_sysconfdir}+ | default: `/etc` | +%{_kf6_mandir}+ | +%{_kf6_datadir}+/man | default: `/usr/share/man` | +%{_kf6_qmldir}+ | +%{_kf6_archdatadir}+/qml | default: `/usr/lib64/qt6/qml` From 70b4092edd3bb85e5aebe08eaa1ccdf5495189d2 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 14 2025 18:14:15 +0000 Subject: [PATCH 7/10] Fix an improperly escaped macro. --- diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc index 55106a1..02b2e9b 100644 --- a/guidelines/modules/ROOT/pages/OCaml.adoc +++ b/guidelines/modules/ROOT/pages/OCaml.adoc @@ -150,7 +150,7 @@ The following macros are available to use in spec files: * `+%{ocaml_native_compiler}+`: the architectures for which native compilation is available * `+%{ocaml_natdynlink}+`: the architectures for which native dynamic linking is available -* `+%{ocamldir}+`: top-level installation directory for OCaml packages, currently equivalent to `+%{_libdir}+/ocaml` +* `+%{ocamldir}+`: top-level installation directory for OCaml packages, currently equivalent to `+%{_libdir}/ocaml+` * `+%{ocaml_files}+`: generate a list of installed files, in files named `.ofiles` (for the main package) and .ofiles-devel (for the devel subpackage), unless `-s` or `-n` is given. This macro requires that python3 be available in the buildroot. Flags: ** `-n`: there is no devel subpackage. All files are listed in `.ofiles`. ** `-s`: separate installation; each subdirectory of `+%{ocamldir}+` is a separate RPM package. For each subdirectory, `.ofiles-` and `.ofiles--devel` is generated (unless `-n` is also given). From 69fd751adbeae1a9ffb6c9081729d9fdb95a259d Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 14 2025 18:14:15 +0000 Subject: [PATCH 8/10] Fix several missing escapes. --- diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc index 337d343..fc4f27f 100644 --- a/guidelines/modules/ROOT/pages/Rust.adoc +++ b/guidelines/modules/ROOT/pages/Rust.adoc @@ -407,7 +407,7 @@ This happens automatically when using rust2rpm version 25 or newer. === Package sources Projects from https://crates.io[crates.io] *MUST* be packaged from the sources -that are published there (i.e. by using the `%{crates_source}` macro). +that are published there (i.e. by using the `+%{crates_source}+` macro). If the sources published on https://crates.io[crates.io] do not contain all files that are necessary for creating the package @@ -460,10 +460,10 @@ is almost entirely automated with several RPM macros: This macro *MUST* be called in the `%install` scriptlet for crates that provide a library interface. It runs `cargo package` and installs the resulting directory tree - into `%{buildroot}/%{crate_instdir}` - (i.e. `%{buildroot}/%{cargo_registry}/%{crate}-%{version}/`). + into `+%{buildroot}/%{crate_instdir}+` + (i.e. `+%{buildroot}/%{cargo_registry}/%{crate}-%{version}/+`). For crates that provide `bin` targets, - it installs all built executables into `%{buildroot}/%{_bindir}`. + it installs all built executables into `+%{buildroot}/%{_bindir}+`. If any built executables need to be installed in a different location, they can be moved after calling `%cargo_install`, or `%cargo_install` can be replaced @@ -622,7 +622,7 @@ will be present in all packages for Rust crates with a library interface. The cargo-rpm-macros package includes RPM generators for automatically generating `Provides` and `Requires` for Rust crates that comply with the Packaging Guidelines -(i.e. install their files into the correct location, `%{crate_instdir}`). +(i.e. install their files into the correct location, `+%{crate_instdir}+`). It is recommended to verify that the generated `Provides` and `Requires` are sane - for example, @@ -630,10 +630,10 @@ the following `Provides` and `Requires` must be present to ensure correct inter-subpackage dependencies: * the main `rust-$crate-devel` subpackage - *MUST* provide `crate($crate) = %{version}` + *MUST* provide `+crate($crate) = %{version}+` * the `rust-$crate+$feature-devel` subpackages - *MUST* provide `crate($crate/$feature) = %{version}` - and require `crate($crate) = %{version}` (i.e. `rust-$crate-devel`) + *MUST* provide `+crate($crate/$feature) = %{version}+` + and require `+crate($crate) = %{version}+` (i.e. `rust-$crate-devel`) Additionally, dependencies on external Rust crates must be as expected: @@ -772,13 +772,13 @@ https://pagure.io/fedora-rust/rust2rpm[rust2rpm] has basic support for generating spec files for this type of package by running `rust2rpm --path path/to/Cargo.toml` in unpacked upstream sources. -Packages that fall into this category *MUST NOT* ship crate sources in `%{cargo_registry}`, +Packages that fall into this category *MUST NOT* ship crate sources in `+%{cargo_registry}+`, i.e. they cannot ship `-devel` subpackages that contain crate sources or have subpackages -that have virtual provides for `crate(...) = %{version}`. +that have virtual provides for `+crate(...) = %{version}+`. To prevent the `+%cargo_install+` macro -from installing library sources into `%{cargo_registry}`, +from installing library sources into `+%{cargo_registry}+`, the `%cargo_install_lib` macro can be defined to `0`. When using rust2rpm with a path to a Cargo.toml file this macro definition is injected automatically. @@ -795,7 +795,7 @@ i.e. they *MUST NOT* use a `rust-` prefix for the source package name. The generic guidelines for https://docs.fedoraproject.org/en-US/packaging-guidelines/SourceURL/[referencing sources] apply. -Notably, the `%{crates_source}` macro cannot be used for packages like this. +Notably, the `+%{crates_source}+` macro cannot be used for packages like this. == Rust applications (cargo workspace projects) @@ -817,9 +817,9 @@ by running `rust2rpm --path path/to/Cargo.toml` in unpacked upstream sources, i.e. the `Cargo.toml` file that contains the `[workspace]` table). Packages that fall into this category -*MUST NOT* ship crate sources in `%{cargo_registry}`, +*MUST NOT* ship crate sources in `+%{cargo_registry}+`, i.e. they cannot ship `-devel` subpackages that contain crate sources -or have any subpackages that have virtual provides for `crate(...) = %{version}`. +or have any subpackages that have virtual provides for `+crate(...) = %{version}+`. === Package naming From 23a903106ce88e42086a35a5ca83779e2ae1afd7 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 14 2025 18:14:15 +0000 Subject: [PATCH 9/10] Fix some trailing whitespace. --- diff --git a/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc index 4be5a18..f21deff 100644 --- a/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc +++ b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc @@ -58,17 +58,17 @@ and are a special exception. Drivers have the following requirements: -* The DSO ``SHOULD`` be located in a private directory in /usr/lib[64] +* The DSO ``SHOULD`` be located in a private directory in /usr/lib[64] (i.e. ``%{_libdir}/%{name}/driver``) -* The directory ``SHOULD`` be added to the loader path using a ``ld.conf.d`` configuration +* The directory ``SHOULD`` be added to the loader path using a ``ld.conf.d`` configuration (i.e. ``%{_sysconfdir}/ld.conf.d/%{name}.conf`` definition) Vulkan Layers are loaded by configuration as defined by the Vulkan Loader specification. Layers have the following requirements: -* The DSO ``MUST`` be located in a private directory in /usr/lib[64] +* The DSO ``MUST`` be located in a private directory in /usr/lib[64] (i.e. ``%{_libdir}/%{name}/layer``) and loaded by configuration @@ -86,17 +86,17 @@ OpenXR Runtimes are loaded by configuration as defined by the OpenXR Loader spec Runtimes have the following requirements: -* The DSO ``MUST`` be located in a private directory in /usr/lib[64] +* The DSO ``MUST`` be located in a private directory in /usr/lib[64] (i.e. ``%{_libdir}/%{name}/runtime``) -* The directory ``SHOULD`` be added to the loader path using a ``ld.conf.d`` configuration +* The directory ``SHOULD`` be added to the loader path using a ``ld.conf.d`` configuration (i.e. ``%{_sysconfdir}/ld.conf.d/%{name}.conf``definition) OpenXR Layers are loaded by configuration as defined by the OpenXR Loader specification. Layers have the following requirements: -* The DSO ``MUST`` be located in a private directory in /usr/lib[64] +* The DSO ``MUST`` be located in a private directory in /usr/lib[64] (i.e. ``%{_libdir}/%{name}/layer``) and loaded by configuration From 8bf3d5128b7096b0841f083569e13cccab4228ba Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 14 2025 18:14:15 +0000 Subject: [PATCH 10/10] Fix several improperly escaped macros. --- diff --git a/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc index f21deff..0686479 100644 --- a/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc +++ b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc @@ -1,3 +1,5 @@ +include::{partialsdir}/attributes.adoc[] + = Unversioned Dynamic Shared Objects The standard policy @@ -59,17 +61,17 @@ and are a special exception. Drivers have the following requirements: * The DSO ``SHOULD`` be located in a private directory in /usr/lib[64] -(i.e. ``%{_libdir}/%{name}/driver``) +(i.e. `+%{_libdir}/%{name}/driver+`) * The directory ``SHOULD`` be added to the loader path using a ``ld.conf.d`` configuration -(i.e. ``%{_sysconfdir}/ld.conf.d/%{name}.conf`` definition) +(i.e. `+%{_sysconfdir}/ld.conf.d/%{name}.conf+` definition) Vulkan Layers are loaded by configuration as defined by the Vulkan Loader specification. Layers have the following requirements: * The DSO ``MUST`` be located in a private directory in /usr/lib[64] -(i.e. ``%{_libdir}/%{name}/layer``) +(i.e. `+%{_libdir}/%{name}/layer+`) and loaded by configuration === OpenXR @@ -87,17 +89,17 @@ OpenXR Runtimes are loaded by configuration as defined by the OpenXR Loader spec Runtimes have the following requirements: * The DSO ``MUST`` be located in a private directory in /usr/lib[64] -(i.e. ``%{_libdir}/%{name}/runtime``) +(i.e. `+%{_libdir}/%{name}/runtime+`) * The directory ``SHOULD`` be added to the loader path using a ``ld.conf.d`` configuration -(i.e. ``%{_sysconfdir}/ld.conf.d/%{name}.conf``definition) +(i.e. `+%{_sysconfdir}/ld.conf.d/%{name}.conf+` definition) OpenXR Layers are loaded by configuration as defined by the OpenXR Loader specification. Layers have the following requirements: * The DSO ``MUST`` be located in a private directory in /usr/lib[64] -(i.e. ``%{_libdir}/%{name}/layer``) +(i.e. `+%{_libdir}/%{name}/layer+`) and loaded by configuration === Other Cases