From dcea63f194c5f8b1421e2716a44f2f4b408b20dc Mon Sep 17 00:00:00 2001 From: James Antill Date: Oct 20 2022 17:03:12 +0000 Subject: [PATCH 1/232] Port the merge from: https://pagure.io/packaging-committee/pull-request/1045 From: Jason Tibbitts This extends the existing mention of macro forms of system executables. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 408aa4e..2b33adc 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2007,11 +2007,20 @@ 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. +Macros with names beginning with underscores +are generally considered to be implementation details internal to RPM +and its associated macro packages +and SHOULD NOT be referenced in specfiles +except to set their values in order to influence RPM behavior. +This implies that macro forms of system executables SHOULD NOT be used. +For example, `+rm+` should be used in preference to `+%{__rm}+`. +However, in some cases needed data are simply not provided +under names which are not prefixed with underscores. +If that is the case, the macro named with leading underscores MAY be used. +Authors of macro packages are encouraged +to avoid using leading underscores +when naming macros which are intended to be used in specfiles +(as opposed to being set). 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. From 3bf74ff35396362a31c94a938756c8bf470ddd83 Mon Sep 17 00:00:00 2001 From: Karolina Surma Date: Oct 27 2022 16:20:17 +0000 Subject: [PATCH 2/232] Update %pyproject_check_import description to match reality Newly, %{pyproject_save_files} only saves public modules whose names match any of the MODNAME globs provided as an argument. Related: https://bugzilla.redhat.com/2127958 --- diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc index d399e90..721be9a 100644 --- a/guidelines/modules/ROOT/pages/Python.adoc +++ b/guidelines/modules/ROOT/pages/Python.adoc @@ -1587,7 +1587,8 @@ to ensure the packaged versions of modules are imported. * `+%pyproject_check_import+` + Imports all public modules found by -<>. +<> whose names match +any of the provided `+MODNAME+` globs. + This macro needs to be used with `+%pyproject_save_files+` (use `+%py3_check_import+` in other cases). From e987c4579cce3ae85b500ea8e641ef9fc998e9c4 Mon Sep 17 00:00:00 2001 From: Miro Hrončok Date: Oct 27 2022 16:25:51 +0000 Subject: [PATCH 3/232] Rust: Stop requiring ExclusiveArch: %{rust_arches} Fixes https://pagure.io/packaging-committee/issue/1220 --- diff --git a/guidelines/modules/ROOT/examples/rust-ripgrep.spec b/guidelines/modules/ROOT/examples/rust-ripgrep.spec index 79416b5..ab20cff 100644 --- a/guidelines/modules/ROOT/examples/rust-ripgrep.spec +++ b/guidelines/modules/ROOT/examples/rust-ripgrep.spec @@ -17,8 +17,6 @@ Source: %{crates_source} # * No jemalloc Patch: ripgrep-fix-metadata.diff -ExclusiveArch: %{rust_arches} - BuildRequires: rust-packaging %global _description %{expand: diff --git a/guidelines/modules/ROOT/examples/rust-serde.spec b/guidelines/modules/ROOT/examples/rust-serde.spec index 093cce6..9f7e445 100644 --- a/guidelines/modules/ROOT/examples/rust-serde.spec +++ b/guidelines/modules/ROOT/examples/rust-serde.spec @@ -15,7 +15,6 @@ License: MIT OR Apache-2.0-or-later URL: https://crates.io/crates/serde Source: %{crates_source} -ExclusiveArch: %{rust_arches} %if %{__cargo_skip_build} BuildArch: noarch %endif diff --git a/guidelines/modules/ROOT/examples/rust-yubibomb.spec b/guidelines/modules/ROOT/examples/rust-yubibomb.spec index e92821e..cdd5476 100644 --- a/guidelines/modules/ROOT/examples/rust-yubibomb.spec +++ b/guidelines/modules/ROOT/examples/rust-yubibomb.spec @@ -12,7 +12,6 @@ License: GPL-3.0-only URL: https://crates.io/crates/yubibomb Source: %{crates_source} -ExclusiveArch: %{rust_arches} %if %{__cargo_skip_build} BuildArch: noarch %endif diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc index 982ae55..e8002e1 100644 --- a/guidelines/modules/ROOT/pages/Rust.adoc +++ b/guidelines/modules/ROOT/pages/Rust.adoc @@ -238,10 +238,6 @@ NOTE: When introducing a compatibility package, the packager SHOULD check for example, on other compatibility packages, or on old versions of other packages. If that is the case, the test suite SHOULD be disabled to lower the overall maintenance burden. -== ExclusiveArch - -All rust packages MUST have `+ExclusiveArch: %{rust_arches}+`. - == License for binary packages See xref:legal::license-field.adoc[License: field in Spec file] guidance specific to Rust. From 14b621edeabe961880b4ef269e60488f08a149cc Mon Sep 17 00:00:00 2001 From: Tomas Orsava Date: Nov 08 2022 23:21:11 +0000 Subject: [PATCH 4/232] Explain how Python canonical names are created --- diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc index 721be9a..70bea4c 100644 --- a/guidelines/modules/ROOT/pages/Python.adoc +++ b/guidelines/modules/ROOT/pages/Python.adoc @@ -248,6 +248,9 @@ This normalization is defined in https://www.python.org/dev/peps/pep-0503/#normalized-names[PEP 503], and <> implements it for Fedora packaging. +The canonical name is obtained by switching the project name to lower case +and converting all runs of non-alphanumeric characters to single “-” characters. +Example: “The $$$ Tree” becomes “the-tree”. Elsewhere in this text, the metavariable `+DISTNAME+` refers to the canonical form of the project name. @@ -285,6 +288,7 @@ The Fedora package’s name *SHOULD* contain the <>. If possible, the project name *SHOULD* be the same as the name of the main importable module, +in lowercase, with underscores (`+_+`) replaced by dashes (`+-+`). If the importable module name and the project name do not match, From 097a1a50c87c7616eae78ed47930cbdc0eca1b92 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:35 +0000 Subject: [PATCH 5/232] Initial Ansible Collection guidelines --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 6281361..a0146e8 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -39,6 +39,7 @@ * Programming Languages ** xref:Ada.adoc[Ada] +** xref:Ansible_collections.adoc[Ansible Collections] ** xref:C_and_C++.adoc[C and {cpp}] ** xref:D.adoc[D] ** xref:Fortran.adoc[Fortran] diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc new file mode 100644 index 0000000..b858e2a --- /dev/null +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -0,0 +1,254 @@ += Ansible Collection Packaging Guidelines +:last-reviewed: 2022-08-18 +:toc: + +== Forward + +Ansible collections are packaged units of Ansible content, +including modules and other types of plugins. +Most Ansible Plugins are written in Python or Powershell. + +Some collections are also included in Ansible Community's `+ansible+` +collection bundle, which is packaged in Fedora. +This package depends on `+ansible-core+`, which contains the core engine and +CLI programs (e.g. `+ansible+`, `+ansible-playbook+`). +The `+ansible+` package has a different release cycle than individual collections, +and it may contain older versions of the individual components. +`+ansible+` installs collections in a different namespace and is parallel +installable with individual collections. +The Ansible engine searches for collections in the standalone collections +directory first. + +See https://fedoraproject.org/wiki/Changes/Ansible5[Changes/Ansible5] +for more information about the split between `+ansible+` and `+ansible-core+`. + +== Naming + +Collection packages MUST be named `+ansible-collection-NAMESPACE-NAME+`. +For example, the `+community.general+` collection is named +`+ansible-collection-community-general+`. + +Currently, all collection specfiles must have the following boilerplate: + +[source,RPMSpec] +---- +%global collection_namespace NAMESPACE +%global collection_name NAME +---- + +This is required for packaging macros to work properly, but this may be changed +in the future. + +== Collection Source + +Collection source code MUST be downloaded from the collection's respective +Git forge/other SCM repository. +While the tarballs published to Ansible Galaxy contain all of the +collection's Python/Powershell source code as well as some development files, +they do not include the `+galaxy.yml+` build configuration +and development files (e.g. unit tests) that the author may choose to remove. +Note that the community Collection Guidelines require collections to tag releases +in a public SCM repository. + +Collection packages SHOULD use the `+%ansible_collection_url+` macro +as the package's `+URL:+` field. +This points to the collection's homepage on Ansible Galaxy. + + +== Dependencies + +Collections MUST have `+BuildRequires: +ansible-packaging+`. +`+ansible-packaging+` provides macros and a dependency generator for packaging +Ansible Collections. +It also pulls in `+ansible-core+`, +so `+BuildRequires: ansible-core+` shouldn't be added manually. + +The dependency generator will generate the appropriate dependency on the Ansible engine. +This ensures compatibility with Fedora 35 +which contains the classic `+ansible+` 2.9 package (instead of the collections bundle) +and `+ansible-core+`. Both versions of the Ansible engine support collections, +but they are not parallel installable. +Packages MUST NOT manually `+Require+` `+ansible-core+` or `+ansible+`, +unless they are known to require a specific version, +in which case the appropriate constraints should be used. + +The dependency generator also handles inter-collection dependencies. + +== Build and Installation + +To build the collection artifact, +packages MUST use `+%ansible_collection_build+` in `+%build+`. +`+%ansible_collection_install+` MUST be used in `+%install+` to install the +artifact. + +The `+%ansible_collection_files+` macro MUST be used in `%files` to refer to +the collection. +Note that this is not a macro that is passed to `+%files -f+`. +It needs to be on its own line under `+%files+`. + +== Unit Tests + +As per xref:index.adoc#_test_suites[the general Fedora Packaging Guidelines], +collection packages SHOULD run upstream unit tests in `+%check+` if practical. +Integration tests are impossible to run in the rpm environment. +In order to run unit tests, collections MUST `+BuildRequire+` +`+ansible-packaging+`, which pulls in the necessary dependencies. +Collections may have other testing dependencies, +which are usually specified in `+tests/unit/requirements.txt+`. +The `+%ansible_test_unit+` macro MUST be used to run tests. + +[NOTE] +.EPEL Compatibility +==== +It is currently impossible to run unit tests on EPEL 8 and 9. + +ansible-core in RHEL 8.6 is built against python38. In c8s and the next RHEL +8 minor release, it will be built against python39. The testing dependencies +are not yet packaged for either Python version in EPEL 8. + +ansible-test in RHEL 9.0 still needs python3-mock, but this +requirement has been removed in CentOS 9 Stream. + +The rest of these guidelines are applicable to EPEL 8 and 9, +and `+ansible-packaging+` itself is available there. +==== + +== Unnecessary Files + +By default, collections ship with all of the files in the repository root, +unless they are manually excluded. +Therefore, many collections contain development files that are unwanted by users. + +Packagers SHOULD exclude these files, which SHOULD be done by patching the +collection's `+galaxy.yml+` to add these files to the `+build_ignore+` +configuration. +These files SHOULD NOT be removed with `+rm+`. +See the https://docs.ansible.com/ansible/latest/dev_guide/collections_galaxy_meta.html#collection-galaxy-metadata-structure[Ansible documentation] +for more information on the `+galaxy.yml+` syntax. + +Common development files include: + +* The `+tests+` directory containing unit and integration tests +* SCM configuration such as `+.gitignore+` and `+.keep+` files +* The `+.azure-pipelines+` and `+.github+` directories that contain CI configuration + +These files often have to be removed downstream, as there are some unresolved +issues with pushing these changes to upstream community collections. These +issues are mostly related to the way Ansible Community compiles the `+ansible+` +bundle and are irrelevant in the Fedora context. + +== Shebangs + +Ansible plugins are not executable. However, many of them have `+#!/usr/bin/python+` +shebangs for legacy reasons. +These shebangs MUST be removed for the following reasons: + +1. Non-executable files shouldn't have shebangs +2. Keeping the shebangs results in an unnecessary dependency +on `+python-unversioned-command+`. + +`+%py3_shebang_fix+` MUST NOT be used, as it will break compatibility +with certain Ansible target nodes. +It won't fix the non-executable file issue, either. + +Shebangs can be removed with: + +[source,bash] +---- +find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' + +---- + + +== Documentation and License Files + +License files and documentation for collections are installed to the +collection's directory in `+/usr/share/ansible+`, by default. +Packagers MAY choose to either +mark the license and documentation files in this directory with `+%license+` +and `+%doc+` +or to add the correct paths to `+build_ignore+` in `+galaxy.yml+` and +install them into the standard directories. +Packages should avoid duplicating these files in both places. + +Note that some multi-licensed collections store licenses in a `+LICENSES+` +directory. This whole directory MUST be marked with `+%license+`. + +Refer to the xref:legal::index.adoc[Legal docs] for the rules about +allowed licenses and determining the `+License:+` field. + + +== Example Specfile + +[source,RPMSpec] +---- +# Only run tests where the dependencies are available +%if %{defined fedora} +%bcond_without tests +%else +%bcond_with tests +%endif + +%global collection_namespace community +%global collection_name rabbitmq + +Name: ansible-collection-%{collection_namespace}-%{collection_name} +Version: 1.2.2 +Release: 1%{?dist} +Summary: RabbitMQ collection for Ansible + +# plugins/module_utils/_version.py: Python Software Foundation License version 2 +License: GPL-3.0-or-later and PSF-2.0 +URL: %{ansible_collection_url} +Source0: https://github.com/ansible-collections/community.rabbitmq/archive/%{version}/%{name}-%{version}.tar.gz + +BuildRequires: ansible-packaging +%if %{with tests} +BuildRequires: ansible-packaging-tests +# Collection specific test dependency +BuildRequires: glibc-all-langpacks +%endif + +BuildArch: noarch + +%description +%{summary}. + + +%prep +%autosetup -n community.rabbitmq-%{version} +find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' + +cat >> galaxy.yml << EOF +build_ignore: + # Remove unnecessary development files from the built package. + - tests + - .azure-pipelines + - .gitignore + # Licenses and docs are installed with %%doc and %%license + - PSF-license.txt + - COPYING + - README.md + - CHANGELOG.rst +EOF + + +%build +%ansible_collection_build + + +%install +%ansible_collection_install + + +%if %{with tests} +%check +%ansible_test_unit +%endif + + +%files +%license COPYING PSF-license.txt +%doc README.md CHANGELOG.rst +%{ansible_collection_files} + +%changelog +---- From 43f3f9c6e2e90bffbd7a85634a8a719f5cc9fe6c Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:35 +0000 Subject: [PATCH 6/232] Explicitly state that all collections can be packaged --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index b858e2a..4f236d5 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -10,7 +10,10 @@ Most Ansible Plugins are written in Python or Powershell. Some collections are also included in Ansible Community's `+ansible+` collection bundle, which is packaged in Fedora. -This package depends on `+ansible-core+`, which contains the core engine and +All collections, whether or not they are included in the `+ansible+` package, +MAY be packaged in Fedora. + +`+ansible+` depends on `+ansible-core+`, which contains the core engine and CLI programs (e.g. `+ansible+`, `+ansible-playbook+`). The `+ansible+` package has a different release cycle than individual collections, and it may contain older versions of the individual components. From 53b39a90f7512a4a1a205a8c97b8fbd8603e7c61 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:35 +0000 Subject: [PATCH 7/232] ansible example: Use patch file to edit metadata We should advise packagers to use actual patch files, not hacky sed'ing. --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index 4f236d5..c88c10c 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -203,6 +203,9 @@ Summary: RabbitMQ collection for Ansible License: GPL-3.0-or-later and PSF-2.0 URL: %{ansible_collection_url} Source0: https://github.com/ansible-collections/community.rabbitmq/archive/%{version}/%{name}-%{version}.tar.gz +# Patch galaxy.yml to exclude unnecessary files from the built collection. +# This is a downstream only patch. +Patch0: build_ignore.patch BuildRequires: ansible-packaging %if %{with tests} @@ -218,7 +221,7 @@ BuildArch: noarch %prep -%autosetup -n community.rabbitmq-%{version} +%autosetup -n community.rabbitmq-%{version} -p1 find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' + cat >> galaxy.yml << EOF build_ignore: @@ -255,3 +258,27 @@ EOF %changelog ---- + +build_ignore.patch: + +[source, patch] +---- +diff --git a/galaxy.yml b/galaxy.yml +index 0b37162..acd029a 100644 +--- a/galaxy.yml ++++ b/galaxy.yml +@@ -13,3 +13,13 @@ repository: https://github.com/ansible-collections/community.rabbitmq + documentation: https://docs.ansible.com/ansible/latest/collections/community/rabbitmq/ + homepage: https://github.com/ansible-collections/community.rabbitmq + issues: https://github.com/ansible-collections/community.rabbitmq/issues ++build_ignore: ++ # Remove unnecessary development files from the built package. ++ - tests ++ - .azure-pipelines ++ - .gitignore ++ # Licenses and docs are installed with %%doc and %%license ++ - PSF-license.txt ++ - COPYING ++ - README.md ++ - CHANGELOG.rst +---- From 459deea93c338697c1de1158cc5bb8a820253acd Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:35 +0000 Subject: [PATCH 8/232] ansible: Expand Dependencies guidelines This expands the Dependencies section to discuss runtime collection dependencies. --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index c88c10c..e2f1bfb 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -60,12 +60,16 @@ This points to the collection's homepage on Ansible Galaxy. == Dependencies +=== Buildtime + Collections MUST have `+BuildRequires: +ansible-packaging+`. `+ansible-packaging+` provides macros and a dependency generator for packaging Ansible Collections. It also pulls in `+ansible-core+`, so `+BuildRequires: ansible-core+` shouldn't be added manually. +=== Runtime + The dependency generator will generate the appropriate dependency on the Ansible engine. This ensures compatibility with Fedora 35 which contains the classic `+ansible+` 2.9 package (instead of the collections bundle) @@ -77,6 +81,37 @@ in which case the appropriate constraints should be used. The dependency generator also handles inter-collection dependencies. +Ansible collections may contain various plugins that have +various external dependencies. +The Ansible dev guide +https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_best_practices.html#importing-and-using-shared-code[mandates] +that plugins fail cleanly if these dependencies. +Therefore, collection packages SHOULD weakly depend on these external libraries, +i.e. use Recommends instead of Requires. + +Module dependencies are only needed on the target node, +not the controller node. +Therefore, collection packages SHOULD NOT depend on these dependencies at all, +weakly or strongly. +Users are responsible for installing these dependencies on the target host. +Modules that are intended to be used with `+delegate_to: localhost+` are an +exception to this rule. + +The situation is a bit different for controller plugins, such as +filter plugins, lookup plugins, connection plugins, and inventory plugins. +Collections MAY add `+Recommends+` for these dependencies. +However, packagers should use discretion when adding any type of dependency +and only do so when it is required for +the central functionality of the collection. +For instance, it makes sense for `+ansible-collection-community-docker+` +to Recommend python3-docker. +On the other hand, it wouldn't make sense for the larger, more general +ansible-collection-community-general collection to Recommend `+python3-redis+` +for the `+redis+` lookup plugin. +This guidelines seeks to prevent ballooning collection packages. +`+ansible-core+` and `+ansible+` follows this same principal. + + == Build and Installation To build the collection artifact, From f7283e0398bb1e84e739d4abc8b040984b3ac965 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 9/232] ansible: Remove section about boilerplate --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index e2f1bfb..a3c180c 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -31,16 +31,6 @@ Collection packages MUST be named `+ansible-collection-NAMESPACE-NAME+`. For example, the `+community.general+` collection is named `+ansible-collection-community-general+`. -Currently, all collection specfiles must have the following boilerplate: - -[source,RPMSpec] ----- -%global collection_namespace NAMESPACE -%global collection_name NAME ----- - -This is required for packaging macros to work properly, but this may be changed -in the future. == Collection Source From c1ee7274ffa621c5502c7520b28645d7ca15bd67 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 10/232] ansible: Document %ansible_collection_filelist --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index a3c180c..d4b5a48 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -109,10 +109,9 @@ packages MUST use `+%ansible_collection_build+` in `+%build+`. `+%ansible_collection_install+` MUST be used in `+%install+` to install the artifact. -The `+%ansible_collection_files+` macro MUST be used in `%files` to refer to +Packagers SHOULD use `+%files -f %{ansible_collection_filelist}+` to install the collection. -Note that this is not a macro that is passed to `+%files -f+`. -It needs to be on its own line under `+%files+`. +The `+%{ansible_collection_filelist}+` is populated by `+%ansible_collection_install+`. == Unit Tests From 6eaa5b5f6107306a53bff010d666f58ecd45cb47 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 11/232] ansible: Update example specfile - Stop using "legacy" macros - Fix patching mistake --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index d4b5a48..d2baaf0 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -215,18 +215,16 @@ allowed licenses and determining the `+License:+` field. %bcond_with tests %endif -%global collection_namespace community -%global collection_name rabbitmq - -Name: ansible-collection-%{collection_namespace}-%{collection_name} +Name: ansible-collection-community-rabbitmq Version: 1.2.2 Release: 1%{?dist} Summary: RabbitMQ collection for Ansible # plugins/module_utils/_version.py: Python Software Foundation License version 2 License: GPL-3.0-or-later and PSF-2.0 -URL: %{ansible_collection_url} -Source0: https://github.com/ansible-collections/community.rabbitmq/archive/%{version}/%{name}-%{version}.tar.gz +URL: %{ansible_collection_url community rabbitmq} +%global forgeurl https://github.com/ansible-collections/community.rabbitmq +Source0: %{fogeurl}/archive/%{version}/%{name}-%{version}.tar.gz # Patch galaxy.yml to exclude unnecessary files from the built collection. # This is a downstream only patch. Patch0: build_ignore.patch @@ -247,18 +245,6 @@ BuildArch: noarch %prep %autosetup -n community.rabbitmq-%{version} -p1 find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' + -cat >> galaxy.yml << EOF -build_ignore: - # Remove unnecessary development files from the built package. - - tests - - .azure-pipelines - - .gitignore - # Licenses and docs are installed with %%doc and %%license - - PSF-license.txt - - COPYING - - README.md - - CHANGELOG.rst -EOF %build @@ -275,10 +261,9 @@ EOF %endif -%files +%files -f %{ansible_collection_filelist} %license COPYING PSF-license.txt %doc README.md CHANGELOG.rst -%{ansible_collection_files} %changelog ---- From 9bc48f372e43111bd1f12ec2e232acb7a808f7b5 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 12/232] ansible: Add new Macro breakdown section --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index d2baaf0..f07b558 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -291,3 +291,153 @@ index 0b37162..acd029a 100644 + - README.md + - CHANGELOG.rst ---- + + +== Macro Breakdown + +Here is a short breakdown of exactly what each macro included in +`+ansible-packaging+` does. + + +[#ansible_collection_url] +===== `+%ansible_collection_url+` + +*Usage:* + +[source,RPMSpec] +---- +URL: %{ansible_collection_url NAMESPACE NAME} +---- + +This macro points to a collection's Ansible Galaxy page. +It is intended to be used for the `+URL:+` tag in the specfile preamble. +It takes the collection namespace and collection name as arguments. + +If no arguments are passed to this macro, it falls back to the values +of `+%{collection_namespace}+` and `+%{collection_name}+` if they are set in the specfile. +New packages SHOULD explicitly pass the namespace and name as arguments. +The fallback may be removed in the future. +See the link:#legacy_macros[Legacy Macros] section for more information. + + +[#ansible_collection_build] + +===== `+%ansible_collection_build+` + +*Usage:* + +[source,RPMSpec] +---- +%build +%ansible_collection_build +---- + +This macro simply runs `+ansible-galaxy collection build+`. + + +[#ansible_collection_install] +===== `+%ansible_collection_install+` + +*Usage:* + +[source,RPMSpec] +---- +%install +%ansible_collection_install +---- + +This macro pulls out the collection namespace, name, and version from `+galaxy.yml+` +and then uses it to run `+ansible-galaxy collection install+`. +After that, it writes out `+%{ansible_collection_filelist}` based on the +metadata it previously extracted + + +[#ansible_test_unit] +===== `+%ansible_test_unit+` + +*Usage:* + +[source,RPMSpec] +---- +%check +%ansible_test_unit +---- +This macro parses galaxy.yml to determine the collection namespace and name +that's needed to create the directory structure that ansible-test expects. +After creating a temporary build directory with the needed structure, the +script runs ansible-test units with the provided arguments. + + +[#ansible_collection_filelist] +===== `+%{ansible_collection_filelist}+` + +*Usage:* + +[source,RPMSpec] +---- +%files -f %{ansible_collection_filelist} +%doc ... +%license ... +---- + +This macro points a file list that's written out by `+%ansible_collection_install+`. +Currently, it only contains a single entry to own the collection's entire +directory in `+%{ansible_collections_dir}+` + + +[#ansible_collections_dir] + +This macro expands to `+%{_datadir}/ansible/collections/ansible_collections+`. +It is used internally by the other macros. +Packagers are expected to use `+%ansible_collection_install+` and +`+%ansible_collection_filelist+` instead of directly referencing this directory. + +[#legacy_macros] +=== Legacy macros + +[#collection_namespace] +===== `+%collection_namepsace+` +*Usage:* + +[source,RPMSpec] +---- +%global collection_namespace NAMESPACE +---- + +The ansible-packaging macros previously required +packagers to manually set `+%collection_namespace+` in specfiles. +Now, the macros extract the collection namespace from the `galaxy.yml`. + + +[#collection_name] +===== `+%collection_name+` + +*Usage:* + +[source,RPMSpec] +---- +%global collection_name NAME +---- + +The ansible-packaging macros previously required +packagers to manually set `+%collection_namespace+` in specfiles. +Now, the macros extract the collection namespace from the `galaxy.yml`. + + +[#ansible_collection_files] +===== `+%{ansible_collection_files}+` + +*Usage:* + +[source,RPMSpec] +---- +%files +%doc ... +%license ... +%{ansible_collection_files} +---- + +New specfiles should use `+%files -f %{ansible_collection_filelist}+` instead +of this macro. +`+%{ansible_collection_files}+` requires setting +`+%collection_namespace+` and `+%collection_name+`. From 8d2db8a73479b14b7b8556b0bafeb3b499956951 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 13/232] ansible: Clarify %ansible_collection_url guideline --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index f07b558..fa984ec 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -43,8 +43,8 @@ and development files (e.g. unit tests) that the author may choose to remove. Note that the community Collection Guidelines require collections to tag releases in a public SCM repository. -Collection packages SHOULD use the `+%ansible_collection_url+` macro -as the package's `+URL:+` field. +Collection packages SHOULD use `+%{ansible_collection_url NAMESPACE NAME}+` +as the package's `+URL:+`. This points to the collection's homepage on Ansible Galaxy. From 0b0931056192c3b38182d9909184a9e1ab62a57c Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 14/232] ansible: Fix wording and typos --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index fa984ec..5053721 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -1,5 +1,5 @@ = Ansible Collection Packaging Guidelines -:last-reviewed: 2022-08-18 +:last-reviewed: 2022-09-25 :toc: == Forward @@ -28,7 +28,7 @@ for more information about the split between `+ansible+` and `+ansible-core+`. == Naming Collection packages MUST be named `+ansible-collection-NAMESPACE-NAME+`. -For example, the `+community.general+` collection is named +For example, the `+community.general+` collection package is named `+ansible-collection-community-general+`. @@ -40,8 +40,8 @@ While the tarballs published to Ansible Galaxy contain all of the collection's Python/Powershell source code as well as some development files, they do not include the `+galaxy.yml+` build configuration and development files (e.g. unit tests) that the author may choose to remove. -Note that the community Collection Guidelines require collections to tag releases -in a public SCM repository. +Note that the Ansible Community collection requirements mandate that +collections tag releases in a public SCM repository. Collection packages SHOULD use `+%{ansible_collection_url NAMESPACE NAME}+` as the package's `+URL:+`. @@ -52,11 +52,11 @@ This points to the collection's homepage on Ansible Galaxy. === Buildtime -Collections MUST have `+BuildRequires: +ansible-packaging+`. +Collections MUST have `+BuildRequires: ansible-packaging+`. `+ansible-packaging+` provides macros and a dependency generator for packaging Ansible Collections. It also pulls in `+ansible-core+`, -so `+BuildRequires: ansible-core+` shouldn't be added manually. +so `+BuildRequires: ansible-core+` SHOULD NOT be added manually. === Runtime @@ -67,20 +67,23 @@ and `+ansible-core+`. Both versions of the Ansible engine support collections, but they are not parallel installable. Packages MUST NOT manually `+Require+` `+ansible-core+` or `+ansible+`, unless they are known to require a specific version, -in which case the appropriate constraints should be used. +in which case the appropriate version constraints should be used. The dependency generator also handles inter-collection dependencies. +==== External dependencies of plugins + Ansible collections may contain various plugins that have various external dependencies. The Ansible dev guide https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_best_practices.html#importing-and-using-shared-code[mandates] -that plugins fail cleanly if these dependencies. +that plugins fail cleanly if these dependencies are not installed. +Many times, external dependencies are only needed for a small subset of the +collection which may or may not be widely used. Therefore, collection packages SHOULD weakly depend on these external libraries, i.e. use Recommends instead of Requires. -Module dependencies are only needed on the target node, -not the controller node. +Module dependencies are only needed on the target node not the controller node. Therefore, collection packages SHOULD NOT depend on these dependencies at all, weakly or strongly. Users are responsible for installing these dependencies on the target host. @@ -88,18 +91,18 @@ Modules that are intended to be used with `+delegate_to: localhost+` are an exception to this rule. The situation is a bit different for controller plugins, such as -filter plugins, lookup plugins, connection plugins, and inventory plugins. -Collections MAY add `+Recommends+` for these dependencies. +filter plugins, lookup plugins, connection plugins, or inventory plugins. +Collections MAY add `+Recommends+` for dependencies of controller plugins. However, packagers should use discretion when adding any type of dependency and only do so when it is required for the central functionality of the collection. For instance, it makes sense for `+ansible-collection-community-docker+` -to Recommend python3-docker. -On the other hand, it wouldn't make sense for the larger, more general +to Recommend `+python3-docker+`, +but it doesn't make sense for the larger, more general ansible-collection-community-general collection to Recommend `+python3-redis+` for the `+redis+` lookup plugin. -This guidelines seeks to prevent ballooning collection packages. -`+ansible-core+` and `+ansible+` follows this same principal. +This guideline seeks to prevent ballooning collection packages. +`+ansible-core+` and `+ansible+` follow this same principal. == Build and Installation @@ -117,11 +120,12 @@ The `+%{ansible_collection_filelist}+` is populated by `+%ansible_collection_ins As per xref:index.adoc#_test_suites[the general Fedora Packaging Guidelines], collection packages SHOULD run upstream unit tests in `+%check+` if practical. -Integration tests are impossible to run in the rpm environment. +Integration tests are impossible to run in the RPM build environment. In order to run unit tests, collections MUST `+BuildRequire+` -`+ansible-packaging+`, which pulls in the necessary dependencies. -Collections may have other testing dependencies, +`+ansible-packaging-tests+`, which pulls in the necessary dependencies. +Some collections have other testing dependencies, which are usually specified in `+tests/unit/requirements.txt+`. +These have to be added manually. The `+%ansible_test_unit+` macro MUST be used to run tests. [NOTE] @@ -161,8 +165,7 @@ Common development files include: These files often have to be removed downstream, as there are some unresolved issues with pushing these changes to upstream community collections. These -issues are mostly related to the way Ansible Community compiles the `+ansible+` -bundle and are irrelevant in the Fedora context. +issues are irrelevant in the Fedora context. == Shebangs @@ -195,7 +198,7 @@ mark the license and documentation files in this directory with `+%license+` and `+%doc+` or to add the correct paths to `+build_ignore+` in `+galaxy.yml+` and install them into the standard directories. -Packages should avoid duplicating these files in both places. +Avoid duplicating these files in both places. Note that some multi-licensed collections store licenses in a `+LICENSES+` directory. This whole directory MUST be marked with `+%license+`. @@ -224,7 +227,7 @@ Summary: RabbitMQ collection for Ansible License: GPL-3.0-or-later and PSF-2.0 URL: %{ansible_collection_url community rabbitmq} %global forgeurl https://github.com/ansible-collections/community.rabbitmq -Source0: %{fogeurl}/archive/%{version}/%{name}-%{version}.tar.gz +Source0: %{forgeurl}/archive/%{version}/%{name}-%{version}.tar.gz # Patch galaxy.yml to exclude unnecessary files from the built collection. # This is a downstream only patch. Patch0: build_ignore.patch @@ -396,7 +399,7 @@ Packagers are expected to use `+%ansible_collection_install+` and === Legacy macros [#collection_namespace] -===== `+%collection_namepsace+` +===== `+%{collection_namepsace}+` *Usage:* [source,RPMSpec] @@ -410,7 +413,7 @@ Now, the macros extract the collection namespace from the `galaxy.yml`. [#collection_name] -===== `+%collection_name+` +===== `+%{collection_name}+` *Usage:* From dce79eec9763aed66346ddafcd079baca4adc4be Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Nov 12 2022 20:16:36 +0000 Subject: [PATCH 15/232] Move Ansible to Other Domain-specific Guidelines Ansible collections are not a programming language. --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index a0146e8..2e11852 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -39,7 +39,6 @@ * Programming Languages ** xref:Ada.adoc[Ada] -** xref:Ansible_collections.adoc[Ansible Collections] ** xref:C_and_C++.adoc[C and {cpp}] ** xref:D.adoc[D] ** xref:Fortran.adoc[Fortran] @@ -66,6 +65,7 @@ ** xref:Tcl.adoc[Tcl/Tk extensions] * Other Domain-specific Guidelines +** xref:Ansible_collections.adoc[Ansible Collections] ** xref:BLAS_LAPACK.adoc[BLAS/LAPACK] ** xref:CronFiles.adoc[CronFiles] ** xref:Drupal7.adoc[Drupal7] From 6580b2b429662595a349a2a49804841b58763bf2 Mon Sep 17 00:00:00 2001 From: Miro Hrončok Date: Nov 15 2022 18:12:09 +0000 Subject: [PATCH 16/232] Don't say stable branches cannot do chain builds --- diff --git a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc index 74f6e2e..8935878 100644 --- a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc +++ b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc @@ -62,7 +62,8 @@ There are many many things to check for a review. This list is provided to assis It is often useful to submit a package for review along with its dependencies in separate tickets. As long as the submitter sets up the Depends on: and Blocks: fields in bugzilla properly, this is not an issue, and it is perfectly possible to review these packages before the full dependency chain is in the distribution (by maintaining a local repository, building and installing the packages locally, or maintaining a Copr). -However, please keep in mind that you cannot do koji builds if all of the build dependencies are not met (because you cannot provide additional dependencies to koji) and when the time comes to build these packages, they must be built in order and you must wait between builds for the dependencies to make it into the appropriate branch of the distribution. For the devel branch (Rawhide) this happens frequently and can be automated using chain builds, but for release branches each package must make it all the way to stable before the next package in the chain can be built. +However, please keep in mind that you cannot do koji builds if all of the build dependencies are not met (because you cannot provide additional dependencies to koji) and when the time comes to build these packages, they must be built in order and you must wait between builds for the dependencies to make it into the appropriate branch of the distribution. +This can be automated using side tags and chain builds. Please also note that while you may actually be able to build a package because all of its build-time dependencies are met, the package may still be non-installable (and thus useless) if its _runtime_ dependencies are not met. A package *MUST* not be built if any of its runtime dependencies are unsatisfied. From 136e8f9e690ef5ff1cbb24f2816921c24a17a2e2 Mon Sep 17 00:00:00 2001 From: James Antill Date: Nov 17 2022 17:26:52 +0000 Subject: [PATCH 17/232] Merge #1201 `initial Ansible Collection guidelines` --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 6281361..2e11852 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -65,6 +65,7 @@ ** xref:Tcl.adoc[Tcl/Tk extensions] * Other Domain-specific Guidelines +** xref:Ansible_collections.adoc[Ansible Collections] ** xref:BLAS_LAPACK.adoc[BLAS/LAPACK] ** xref:CronFiles.adoc[CronFiles] ** xref:Drupal7.adoc[Drupal7] diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc new file mode 100644 index 0000000..5053721 --- /dev/null +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -0,0 +1,446 @@ += Ansible Collection Packaging Guidelines +:last-reviewed: 2022-09-25 +:toc: + +== Forward + +Ansible collections are packaged units of Ansible content, +including modules and other types of plugins. +Most Ansible Plugins are written in Python or Powershell. + +Some collections are also included in Ansible Community's `+ansible+` +collection bundle, which is packaged in Fedora. +All collections, whether or not they are included in the `+ansible+` package, +MAY be packaged in Fedora. + +`+ansible+` depends on `+ansible-core+`, which contains the core engine and +CLI programs (e.g. `+ansible+`, `+ansible-playbook+`). +The `+ansible+` package has a different release cycle than individual collections, +and it may contain older versions of the individual components. +`+ansible+` installs collections in a different namespace and is parallel +installable with individual collections. +The Ansible engine searches for collections in the standalone collections +directory first. + +See https://fedoraproject.org/wiki/Changes/Ansible5[Changes/Ansible5] +for more information about the split between `+ansible+` and `+ansible-core+`. + +== Naming + +Collection packages MUST be named `+ansible-collection-NAMESPACE-NAME+`. +For example, the `+community.general+` collection package is named +`+ansible-collection-community-general+`. + + +== Collection Source + +Collection source code MUST be downloaded from the collection's respective +Git forge/other SCM repository. +While the tarballs published to Ansible Galaxy contain all of the +collection's Python/Powershell source code as well as some development files, +they do not include the `+galaxy.yml+` build configuration +and development files (e.g. unit tests) that the author may choose to remove. +Note that the Ansible Community collection requirements mandate that +collections tag releases in a public SCM repository. + +Collection packages SHOULD use `+%{ansible_collection_url NAMESPACE NAME}+` +as the package's `+URL:+`. +This points to the collection's homepage on Ansible Galaxy. + + +== Dependencies + +=== Buildtime + +Collections MUST have `+BuildRequires: ansible-packaging+`. +`+ansible-packaging+` provides macros and a dependency generator for packaging +Ansible Collections. +It also pulls in `+ansible-core+`, +so `+BuildRequires: ansible-core+` SHOULD NOT be added manually. + +=== Runtime + +The dependency generator will generate the appropriate dependency on the Ansible engine. +This ensures compatibility with Fedora 35 +which contains the classic `+ansible+` 2.9 package (instead of the collections bundle) +and `+ansible-core+`. Both versions of the Ansible engine support collections, +but they are not parallel installable. +Packages MUST NOT manually `+Require+` `+ansible-core+` or `+ansible+`, +unless they are known to require a specific version, +in which case the appropriate version constraints should be used. + +The dependency generator also handles inter-collection dependencies. + +==== External dependencies of plugins + +Ansible collections may contain various plugins that have +various external dependencies. +The Ansible dev guide +https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_best_practices.html#importing-and-using-shared-code[mandates] +that plugins fail cleanly if these dependencies are not installed. +Many times, external dependencies are only needed for a small subset of the +collection which may or may not be widely used. +Therefore, collection packages SHOULD weakly depend on these external libraries, +i.e. use Recommends instead of Requires. + +Module dependencies are only needed on the target node not the controller node. +Therefore, collection packages SHOULD NOT depend on these dependencies at all, +weakly or strongly. +Users are responsible for installing these dependencies on the target host. +Modules that are intended to be used with `+delegate_to: localhost+` are an +exception to this rule. + +The situation is a bit different for controller plugins, such as +filter plugins, lookup plugins, connection plugins, or inventory plugins. +Collections MAY add `+Recommends+` for dependencies of controller plugins. +However, packagers should use discretion when adding any type of dependency +and only do so when it is required for +the central functionality of the collection. +For instance, it makes sense for `+ansible-collection-community-docker+` +to Recommend `+python3-docker+`, +but it doesn't make sense for the larger, more general +ansible-collection-community-general collection to Recommend `+python3-redis+` +for the `+redis+` lookup plugin. +This guideline seeks to prevent ballooning collection packages. +`+ansible-core+` and `+ansible+` follow this same principal. + + +== Build and Installation + +To build the collection artifact, +packages MUST use `+%ansible_collection_build+` in `+%build+`. +`+%ansible_collection_install+` MUST be used in `+%install+` to install the +artifact. + +Packagers SHOULD use `+%files -f %{ansible_collection_filelist}+` to install +the collection. +The `+%{ansible_collection_filelist}+` is populated by `+%ansible_collection_install+`. + +== Unit Tests + +As per xref:index.adoc#_test_suites[the general Fedora Packaging Guidelines], +collection packages SHOULD run upstream unit tests in `+%check+` if practical. +Integration tests are impossible to run in the RPM build environment. +In order to run unit tests, collections MUST `+BuildRequire+` +`+ansible-packaging-tests+`, which pulls in the necessary dependencies. +Some collections have other testing dependencies, +which are usually specified in `+tests/unit/requirements.txt+`. +These have to be added manually. +The `+%ansible_test_unit+` macro MUST be used to run tests. + +[NOTE] +.EPEL Compatibility +==== +It is currently impossible to run unit tests on EPEL 8 and 9. + +ansible-core in RHEL 8.6 is built against python38. In c8s and the next RHEL +8 minor release, it will be built against python39. The testing dependencies +are not yet packaged for either Python version in EPEL 8. + +ansible-test in RHEL 9.0 still needs python3-mock, but this +requirement has been removed in CentOS 9 Stream. + +The rest of these guidelines are applicable to EPEL 8 and 9, +and `+ansible-packaging+` itself is available there. +==== + +== Unnecessary Files + +By default, collections ship with all of the files in the repository root, +unless they are manually excluded. +Therefore, many collections contain development files that are unwanted by users. + +Packagers SHOULD exclude these files, which SHOULD be done by patching the +collection's `+galaxy.yml+` to add these files to the `+build_ignore+` +configuration. +These files SHOULD NOT be removed with `+rm+`. +See the https://docs.ansible.com/ansible/latest/dev_guide/collections_galaxy_meta.html#collection-galaxy-metadata-structure[Ansible documentation] +for more information on the `+galaxy.yml+` syntax. + +Common development files include: + +* The `+tests+` directory containing unit and integration tests +* SCM configuration such as `+.gitignore+` and `+.keep+` files +* The `+.azure-pipelines+` and `+.github+` directories that contain CI configuration + +These files often have to be removed downstream, as there are some unresolved +issues with pushing these changes to upstream community collections. These +issues are irrelevant in the Fedora context. + +== Shebangs + +Ansible plugins are not executable. However, many of them have `+#!/usr/bin/python+` +shebangs for legacy reasons. +These shebangs MUST be removed for the following reasons: + +1. Non-executable files shouldn't have shebangs +2. Keeping the shebangs results in an unnecessary dependency +on `+python-unversioned-command+`. + +`+%py3_shebang_fix+` MUST NOT be used, as it will break compatibility +with certain Ansible target nodes. +It won't fix the non-executable file issue, either. + +Shebangs can be removed with: + +[source,bash] +---- +find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' + +---- + + +== Documentation and License Files + +License files and documentation for collections are installed to the +collection's directory in `+/usr/share/ansible+`, by default. +Packagers MAY choose to either +mark the license and documentation files in this directory with `+%license+` +and `+%doc+` +or to add the correct paths to `+build_ignore+` in `+galaxy.yml+` and +install them into the standard directories. +Avoid duplicating these files in both places. + +Note that some multi-licensed collections store licenses in a `+LICENSES+` +directory. This whole directory MUST be marked with `+%license+`. + +Refer to the xref:legal::index.adoc[Legal docs] for the rules about +allowed licenses and determining the `+License:+` field. + + +== Example Specfile + +[source,RPMSpec] +---- +# Only run tests where the dependencies are available +%if %{defined fedora} +%bcond_without tests +%else +%bcond_with tests +%endif + +Name: ansible-collection-community-rabbitmq +Version: 1.2.2 +Release: 1%{?dist} +Summary: RabbitMQ collection for Ansible + +# plugins/module_utils/_version.py: Python Software Foundation License version 2 +License: GPL-3.0-or-later and PSF-2.0 +URL: %{ansible_collection_url community rabbitmq} +%global forgeurl https://github.com/ansible-collections/community.rabbitmq +Source0: %{forgeurl}/archive/%{version}/%{name}-%{version}.tar.gz +# Patch galaxy.yml to exclude unnecessary files from the built collection. +# This is a downstream only patch. +Patch0: build_ignore.patch + +BuildRequires: ansible-packaging +%if %{with tests} +BuildRequires: ansible-packaging-tests +# Collection specific test dependency +BuildRequires: glibc-all-langpacks +%endif + +BuildArch: noarch + +%description +%{summary}. + + +%prep +%autosetup -n community.rabbitmq-%{version} -p1 +find -type f ! -executable -name '*.py' -print -exec sed -i -e '1{\@^#!.*@d}' '{}' + + + +%build +%ansible_collection_build + + +%install +%ansible_collection_install + + +%if %{with tests} +%check +%ansible_test_unit +%endif + + +%files -f %{ansible_collection_filelist} +%license COPYING PSF-license.txt +%doc README.md CHANGELOG.rst + +%changelog +---- + +build_ignore.patch: + +[source, patch] +---- +diff --git a/galaxy.yml b/galaxy.yml +index 0b37162..acd029a 100644 +--- a/galaxy.yml ++++ b/galaxy.yml +@@ -13,3 +13,13 @@ repository: https://github.com/ansible-collections/community.rabbitmq + documentation: https://docs.ansible.com/ansible/latest/collections/community/rabbitmq/ + homepage: https://github.com/ansible-collections/community.rabbitmq + issues: https://github.com/ansible-collections/community.rabbitmq/issues ++build_ignore: ++ # Remove unnecessary development files from the built package. ++ - tests ++ - .azure-pipelines ++ - .gitignore ++ # Licenses and docs are installed with %%doc and %%license ++ - PSF-license.txt ++ - COPYING ++ - README.md ++ - CHANGELOG.rst +---- + + +== Macro Breakdown + +Here is a short breakdown of exactly what each macro included in +`+ansible-packaging+` does. + + +[#ansible_collection_url] +===== `+%ansible_collection_url+` + +*Usage:* + +[source,RPMSpec] +---- +URL: %{ansible_collection_url NAMESPACE NAME} +---- + +This macro points to a collection's Ansible Galaxy page. +It is intended to be used for the `+URL:+` tag in the specfile preamble. +It takes the collection namespace and collection name as arguments. + +If no arguments are passed to this macro, it falls back to the values +of `+%{collection_namespace}+` and `+%{collection_name}+` if they are set in the specfile. +New packages SHOULD explicitly pass the namespace and name as arguments. +The fallback may be removed in the future. +See the link:#legacy_macros[Legacy Macros] section for more information. + + +[#ansible_collection_build] + +===== `+%ansible_collection_build+` + +*Usage:* + +[source,RPMSpec] +---- +%build +%ansible_collection_build +---- + +This macro simply runs `+ansible-galaxy collection build+`. + + +[#ansible_collection_install] +===== `+%ansible_collection_install+` + +*Usage:* + +[source,RPMSpec] +---- +%install +%ansible_collection_install +---- + +This macro pulls out the collection namespace, name, and version from `+galaxy.yml+` +and then uses it to run `+ansible-galaxy collection install+`. +After that, it writes out `+%{ansible_collection_filelist}` based on the +metadata it previously extracted + + +[#ansible_test_unit] +===== `+%ansible_test_unit+` + +*Usage:* + +[source,RPMSpec] +---- +%check +%ansible_test_unit +---- +This macro parses galaxy.yml to determine the collection namespace and name +that's needed to create the directory structure that ansible-test expects. +After creating a temporary build directory with the needed structure, the +script runs ansible-test units with the provided arguments. + + +[#ansible_collection_filelist] +===== `+%{ansible_collection_filelist}+` + +*Usage:* + +[source,RPMSpec] +---- +%files -f %{ansible_collection_filelist} +%doc ... +%license ... +---- + +This macro points a file list that's written out by `+%ansible_collection_install+`. +Currently, it only contains a single entry to own the collection's entire +directory in `+%{ansible_collections_dir}+` + + +[#ansible_collections_dir] + +This macro expands to `+%{_datadir}/ansible/collections/ansible_collections+`. +It is used internally by the other macros. +Packagers are expected to use `+%ansible_collection_install+` and +`+%ansible_collection_filelist+` instead of directly referencing this directory. + +[#legacy_macros] +=== Legacy macros + +[#collection_namespace] +===== `+%{collection_namepsace}+` +*Usage:* + +[source,RPMSpec] +---- +%global collection_namespace NAMESPACE +---- + +The ansible-packaging macros previously required +packagers to manually set `+%collection_namespace+` in specfiles. +Now, the macros extract the collection namespace from the `galaxy.yml`. + + +[#collection_name] +===== `+%{collection_name}+` + +*Usage:* + +[source,RPMSpec] +---- +%global collection_name NAME +---- + +The ansible-packaging macros previously required +packagers to manually set `+%collection_namespace+` in specfiles. +Now, the macros extract the collection namespace from the `galaxy.yml`. + + +[#ansible_collection_files] +===== `+%{ansible_collection_files}+` + +*Usage:* + +[source,RPMSpec] +---- +%files +%doc ... +%license ... +%{ansible_collection_files} +---- + +New specfiles should use `+%files -f %{ansible_collection_filelist}+` instead +of this macro. +`+%{ansible_collection_files}+` requires setting +`+%collection_namespace+` and `+%collection_name+`. From 6d6e506d422d2710bb499940fa41d0a9543dca34 Mon Sep 17 00:00:00 2001 From: David Kaufmann Date: Dec 21 2022 19:20:30 +0000 Subject: [PATCH 18/232] fix changed rpmlint parameters --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 2b33adc..8b3b609 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -722,12 +722,12 @@ So you'd want to use `+Requires: /sbin/ifconfig+` in your spec file. Run rpmlint on binary and source rpms to examine them for common errors, and fix them (unless rpmlint is wrong, which can happen, too). If you find rpmlint's output cryptic, -the `+-i+` switch to it can be used +the `+-e+` switch to it can be used to get more verbose descriptions of most errors and warnings. Note that rpmlint will perform additional checks if given the name of an installed package. For example, -`+dnf install foo-1.0-1.f20.x86_64.rpm; rpmlint foo+` +`+dnf install foo-1.0-1.f20.x86_64.rpm; rpmlint -i foo+` will perform a set of tests on the foo package that `+rpmlint foo-1.0-1.f20.x86_64.rpm+` cannot. A community-maintained page on rpmlint issues can be found From 9129d169f19f775b44d8d6c8087c091f953b752b Mon Sep 17 00:00:00 2001 From: Karolina Surma Date: Jan 05 2023 13:24:55 +0000 Subject: [PATCH 19/232] Document _python_dist_allow_version_zero macro Rationale: https://fedoraproject.org/wiki/Changes/Prevent-Providing-python3dist(pkg)=0 --- diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc index 70bea4c..f4e117e 100644 --- a/guidelines/modules/ROOT/pages/Python.adoc +++ b/guidelines/modules/ROOT/pages/Python.adoc @@ -1167,6 +1167,7 @@ When using sources from PyPI, you can use the <> to generate the proper URL. +[[_version_warning]] WARNING: Some Python packages use metadata from `git` (or a similar version control system) to construct their version string, @@ -1830,6 +1831,13 @@ See <> for more details. + If defined, <> will not be generated. +[#_python_dist_allow_version_zero] +* `+%global _python_dist_allow_version_zero 1+` ++ +From Fedora Linux 38 on, it is no longer possible to build a Python package with version 0 +to prevent <<_version_warning,an accidental loss of the actual version information>>. +If defined, the macro will allow to build such package. + === Deprecated Macros The following macros are deprecated. From 26174464286d7e44c4f5a23f71d487fd9fd4d3f9 Mon Sep 17 00:00:00 2001 From: Miro Hrončok Date: Jan 09 2023 09:52:51 +0000 Subject: [PATCH 20/232] Always use !? for "not defined" See https://github.com/rpm-software-management/rpm/discussions/2340 --- diff --git a/guidelines/modules/ROOT/pages/Perl.adoc b/guidelines/modules/ROOT/pages/Perl.adoc index 4fa3305..c576ccf 100644 --- a/guidelines/modules/ROOT/pages/Perl.adoc +++ b/guidelines/modules/ROOT/pages/Perl.adoc @@ -148,7 +148,7 @@ One common way to disable a test for mock but enable it locally is to use a `+_w .... %check -%{?!_with_network_tests: rm t/roster.t } +%{!?_with_network_tests: rm t/roster.t } ./Build test .... From f7fe97de94545fc457e3a1e7216bdb87599c476f Mon Sep 17 00:00:00 2001 From: Jitka Plesnikova Date: Jan 12 2023 08:43:56 +0000 Subject: [PATCH 21/232] Perl: Replace versioned MODULE_COMPAT_ requires by RPM dependency generator Rationale: https://fedoraproject.org/wiki/Changes/Perl_replace_MODULE_COMPAT_by_generator Implemented here: https://src.fedoraproject.org/rpms/perl-generators/pull-request/2 https://github.com/jplesnik/generators/commit/9bc8d5b783f3a1597b2342ce4c15f65f0c607508 --- diff --git a/guidelines/modules/ROOT/pages/Perl.adoc b/guidelines/modules/ROOT/pages/Perl.adoc index c576ccf..785fc4d 100644 --- a/guidelines/modules/ROOT/pages/Perl.adoc +++ b/guidelines/modules/ROOT/pages/Perl.adoc @@ -46,25 +46,11 @@ Perl packages use the virtual `+perl(Foo)+` naming to indicate a given Perl modu It is recommended to include explicit dependencies for core modules, because they can move between sub-packages or disappear from core Perl. -=== Versioned MODULE_COMPAT_ Requires +=== Versioned MODULE_COMPAT_ Requires or `+perl-libs+` -All Perl modules must include the versioned MODULE_COMPAT Requires: +Packages with Perl modules installed in %{perl_vendorarch}, %{perl_vendorlib}, %{perl_privlib} or %{perl_archlib} will automatically gain dependency on `+perl-libs+` for pure Perl modules or a dependency on `+perl(:MODULE_COMPAT_)+` for libraries with compiled code. The dependency is handled by `+perl-generators+`. -.... -Requires: perl(:MODULE_COMPAT_%(eval "`%{__perl} -V:version`"; echo $version)) -.... - -This is to ensure that Perl packages have a dependency on the particular version of Perl it was built against, or on a newer version of Perl that provides backward compatibility with it. - -For example, `+perl-5.8.8+` provided not only `+perl(:MODULE_COMPAT_5.8.8)+`, but also `+perl(:MODULE_COMPAT_5.8.7)+`, etc., because backward compatibility was guaranteed for Fedora Perl 5.8.x. - -On the other hand, `+perl-5.10.1+` implements some incompatible changes to module tree layout and `+libperl.so+` build options. Once the compatibility aids are removed, `+perl-5.10.1+` and above will no longer provide `+perl(:MODULE_COMPAT_5.10.0)+`. - -In the future, it is possible that `+perl-5.12.2+` will provide not only `+perl(:MODULE_COMPAT_5.12.[012])+`, but also `+perl(:MODULE_COMPAT_5.10.[123])+`, if the backward compatibility with all versions >= 5.10.1 is maintained. - -==== Packages that link to `+libperl+` - -Some packages link to `+libperl.so+`, usually to provide embedded Perl functionality. All of these packages must also use the versioned `+MODULE_COMPAT+` dependency, because the automatically generated dependency on `+libperl.so+` does not include any interface version number. +Packages that require the Perl interpreter or `+libperl.so+` but do not install modules to the aforementioned directories or explicitly link to `+libperl.so.+` need to handle the dependency manually. === Filtering Requires and Provides From 938a9c73a1375ec6f47009651aecca4a2ab3b7b6 Mon Sep 17 00:00:00 2001 From: Miro Hrončok Date: Jan 17 2023 11:00:49 +0000 Subject: [PATCH 22/232] Rust: Fix a typo --- diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc index e8002e1..3396992 100644 --- a/guidelines/modules/ROOT/pages/Rust.adoc +++ b/guidelines/modules/ROOT/pages/Rust.adoc @@ -107,7 +107,7 @@ All Rust packages MUST have `+BuildRequires: rust-packaging+`. NOTE: As stated in the general xref:index.adoc#bundling[Packaging Guidelines], packages MUST be built against system libraries, if that is possible. For Rust, this means that packages MUST NOT use dependencies from a "vendor tarball" - (e.g. crated by running `+cargo vendor+`), + (e.g. created by running `+cargo vendor+`), but package all library dependencies separately. However, two common reasons that can make building a package From b150207d4c8f842c1ad3597675016eb82388bca8 Mon Sep 17 00:00:00 2001 From: Miro Hrončok Date: Jan 26 2023 22:14:14 +0000 Subject: [PATCH 23/232] Rust: Link to the Rust section of the license field docs --- diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc index 3396992..9672a4a 100644 --- a/guidelines/modules/ROOT/pages/Rust.adoc +++ b/guidelines/modules/ROOT/pages/Rust.adoc @@ -240,7 +240,7 @@ NOTE: When introducing a compatibility package, the packager SHOULD check == License for binary packages -See xref:legal::license-field.adoc[License: field in Spec file] guidance specific to Rust. +See xref:legal::license-field.adoc#_rust_packages[License: field in Spec file] guidance specific to Rust. == Miscellaneous From 6c9d9c08da1bc4018651a12e58312c95178a9023 Mon Sep 17 00:00:00 2001 From: Carl George Date: Feb 01 2023 03:57:45 +0000 Subject: [PATCH 24/232] Remove duplicate tables of contents The Fedora docs theme now defaults to placing a table of contents on the right hand side, so we don't need to set these attributes. --- diff --git a/guidelines/modules/ROOT/pages/Ada.adoc b/guidelines/modules/ROOT/pages/Ada.adoc index 94bfc82..30f69c5 100644 --- a/guidelines/modules/ROOT/pages/Ada.adoc +++ b/guidelines/modules/ROOT/pages/Ada.adoc @@ -1,7 +1,6 @@ = Ada Packaging Guidelines :last-reviewed: 2019-04-04 -:toc: This document describes the current policies for packaging Ada programs and libraries for Fedora. diff --git a/guidelines/modules/ROOT/pages/Alternatives.adoc b/guidelines/modules/ROOT/pages/Alternatives.adoc index 68fb0a1..a3aba3f 100644 --- a/guidelines/modules/ROOT/pages/Alternatives.adoc +++ b/guidelines/modules/ROOT/pages/Alternatives.adoc @@ -1,7 +1,6 @@ = Alternatives :last-reviewed: 2019-04-04 -:toc: Alternatives provide means for parallel installation of packages which provide the same functionality by maintaining sets of symlinks diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index 5053721..19158b3 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -1,6 +1,5 @@ = Ansible Collection Packaging Guidelines :last-reviewed: 2022-09-25 -:toc: == Forward diff --git a/guidelines/modules/ROOT/pages/AppData.adoc b/guidelines/modules/ROOT/pages/AppData.adoc index 8c2f15d..18da9d9 100644 --- a/guidelines/modules/ROOT/pages/AppData.adoc +++ b/guidelines/modules/ROOT/pages/AppData.adoc @@ -1,6 +1,5 @@ = Packaging Guidelines for AppData Files :last-reviewed: 2021-01-18 -:toc: If a package contains a GUI application, then it SHOULD install a `+.metainfo.xml+` file diff --git a/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc b/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc index ff83d88..f054df8 100644 --- a/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc +++ b/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc @@ -1,7 +1,6 @@ = Automatic Filtering of Provides and Requires :last-reviewed: 2019-04-04 -:toc: == Summary diff --git a/guidelines/modules/ROOT/pages/BLAS_LAPACK.adoc b/guidelines/modules/ROOT/pages/BLAS_LAPACK.adoc index 5638522..3ea9c28 100644 --- a/guidelines/modules/ROOT/pages/BLAS_LAPACK.adoc +++ b/guidelines/modules/ROOT/pages/BLAS_LAPACK.adoc @@ -1,5 +1,4 @@ = Linear Algebra Libraries -:toc: == Introduction diff --git a/guidelines/modules/ROOT/pages/CMake.adoc b/guidelines/modules/ROOT/pages/CMake.adoc index 2e45a5e..b2c0602 100644 --- a/guidelines/modules/ROOT/pages/CMake.adoc +++ b/guidelines/modules/ROOT/pages/CMake.adoc @@ -1,7 +1,6 @@ :last-reviewed: 2020-07-18 = CMake Packaging Guidelines -:toc: This document provides best practices for the usage of https://cmake.org/[the CMake build system] diff --git a/guidelines/modules/ROOT/pages/DefaultServices.adoc b/guidelines/modules/ROOT/pages/DefaultServices.adoc index 46e4302..eab7c6a 100644 --- a/guidelines/modules/ROOT/pages/DefaultServices.adoc +++ b/guidelines/modules/ROOT/pages/DefaultServices.adoc @@ -1,5 +1,4 @@ = Default Services -:toc: == What is a Service? diff --git a/guidelines/modules/ROOT/pages/FontsPolicy.adoc b/guidelines/modules/ROOT/pages/FontsPolicy.adoc index 77a406c..f037bbe 100644 --- a/guidelines/modules/ROOT/pages/FontsPolicy.adoc +++ b/guidelines/modules/ROOT/pages/FontsPolicy.adoc @@ -1,6 +1,4 @@ = Fonts -:toc: -:toclevels: 4 == Foreword diff --git a/guidelines/modules/ROOT/pages/GAP.adoc b/guidelines/modules/ROOT/pages/GAP.adoc index 90feeed..a135953 100644 --- a/guidelines/modules/ROOT/pages/GAP.adoc +++ b/guidelines/modules/ROOT/pages/GAP.adoc @@ -1,5 +1,4 @@ = GAP Packaging Guidelines -:toc: This document describes the conventions and customs surrounding the proper packaging of https://gap-system.org/[GAP] add-on packages in Fedora. Throughout this document, we use the word _add-on_ to substitute for GAP upstream's use of the word _package_, to avoid confusion with RPM packages. diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index f6b8954..bf4b870 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -1,6 +1,5 @@ = Golang Packaging Guidelines :last-reviewed: 2019-06-19 -:toc: This document details best practices for packaging Golang packages. Most of it is automated by an extensive use of macros. diff --git a/guidelines/modules/ROOT/pages/Golang_advanced.adoc b/guidelines/modules/ROOT/pages/Golang_advanced.adoc index 1052334..0ce8c79 100644 --- a/guidelines/modules/ROOT/pages/Golang_advanced.adoc +++ b/guidelines/modules/ROOT/pages/Golang_advanced.adoc @@ -1,6 +1,5 @@ = Advanced uses cases :last-reviewed: 2019-06-19 -:toc: == Shipping additional files diff --git a/guidelines/modules/ROOT/pages/Golang_templates.adoc b/guidelines/modules/ROOT/pages/Golang_templates.adoc index 157bff7..7f1a017 100644 --- a/guidelines/modules/ROOT/pages/Golang_templates.adoc +++ b/guidelines/modules/ROOT/pages/Golang_templates.adoc @@ -1,6 +1,5 @@ = Additional annotated templates :last-reviewed: 2019-03-22 -:toc: == Minimal source package diff --git a/guidelines/modules/ROOT/pages/Java.adoc b/guidelines/modules/ROOT/pages/Java.adoc index ceec760..4f7ffa4 100644 --- a/guidelines/modules/ROOT/pages/Java.adoc +++ b/guidelines/modules/ROOT/pages/Java.adoc @@ -1,6 +1,5 @@ = Java Packaging Guidelines :last-reviewed: 2022-07-01 -:toc: This page represents Fedora guidelines for packaging libraries and applications diff --git a/guidelines/modules/ROOT/pages/Meson.adoc b/guidelines/modules/ROOT/pages/Meson.adoc index 967f04c..1db13df 100644 --- a/guidelines/modules/ROOT/pages/Meson.adoc +++ b/guidelines/modules/ROOT/pages/Meson.adoc @@ -1,5 +1,4 @@ = Meson Packaging Guidelines -:toc: This document provides best practices for the usage of https://mesonbuild.com/[the Meson build system] in Fedora packages. Meson is a build system (similar to automake) which can generate code for other lower-level build systems. For example, it can generate code for https://ninja-build.org/[ninja]. When packaging software which builds using Meson it's important to use the `+%meson+` macros instead of `+%ninja+` or other lower-level build system macros directly. The backend used by Meson could change. diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index 65353e0..cc5fbb3 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -1,5 +1,4 @@ = Packaging Guidelines for MinGW Cross Compilers -:toc: == Introduction diff --git a/guidelines/modules/ROOT/pages/Mono.adoc b/guidelines/modules/ROOT/pages/Mono.adoc index 6bb61e4..454f402 100644 --- a/guidelines/modules/ROOT/pages/Mono.adoc +++ b/guidelines/modules/ROOT/pages/Mono.adoc @@ -1,5 +1,4 @@ = Mono Packaging Guidelines -:toc: == File Locations and Architectures diff --git a/guidelines/modules/ROOT/pages/Naming.adoc b/guidelines/modules/ROOT/pages/Naming.adoc index 5d4f59c..7ff5ec1 100644 --- a/guidelines/modules/ROOT/pages/Naming.adoc +++ b/guidelines/modules/ROOT/pages/Naming.adoc @@ -1,5 +1,4 @@ = Naming Guidelines -:toc: [NOTE] .Versioning guidelines have moved diff --git a/guidelines/modules/ROOT/pages/PHP.adoc b/guidelines/modules/ROOT/pages/PHP.adoc index c8f4ba5..899cc04 100644 --- a/guidelines/modules/ROOT/pages/PHP.adoc +++ b/guidelines/modules/ROOT/pages/PHP.adoc @@ -1,5 +1,4 @@ = PHP Packaging Guidelines -:toc: Fedora Packaging Guidelines for PHP addon modules diff --git a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc index 6786ff7..6b94199 100644 --- a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc +++ b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc @@ -1,5 +1,3 @@ -:toc: - In the Fedora.next world, we 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. The goal of this document is to set out the guidelines for creating per-Product configuration defaults. We want to ensure that all packages have sensible defaults for whichever Product on which they are installed, while also avoiding situations where users would have some packages installed with one Product's defaults and some packages with another. diff --git a/guidelines/modules/ROOT/pages/Perl.adoc b/guidelines/modules/ROOT/pages/Perl.adoc index 785fc4d..e782c76 100644 --- a/guidelines/modules/ROOT/pages/Perl.adoc +++ b/guidelines/modules/ROOT/pages/Perl.adoc @@ -1,5 +1,4 @@ = Perl Packaging Guidelines -:toc: == License tag diff --git a/guidelines/modules/ROOT/pages/Pkcs11Support.adoc b/guidelines/modules/ROOT/pages/Pkcs11Support.adoc index 687fba8..a7022ae 100644 --- a/guidelines/modules/ROOT/pages/Pkcs11Support.adoc +++ b/guidelines/modules/ROOT/pages/Pkcs11Support.adoc @@ -1,5 +1,4 @@ = PKCS#11 / Smart-Card Support Guidelines -:toc: These guidelines are relevant to maintainers of packages with smart cards drivers (PKCS#11 modules), or smart card related tooling. Its purpose is to bring a consistency in smart card handling on the OS; for background and motivation see the https://fedoraproject.org/wiki/User:Nmav/Pkcs11Status[current status of PKCS#11 in Fedora]. diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc index f4e117e..7ec93ce 100644 --- a/guidelines/modules/ROOT/pages/Python.adoc +++ b/guidelines/modules/ROOT/pages/Python.adoc @@ -1,6 +1,5 @@ = Python Packaging Guidelines :last-reviewed: 2021-06-04 -:toc: //// diff --git a/guidelines/modules/ROOT/pages/Python_201x.adoc b/guidelines/modules/ROOT/pages/Python_201x.adoc index 88b6c12..65b9e41 100644 --- a/guidelines/modules/ROOT/pages/Python_201x.adoc +++ b/guidelines/modules/ROOT/pages/Python_201x.adoc @@ -1,6 +1,5 @@ = Python Packaging Guidelines (201x-era) :last-reviewed: 2020-08-05 -:toc: [IMPORTANT] ==== diff --git a/guidelines/modules/ROOT/pages/Python_Appendix.adoc b/guidelines/modules/ROOT/pages/Python_Appendix.adoc index bd686f0..c2a5895 100644 --- a/guidelines/modules/ROOT/pages/Python_Appendix.adoc +++ b/guidelines/modules/ROOT/pages/Python_Appendix.adoc @@ -1,6 +1,5 @@ = Additional Python Guidelines :last-reviewed: 2020-01-01 -:toc: Here are some additional Python-related guidelines, moved here in order to keep the main page manageable. diff --git a/guidelines/modules/ROOT/pages/R.adoc b/guidelines/modules/ROOT/pages/R.adoc index 9f662a8..2b470b2 100644 --- a/guidelines/modules/ROOT/pages/R.adoc +++ b/guidelines/modules/ROOT/pages/R.adoc @@ -1,5 +1,4 @@ = R Packaging Guidelines -:toc: == What is R? diff --git a/guidelines/modules/ROOT/pages/Ruby.adoc b/guidelines/modules/ROOT/pages/Ruby.adoc index 86757d9..4d15aa1 100644 --- a/guidelines/modules/ROOT/pages/Ruby.adoc +++ b/guidelines/modules/ROOT/pages/Ruby.adoc @@ -1,5 +1,4 @@ = Ruby Packaging Guidelines -:toc: NOTE: *JRuby Gems*: Although Fedora has fully functioning JRuby diff --git a/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc b/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc index 1fb8d3e..c73badc 100644 --- a/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc +++ b/guidelines/modules/ROOT/pages/SSLCertificateHandling.adoc @@ -1,5 +1,4 @@ = Certificate Handling Guidelines -:toc: These guidelines are relevant to maintainers of packages which utilize smart cards for loading certificate or private key. Its purpose is to bring a consistency in smart card handling on the OS; for background and motivation see the link:https://fedoraproject.org/wiki/User:Nmav/Pkcs11Status[current status of PKCS#11 in Fedora]. diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc index 61c906d..cac2ccd 100644 --- a/guidelines/modules/ROOT/pages/Scriptlets.adoc +++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc @@ -1,5 +1,4 @@ = Scriptlets -:toc: RPM spec files have several sections which allow packages to run code on installation and removal. diff --git a/guidelines/modules/ROOT/pages/Systemd.adoc b/guidelines/modules/ROOT/pages/Systemd.adoc index 4a699dd..ae7bfd9 100644 --- a/guidelines/modules/ROOT/pages/Systemd.adoc +++ b/guidelines/modules/ROOT/pages/Systemd.adoc @@ -1,5 +1,4 @@ = Fedora systemd Services -:toc: This document describes the guidelines for systemd services, for use and inclusion in Fedora packages. diff --git a/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc b/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc index eff8777..d915937 100644 --- a/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc +++ b/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc @@ -1,5 +1,4 @@ = Tmpfiles.d -:toc: == Overview diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index fcddde8..6eaa069 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -1,7 +1,6 @@ include::{partialsdir}/versions.adoc[] = Versioning Guidelines -:toc: Fedora's package versioning scheme encompasses both the `+Version:+` diff --git a/guidelines/modules/ROOT/pages/deprecating-packages.adoc b/guidelines/modules/ROOT/pages/deprecating-packages.adoc index 804b66a..3dbb9ea 100644 --- a/guidelines/modules/ROOT/pages/deprecating-packages.adoc +++ b/guidelines/modules/ROOT/pages/deprecating-packages.adoc @@ -1,5 +1,4 @@ = Deprecating Packages -:toc: Sometimes a package is intended to be https://docs.fedoraproject.org/en-US/package-maintainers/Package_Retirement_Process/[removed from Fedora], but it is kept in Fedora for some additional (often indeterminate) time for various reasons including maintaining backwards compatibility. In order to prevent new packages from depending on such a package, it can be marked as *deprecated*. diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 8b3b609..0ae108c 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -3,7 +3,6 @@ :packaging-committee: https://pagure.io/packaging-committee[Fedora Packaging Committee] :scl-guidelines: https://fedoraproject.org/wiki/User:Toshio/SCL_Guidelines_(draft)[Software Collections] :updates-policy: https://docs.fedoraproject.org/en-US/fesco/Updates_Policy/[Updates Policy] -:toc: macro The Packaging Guidelines are a collection of common issues and the severity that should be placed on them. @@ -44,8 +43,6 @@ by many members of the Packaging Committee. Report issues with these guidelines, including typos, https://pagure.io/packaging-committee[here]. -toc::[] - == Applicability In general, diff --git a/guidelines/modules/ROOT/pages/what-can-be-packaged.adoc b/guidelines/modules/ROOT/pages/what-can-be-packaged.adoc index 0a7be23..38cca68 100644 --- a/guidelines/modules/ROOT/pages/what-can-be-packaged.adoc +++ b/guidelines/modules/ROOT/pages/what-can-be-packaged.adoc @@ -2,7 +2,6 @@ :packaging-committee: https://fedoraproject.org/wiki/Packaging_Committee[Packaging Committee] :legal-team: https://fedoraproject.org/wiki/Legal:Main[Legal Team] :kernel-team: https://fedoraproject.org/wiki/Kernel[Kernel Team] -:toc: Not everything can be packaged in Fedora. Most things considered to be "free software" or "open source software" are permitted, but definitions of these are not always consistent and Fedora has a few specific requirements and exceptions. This is an overview of some specific requirements and exceptions, but it is not intended to be exhaustive. If questions arise, the {packaging-committee} and the {legal-team} are the primary places to receive answers. From dd963fa392d8f9e4ec11d71b3cd2014e45b7e73f Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: [PATCH 25/232] mingw: remove reference to early state in Fedora 17 What was present in Fedora 17 for mingw is not relevant information for people reading mingw packaging guidelines 20 releases later. Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index cc5fbb3..746faa4 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -4,7 +4,7 @@ The Fedora MinGW project's mission is to provide an excellent development environment for Fedora users who wish to cross-compile their programs to run on Windows, minimizing the need to use Windows at all. In the past developers have had to port and compile all of the libraries and tools they have needed, and this huge effort has happened independently many times over. We aim to eliminate duplication of work for application developers by providing a range of libraries and development tools which have already been ported to the MinGW cross-compiler environment. This means that developers will not need to recompile the application stack themselves, but can concentrate just on the changes needed to their own application. -As of Fedora 17 a set of RPM macros and packages have been introduced which help packagers compile binaries for multiple targets. The targets Win32 and Win64 are supported. +The targets Win32 and Win64 are supported. == Track Fedora native package versions From 3dfbbaf6064ccd420dcc22309fe5f9c3202a3dbe Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: [PATCH 26/232] mingw: remove reference to secret package comparison script The guidelines reference a script for comparing native and mingw RPMs, however, there is no pointer to where it is. This script has existed as an attachment in a mailing list thread a great many years ago, but was never formalized into something that MinGW maintainers are expected to use. Remove the reference to it so maintainers don't go looking for something they will struggle to find. Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index 746faa4..82670ce 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -11,8 +11,6 @@ The targets Win32 and Win64 are supported. In general terms, cross-compiled MinGW versions of packages which are already natively available in Fedora, should follow the native Fedora package as closely as possible. This means they should stay at the same version, include all the same patches as the native Fedora package, and be built with the same configuration options. -The MinGW SIG have written an RPM comparison tool which makes it possible to compare cross compiled MinGW packages with the Fedora native packages, in order to determine whether versions, patches and configuration are aligned. - == Follow Fedora policy Cross compiled MinGW packages must follow Fedora policy, except where noted in this document. Cross compiled packages go through the same review process, GIT admin process etc. as other Fedora packages. From be5bafa6b72c9ca5dccd32f6fbb6d908dfe73531 Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: [PATCH 27/232] mingw: remove pointless line breaks in table headers Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index 82670ce..12cd2a1 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -202,8 +202,7 @@ Generic macros: [cols=",,",] |================================================================================================================================================== -|Macro |Available in + -mingw-filesystem |Explanation +|Macro |Available in mingw-filesystem |Explanation |mingw_cmake |>= 95 |Call the 'cmake' binary for all the configured targets |mingw_cmake_kde4 |>= 95 |Call the 'cmake' binary for all the configured targets with KDE4 specific parameters set |mingw_configure |>= 95 |Call the configure command for all the configured targets @@ -223,8 +222,7 @@ Win32 specific macros: [cols=",,,",] |=================================================================================================================================================== -|Macro |Available in + -mingw32-filesystem | Value |Explanation +|Macro |Available in mingw32-filesystem | Value |Explanation |mingw32_ar |>= 95 |i686-w64-mingw32-ar |cross compiler 'ar' binary |mingw32_cc |>= 95 |i686-w64-mingw32-gcc |cross compiler 'gcc' binary |mingw32_cflags |>= 95 |-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions --param=ssp-buffer-size=4 |Default compiler flags for C/C++ binaries @@ -249,8 +247,7 @@ Win64 specific macros: [cols=",,,",] |=================================================================================================================================================== -|Macro |Available in + -mingw64-filesystem | Value |Explanation +|Macro |Available in mingw64-filesystem | Value |Explanation |mingw64_ar |>= 95 |x86_64-w64-mingw32-ar |cross compiler 'ar' binary |mingw64_cc |>= 95 |x86_64-w64-mingw32-gcc |cross compiler 'gcc' binary |mingw64_cflags |>= 95 |-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions --param=ssp-buffer-size=4 |Default compiler flags for C/C++ binaries From 857e0312c00d8b6bff5b9e0817bef47d92bf5164 Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: [PATCH 28/232] mingw: remove reference to %{mingw_package_header} adding deps The %{mingw_package_header} does not express any automatic dependancy on the mingwXX-filesystem packages. This must always be explicitly added in the spec file. Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index 12cd2a1..c43e039 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -28,7 +28,7 @@ MinGW packages require special naming to denote the appropriate CPU architecture == Base packages -The base packages provide a root filesystem, base libraries, binutils (basic programs like 'strip', 'ld' etc), the compiler (gcc) and the Win32/Win64 API. Packages may need to depend on one or more of these. In particular, almost all packages should BuildRequire `+mingw32-filesystem+`, `+mingw64-filesystem+`, `+mingw32-gcc+` and `+mingw64-gcc+`. The correct Requires flags will get added automatically when the `+%{?mingw_package_header}+` macro is mentioned in the spec file (as will be described later on in these guidelines) +The base packages provide a root filesystem, base libraries, binutils (basic programs like 'strip', 'ld' etc), the compiler (gcc) and the Win32/Win64 API. Packages may need to depend on one or more of these. In particular, almost all packages should BuildRequire `+mingw32-filesystem+`, `+mingw64-filesystem+`, `+mingw32-gcc+` and `+mingw64-gcc+`. [cols=",",] |================================================================================================================================================================================================================================= @@ -369,7 +369,7 @@ Correct dependency generation is done automatically. Packagers should start thei %{?mingw_package_header} .... -All binary packages should depend on `+mingw32-filesystem+` or `+mingw64-filesystem+` (depending on the files in the package). If the line mentioned above is used then it will be added automatically, so you don't have to add it yourself +All binary packages should depend on `+mingw32-filesystem+` or `+mingw64-filesystem+` (depending on the files in the package). All specfiles should BuildRequire at least one of these (depending on the targets for which you want to build): From 2633349668552011509009b9e200b3d4dff7596d Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: [PATCH 29/232] mingw: stop recommending a versioned BR dep on mingwXX-filesystem All the documented mingw32/mingw64 RPM macros can be assumed to exist in all non-EOL Fedora releases. There is no common reason to write specfiles to cope with EOL Fedora releases. Thus using a versioned BR dep on the mingwXX-filesystem packages is not required, aside from in exceptional circumstances where a newly introduced macro is used. When we enable the UCRT64 target for non-toolchain packages, it might be desirable to have a versioned dep, since UCRT64 was only introduced in mingw-filesystem 133. The time for enabling UCRT64 is still TBD. Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index c43e039..a25dbef 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -373,12 +373,14 @@ All binary packages should depend on `+mingw32-filesystem+` or `+mingw64-filesys All specfiles should BuildRequire at least one of these (depending on the targets for which you want to build): -`+BuildRequires:  mingw32-filesystem >= minimum-version+` + -`+BuildRequires:  mingw64-filesystem >= minimum-version+` +`+BuildRequires:  mingw32-filesystem+` + +`+BuildRequires:  mingw64-filesystem+` and any other BuildRequires that they need. -The `+minimum-version+` must be at least 95 or any later version which provides the functionality you need +Most mingw RPM macros can be assumed to exist in all non-EOL Fedora releases. +If the package does, however, rely on a newly introduced macro, a versioned +dependancy on the `+mingw-XX-filesystem+` packages should be used. == Build architecture @@ -463,14 +465,14 @@ Source: https://fedoraproject.org/example-%{version}.tar.bz2 BuildArch: noarch -BuildRequires: mingw32-filesystem >= 113 +BuildRequires: mingw32-filesystem BuildRequires: mingw32-gcc BuildRequires: mingw32-binutils BuildRequires: mingw32-gettext BuildRequires: mingw32-win-iconv BuildRequires: mingw32-zlib -BuildRequires: mingw64-filesystem >= 113 +BuildRequires: mingw64-filesystem BuildRequires: mingw64-gcc BuildRequires: mingw64-binutils BuildRequires: mingw64-gettext From be8558f5c70393d1c28dc425202e314c2c118d2b Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: [PATCH 30/232] mingw: clarify the intended usage wrt selecting files to include Clarify that the MinGW package content will be used both for adhoc dev/test of Windows platform support, and for creation of Windows installers for applications. Generally this distinction won't have a major bearing on the selection of files to include in MinGW packages. It could, however, influence the inclusion of executables and documentation targetted at end users. Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index a25dbef..4e3c5ed 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -431,14 +431,28 @@ Most binaries contain debugging symbols when the package gets built. To split th The `+%{?mingw_debug_package}+` line must be placed after the `+%description tag+`. Otherwise spectool and other RPM tools may fail to function -== Executables (EXEs) +== File listing + +The MinGW packages are intended to allow developers to compile and test the +Windows support of their applications. It is furthermore expected that +developers will build Windows installers (MSIs) for their applications using +the MinGW package content. + +Thus the Fedora MinGW package file listing must include content needed to +satisfy either build/test usage or the creation of Windows installers. + +=== Executables (EXEs) Most libraries also provide executables. These can include executables which can be used to test or showcase the library in question (for example gtk3-demo.exe in mingw-gtk3). Other examples are helper executables which are used by the library itself internally (for example gspawn-win32-helper.exe in mingw-glib2). -Executables which are required for proper functionality of the libraries must be packaged in the matching mingw32/mingw64 subpackage. All other executables are discouraged, but may be packaged in optional (dependent) subpackages at a packager's discretion. +Executables which are required for proper functionality of the libraries must be +packaged in the matching mingw32/mingw64 subpackage. Other optional executables +targetted at end users should be packaged (for example certtool.exe in GNUTLS). +Executables targetted at developers are discouraged, but may be packaged in +optional (dependent) subpackages at a packager's discretion. -== Files which are already part of native packages +=== Files which are already part of native packages There are various types of files which are simply duplicates of equivalent files found in Fedora native packages. These files should not be packaged in the MinGW package. The following files don't need to be packaged in the MinGW package when their native counterpart already contains them: @@ -449,6 +463,10 @@ The following files don't need to be packaged in the MinGW package when their na * Autoconf files (`+%{mingw32_datadir}/aclocal+` / `+%{mingw64_datadir}/aclocal+`) * gtk-doc files (`+%{mingw32_datadir}/gtk-doc+` / `+%{mingw64_datadir}/gtk-doc+`) +Note, generic Documentation aimed at end users, as opposed to developers, +should be included where it is likely that application developers will want +to bundle it with their Windows installers. + == Example Specfile .... From 3bb7fe3cfd997b9d09ed204c98b5b17751dfdb6c Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: [PATCH 31/232] mingw: sanitize line breaks in paragraphs As a result of automated conversion from previous formats, the paragraph text is mostly unbroken long lines, but there are also some arbitrary line breaks present. Long lines lead to very unfriendly patch diffs, both for command line tools, and also online review tools like Pagure. Thus this commit breaks all paragraphs at 79 characters. Tables and formatted examples are left untouched, since their content is easier to review if it is allowed to extend to its natural formatted width. Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index 4e3c5ed..8e08e6f 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -2,22 +2,41 @@ == Introduction -The Fedora MinGW project's mission is to provide an excellent development environment for Fedora users who wish to cross-compile their programs to run on Windows, minimizing the need to use Windows at all. In the past developers have had to port and compile all of the libraries and tools they have needed, and this huge effort has happened independently many times over. We aim to eliminate duplication of work for application developers by providing a range of libraries and development tools which have already been ported to the MinGW cross-compiler environment. This means that developers will not need to recompile the application stack themselves, but can concentrate just on the changes needed to their own application. +The Fedora MinGW project's mission is to provide an excellent development +environment for Fedora users who wish to cross-compile their programs to run on +Windows, minimizing the need to use Windows at all. In the past developers have +had to port and compile all of the libraries and tools they have needed, and +this huge effort has happened independently many times over. We aim to eliminate +duplication of work for application developers by providing a range of libraries +and development tools which have already been ported to the MinGW cross-compiler +environment. This means that developers will not need to recompile the +application stack themselves, but can concentrate just on the changes needed to +their own application. The targets Win32 and Win64 are supported. == Track Fedora native package versions -In general terms, cross-compiled MinGW versions of packages which are already natively available in Fedora, should follow the native Fedora package as closely as possible. This means they should stay at the same version, include all the same patches as the native -Fedora package, and be built with the same configuration options. +In general terms, cross-compiled MinGW versions of packages which are already +natively available in Fedora, should follow the native Fedora package as closely +as possible. This means they should stay at the same version, include all the +same patches as the native Fedora package, and be built with the same +configuration options. == Follow Fedora policy -Cross compiled MinGW packages must follow Fedora policy, except where noted in this document. Cross compiled packages go through the same review process, GIT admin process etc. as other Fedora packages. +Cross compiled MinGW packages must follow Fedora policy, except where noted in +this document. Cross compiled packages go through the same review process, GIT +admin process etc. as other Fedora packages. == Package naming -MinGW packages require special naming to denote the appropriate CPU architecture the binaries have been built for. There should *never* be a package prefixed with `+mingw-+` output during a build. The `+mingw-+` prefix is exclusive for RPM spec file names and the source RPM file name. The CPU architecture specific packages are created by sections with `+%files -n mingw32-foo+` or `+%files -n mingw64-foo+`. +MinGW packages require special naming to denote the appropriate CPU architecture +the binaries have been built for. There should *never* be a package prefixed +with `+mingw-+` output during a build. The `+mingw-+` prefix is exclusive for +RPM spec file names and the source RPM file name. The CPU architecture specific +packages are created by sections with `+%files -n mingw32-foo+` or +`+%files -n mingw64-foo+`. [cols=",",] |======================================================= @@ -28,7 +47,11 @@ MinGW packages require special naming to denote the appropriate CPU architecture == Base packages -The base packages provide a root filesystem, base libraries, binutils (basic programs like 'strip', 'ld' etc), the compiler (gcc) and the Win32/Win64 API. Packages may need to depend on one or more of these. In particular, almost all packages should BuildRequire `+mingw32-filesystem+`, `+mingw64-filesystem+`, `+mingw32-gcc+` and `+mingw64-gcc+`. +The base packages provide a root filesystem, base libraries, binutils (basic +programs like 'strip', 'ld' etc), the compiler (gcc) and the Win32/Win64 API. +Packages may need to depend on one or more of these. In particular, almost all +packages should BuildRequire `+mingw32-filesystem+`, `+mingw64-filesystem+`, +`+mingw32-gcc+` and `+mingw64-gcc+`. [cols=",",] |================================================================================================================================================================================================================================= @@ -41,12 +64,16 @@ The base packages provide a root filesystem, base libraries, binutils (basic pro == Build for multiple targets -The goal of the MinGW framework is to provide an easy way for package maintainers to build their packages for multiple targets using one .spec file. To aid developers in this several RPM macros have been developed which are part of the mingw-filesystem package. -These RPM macros will be explained later on in these guidelines. +The goal of the MinGW framework is to provide an easy way for package +maintainers to build their packages for multiple targets using one .spec file. +To aid developers in this several RPM macros have been developed which are part +of the mingw-filesystem package. These RPM macros will be explained later on in +these guidelines. By default a MinGW package will be built for both the Win32 and Win64 targets. -When a package can only be built for either one of these targets this can be indicated by setting one of these: +When a package can only be built for either one of these targets this can be +indicated by setting one of these: [cols=",",] |=============================================================== @@ -56,13 +83,19 @@ When a package can only be built for either one of these targets this can be ind == One source RPM, separate binary RPMs per-target -Each cross compiled MinGW package which builds binaries for a specific target should put the binaries for that target in a separate subpackage. So if a package `+foo+` builds binaries for the Win32 and Win64 targets, then the source RPM should provide two subpackages named `+mingw32-foo+` and `+mingw64-foo+`. +Each cross compiled MinGW package which builds binaries for a specific target +should put the binaries for that target in a separate subpackage. So if a +package `+foo+` builds binaries for the Win32 and Win64 targets, then the +source RPM should provide two subpackages named `+mingw32-foo+` and +`+mingw64-foo+`. -This means that a spec file must contains %package and %files sections for all the targets. +This means that a spec file must contains %package and %files sections for all +the targets. -If a package contains translations then all calls to the `+%find_lang+` must be replaced by `+%mingw_find_lang+`. -This causes all translation filelists to be split in per-target filelists. -For example: when a spec file contains something like this: +If a package contains translations then all calls to the `+%find_lang+` must be +replaced by `+%mingw_find_lang+`. This causes all translation filelists to be +split in per-target filelists. For example: when a spec file contains something +like this: .... %install @@ -70,8 +103,9 @@ For example: when a spec file contains something like this: %mingw_find_lang foo .... -then two files will get created named `+mingw32-foo.lang+` and `+mingw64-foo.lang+`. -These file lists can be included in the %files section for the targets: +then two files will get created named `+mingw32-foo.lang+` and +`+mingw64-foo.lang+`. These file lists can be included in the %files section +for the targets: .... %files -n mingw32-foo -f mingw32-foo.lang @@ -145,9 +179,12 @@ These file lists can be included in the %files section for the targets: == Filenames of the cross-compilers and binutils -The MinGW cross-compilers and binutils are Fedora binaries and are therefore placed in `+%{_bindir}+` (i.e., `+/usr/bin+`) according to the FHS and Fedora guidelines. +The MinGW cross-compilers and binutils are Fedora binaries and are therefore +placed in `+%{_bindir}+` (i.e., `+/usr/bin+`) according to the FHS and Fedora +guidelines. -The MinGW cross-compilers and binutils which generate i686 binaries for Windows are named: +The MinGW cross-compilers and binutils which generate i686 binaries for Windows +are named: .... %{_bindir}/i686-w64-mingw32-gcc @@ -171,11 +208,15 @@ name, i.e., etc. .... -The same also applies for the x86_64 target. This target uses 'x86_64-w64-mingw32' as prefix instead of 'i686-w64-mingw32' +The same also applies for the x86_64 target. This target uses +'x86_64-w64-mingw32' as prefix instead of 'i686-w64-mingw32' == Naming of the root filesystem -The root filesystem contains Windows executables and DLLs and any other Windows-only files. It is necessary both because we need to store Windows libraries in order to link further libraries which depend on them, and also because MinGW requires a root filesystem location. +The root filesystem contains Windows executables and DLLs and any other +Windows-only files. It is necessary both because we need to store Windows +libraries in order to link further libraries which depend on them, and also +because MinGW requires a root filesystem location. The location for Win32 target is provided by the macro: @@ -191,8 +232,9 @@ And the Win64 target is provided by the macro: == Standard mingw RPM macros -The `+mingw-filesystem+` package provides a number of convenience macros for the cross compiled sysroot directories, and -toolchain. It is mandatory to use these macros in all MinGW cross compiled packages submitted to Fedora. +The `+mingw-filesystem+` package provides a number of convenience macros for +the cross compiled sysroot directories, and toolchain. It is mandatory to use +these macros in all MinGW cross compiled packages submitted to Fedora. === Toolchain macros @@ -270,7 +312,8 @@ Win64 specific macros: === Filesystem location macros -The following macros are for use in %build, %install and %files sections of the RPM spec +The following macros are for use in %build, %install and %files sections of the +RPM spec For the Win32 target: @@ -310,19 +353,26 @@ For the Win64 target: == Compilation of binaries -In order to build binaries for multiple targets we have to call commands like `+./configure+` and `+make+` multiple times (once for each target). -If one has to write this all out in a spec file then it will lead to duplicate code. -To reduce the amount of duplication, several RPM macros have been introduced to help with the compilation. -These macros are `+%mingw_configure+`, `+%mingw_cmake+`, `+%mingw_cmake_kde4+`, `+%mingw_qmake_qt4+`, `+%mingw_qmake_qt5+` and `+%mingw_make+` - -These macros use out of source compilation to build binaries for all the targets. -Almost all packages support out of source compilation or require slight patching. The only known exceptions to date are zlib and openssl. -Packages which don't support out of source compilation may require a different approach like performing everything in the %install phase. -If you happen to stumble across a package which requires a different approach feel free to contact us on the Fedora MinGW mailing list - -Some packages need to be built multiple times for each target. Examples of this are packages which have to be built once for a static version and once for a shared version. -Such packages can add a custom suffix to the build directory used. -Say you've got something like below: +In order to build binaries for multiple targets we have to call commands like +`+./configure+` and `+make+` multiple times (once for each target). If one has +to write this all out in a spec file then it will lead to duplicate code. To +reduce the amount of duplication, several RPM macros have been introduced to +help with the compilation. These macros are `+%mingw_configure+`, +`+%mingw_cmake+`, `+%mingw_cmake_kde4+`, `+%mingw_qmake_qt4+`, +`+%mingw_qmake_qt5+` and `+%mingw_make+` + +These macros use out of source compilation to build binaries for all the +targets. Almost all packages support out of source compilation or require +slight patching. The only known exceptions to date are zlib and openssl. +Packages which don't support out of source compilation may require a different +approach like performing everything in the %install phase. If you happen to +stumble across a package which requires a different approach feel free to +contact us on the Fedora MinGW mailing list + +Some packages need to be built multiple times for each target. Examples of this +are packages which have to be built once for a static version and once for a +shared version. Such packages can add a custom suffix to the build directory +used. Say you've got something like below: .... mkdir build_shared @@ -343,35 +393,48 @@ This can be rewritten to something like this: .... Most packages used the command `+make %{?_smp_mflags}+` to build the package. -In the MinGW cross compiler framework you have to use `+%mingw_make %{?_smp_mflags}+` to build the package for all configured targets. -As with the `+%mingw_configure+` macro you can also use the MINGW_BUILDDIR_SUFFIX environment variable to indicate a custom suffix to the build directory used - -To install the package the command `+make install DESTDIR=$RPM_BUILD_ROOT+` was used in almost all cases. -This can be rewritten to `+%mingw_make install DESTDIR=$RPM_BUILD_ROOT+` to install the package for all configured targets -The environment variable MINGW_BUILDDIR_SUFFIX can also be used here - -Some packages require some custom instructions before the files are ready to be packaged. Such code can remain as is. However, you may need to duplicate these instructions multiple times (for all configured targets). +In the MinGW cross compiler framework you have to use +`+%mingw_make %{?_smp_mflags}+` to build the package for all configured targets. +As with the `+%mingw_configure+` macro you can also use the +MINGW_BUILDDIR_SUFFIX environment variable to indicate a custom suffix to the +build directory used + +To install the package the command `+make install DESTDIR=$RPM_BUILD_ROOT+` was +used in almost all cases. This can be rewritten to +`+%mingw_make install DESTDIR=$RPM_BUILD_ROOT+` to install the package for all +configured targets. The environment variable MINGW_BUILDDIR_SUFFIX can also be +used here. + +Some packages require some custom instructions before the files are ready to be +packaged. Such code can remain as is. However, you may need to duplicate these +instructions multiple times (for all configured targets). == Dependencies -If a package contains binaries which depend on a DLL provided by another package, these dependencies should be expressed in the form: +If a package contains binaries which depend on a DLL provided by another +package, these dependencies should be expressed in the form: .... mingw32(foo.dll) .... -where `+foo.dll+` is the name of the DLL. The name must be converted to lowercase because Windows binaries contain case -insensitive dependencies. The form 'mingw32(foo.dll)' should be used for Win32 binaries and the form 'mingw64(foo.dll)' for Win64 binaries. +where `+foo.dll+` is the name of the DLL. The name must be converted to +lowercase because Windows binaries contain case insensitive dependencies. The +form 'mingw32(foo.dll)' should be used for Win32 binaries and the form +'mingw64(foo.dll)' for Win64 binaries. -Correct dependency generation is done automatically. Packagers should start their spec files with this line: +Correct dependency generation is done automatically. Packagers should start +their spec files with this line: .... %{?mingw_package_header} .... -All binary packages should depend on `+mingw32-filesystem+` or `+mingw64-filesystem+` (depending on the files in the package). +All binary packages should depend on `+mingw32-filesystem+` or +`+mingw64-filesystem+` (depending on the files in the package). -All specfiles should BuildRequire at least one of these (depending on the targets for which you want to build): +All specfiles should BuildRequire at least one of these (depending on the +targets for which you want to build): `+BuildRequires:  mingw32-filesystem+` + `+BuildRequires:  mingw64-filesystem+` @@ -394,26 +457,34 @@ unless they contain Fedora native executables. All libraries must be built as DLLs. -Because of the peculiarity of Windows, DLLs are stored in the `+%{mingw32_bindir}+` directory, along with a control file in -the `+%{mingw32_libdir}+` directory. For example, for a library called `+foo+` there would be: +Because of the peculiarity of Windows, DLLs are stored in the +`+%{mingw32_bindir}+` directory, along with a control file in the +`+%{mingw32_libdir}+` directory. For example, for a library called `+foo+` +there would be: .... %{mingw32_bindir}/foo.dll %{mingw32_libdir}/foo.dll.a .... -The `+foo.dll+` file is the main library, `+foo.dll.a+` is a stub linked to applications so they can find the library at runtime. All of these files are required in those locations in order to link successfully. The `+.dll+` may contain a version number although not always (e.g., `+foo-0.dll+`). +The `+foo.dll+` file is the main library, `+foo.dll.a+` is a stub linked to +applications so they can find the library at runtime. All of these files are +required in those locations in order to link successfully. The `+.dll+` may +contain a version number although not always (e.g., `+foo-0.dll+`). === Do not use %\{mingw32_bindir}/* or %\{mingw32_libdir}/* in %files section -The `+%files+` section must list DLLs and import libraries separately. Packages must NOT use `+%{mingw32_bindir}/*+` or -`+%{mingw32_libdir}/*+` +The `+%files+` section must list DLLs and import libraries separately. Packages +must NOT use `+%{mingw32_bindir}/*+` or `+%{mingw32_libdir}/*+` -The reason for this is that libtool is very fragile and will give up on building a DLL very easily. Therefore we force the name of the DLL to be listed explicitly in the `+%files+` section in order to catch this during RPM builds. +The reason for this is that libtool is very fragile and will give up on building +a DLL very easily. Therefore we force the name of the DLL to be listed +explicitly in the `+%files+` section in order to catch this during RPM builds. === Stripping -Libraries and executables should be stripped. This is done correctly and automatically if the spec file starts with this line: +Libraries and executables should be stripped. This is done correctly and +automatically if the spec file starts with this line: .... %{?mingw_package_header} @@ -421,7 +492,9 @@ Libraries and executables should be stripped. This is done correctly and automat === Debuginfo subpackage -Most binaries contain debugging symbols when the package gets built. To split the debugging symbols to a separate debuginfo package (as is done with native Fedora packages) the spec file must include these lines: +Most binaries contain debugging symbols when the package gets built. To split +the debugging symbols to a separate debuginfo package (as is done with native +Fedora packages) the spec file must include these lines: .... %{?mingw_package_header} @@ -429,7 +502,9 @@ Most binaries contain debugging symbols when the package gets built. To split th %{?mingw_debug_package} .... -The `+%{?mingw_debug_package}+` line must be placed after the `+%description tag+`. Otherwise spectool and other RPM tools may fail to function +The `+%{?mingw_debug_package}+` line must be placed after the +`+%description tag+`. Otherwise spectool and other RPM tools may fail to +function. == File listing @@ -443,8 +518,11 @@ satisfy either build/test usage or the creation of Windows installers. === Executables (EXEs) -Most libraries also provide executables. These can include executables which can be used to test or showcase the library in question (for example gtk3-demo.exe in mingw-gtk3). -Other examples are helper executables which are used by the library itself internally (for example gspawn-win32-helper.exe in mingw-glib2). +Most libraries also provide executables. These can include executables which +can be used to test or showcase the library in question (for example +gtk3-demo.exe in mingw-gtk3). Other examples are helper executables which are +used by the library itself internally (for example gspawn-win32-helper.exe in +mingw-glib2). Executables which are required for proper functionality of the libraries must be packaged in the matching mingw32/mingw64 subpackage. Other optional executables @@ -454,8 +532,10 @@ optional (dependent) subpackages at a packager's discretion. === Files which are already part of native packages -There are various types of files which are simply duplicates of equivalent files found in Fedora native packages. These files should not be packaged in the MinGW package. -The following files don't need to be packaged in the MinGW package when their native counterpart already contains them: +There are various types of files which are simply duplicates of equivalent files +found in Fedora native packages. These files should not be packaged in the MinGW +package. The following files don't need to be packaged in the MinGW package when +their native counterpart already contains them: * Man pages (`+%{mingw32_mandir}+` / `+%{mingw64_mandir}+`) * Info files (`+%{mingw32_infodir}+` / `+%{mingw64_infodir}+`) From d12471f2e5c492b23a70c565d2f45e8bbe2cd89b Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: [PATCH 32/232] mingw: fix mangled formatting of filesytem hierarchy The formatting of this section got mangled at one point in the document format conversion, so doesn't render cleanly currently. Switch to the pre-formatted paragraph syntax, and split it into two separate paragraphs. Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index 8e08e6f..6ca003f 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -115,67 +115,75 @@ for the targets: == Filesystem layout -`+[root]+` + -`+  |+` + -`+  +- etc+` + -`+  |   |+` + -`+  |   +- rpm+` + -`+  |       |+` + -`+  |       +- macros.mingw+` + -`+  |       +- macros.mingw32+` + -`+  |       +- macros.mingw64+` + -`+  |+` + -`+  +- usr+` + -`+      |+` + -`+      +- bin   - Links to MinGW cross compiler toolchain+` + -`+      |   |+` + -`+      |   +- i686-w64-mingw32-cpp+` + -`+      |   +- i686-w64-mingw32-gcc+` + -`+      |   +- i686-w64-mingw32-g+++` + -`+      |   +- x86_64-w64-mingw32-cpp+` + -`+      |   +- x86_64-w64-mingw32-gcc+` + -`+      |   +- x86_64-w64-mingw32-g+++` + -`+      |   +- ... etc..+` + -`+      |+` + -`+      +- lib+` + -`+      |   |+` + -`+      |   +- rpm+` + -`+      |       |+` + -`+      |       +- mingw-find-debuginfo.sh - extract debug information from Win32 and Win64 binaries+` + -`+      |       +- mingw-find-lang.sh - generates per-target file lists containing translations+` + -`+      |       +- mingw-find-provides.sh - extra DLL names+` + -`+      |       +- mingw-find-requires.sh - discover required DLL names+` + -`+      |+` + -`+      +- i686-w64-mingw32  - root of mingw toolchain and binaries for the Win32 target - see next diagram+` + -`+      +- x86_64-w64-mingw32  - root of mingw toolchain and binaries for the Win64 target - see next diagram+` - -`+/usr/i686-w64-mingw32+` + -`+/usr/x86_64-w64-mingw32+` + -`+  |+` + -`+  +- bin  - Binutils toolchain binaries for the target+` + -`+  |   |+` + -`+  |   +- ar+` + -`+  |   +- as+` + -`+  |   +- dlltool+` + -`+  |   +- ld+` + -`+  |   +- ... etc ...+` + -`+  |+` + -`+  +- lib  - Binutils toolchain support libraries / files for the target+` + -`+  |+` + -`+  +- sys-root  - root for cross compiled MinGW binaries+` + -`+      |+` + -`+      +- mingw+` + -`+          |+` + -`+          +- bin     - cross-compiled MinGW binaries & runtime DLL parts+` + -`+          +- etc     - configuration files+` + -`+          +- include - include files for cross compiled MinGW libs+` + -`+          +- lib     - cross-compiled static MinGW libraries & linktime DLL parts+` + -`+          |   |+` + -`+          |   +- pkgconfig  - pkg-config definitions for libraries+` + -`+          |+` + -`+          +- share+` + -`+              |+` + -`+              +- man+` +Integration into the main root filesystem layout is as follows: + +.... +[root] + | + +- etc + | | + | +- rpm + | | + | +- macros.mingw + | +- macros.mingw32 + | +- macros.mingw64 + | + +- usr + | + +- bin - Links to MinGW cross compiler toolchain + | | + | +- i686-w64-mingw32-cpp + | +- i686-w64-mingw32-gcc + | +- i686-w64-mingw32-g++ + | +- x86_64-w64-mingw32-cpp + | +- x86_64-w64-mingw32-gcc + | +- x86_64-w64-mingw32-g++ + | +- ... etc.. + | + +- lib + | | + | +- rpm + | | + | +- mingw-find-debuginfo.sh - extract debug information from Win32 and Win64 binaries + | +- mingw-find-lang.sh - generates per-target file lists containing translations + | +- mingw-find-provides.sh - extra DLL names + | +- mingw-find-requires.sh - discover required DLL names + | + +- i686-w64-mingw32 - root of mingw toolchain and binaries for the Win32 target - see next diagram + +- x86_64-w64-mingw32 - root of mingw toolchain and binaries for the Win64 target - see next diagram+` +.... + +The bulk of the packaged content is located under the respective MinGW root, +one of `+/usr/i686-w64-mingw32+` + `+/usr/x86_64-w64-mingw32+`: + +.... +[mingw-root] + | + +- bin - Binutils toolchain binaries for the target + | | + | +- ar + | +- as + | +- dlltool + | +- ld + | +- ... etc ... + | + +- lib - Binutils toolchain support libraries / files for the target + | + +- sys-root - root for cross compiled MinGW binaries + | + +- mingw + | + +- bin - cross-compiled MinGW binaries & runtime DLL parts + +- etc - configuration files + +- include - include files for cross compiled MinGW libs + +- lib - cross-compiled static MinGW libraries & linktime DLL parts + | | + | +- pkgconfig - pkg-config definitions for libraries + | + +- share + | + +- man +.... == Filenames of the cross-compilers and binutils From 9b8a0ad3fb6e1b4938a5492d4b1796fb87192f95 Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: [PATCH 33/232] mingw: remove vertical alignment of example spec field values Illustrating vertically aligned field values is undesirable as they inevitably slip out of alignment over time as changes are made. Since there is no Fedora standard for this, it doesn't make sense to promote it as a specific formatting approach in MinGW guidelines. Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index 6ca003f..c252926 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -560,30 +560,30 @@ to bundle it with their Windows installers. .... %{?mingw_package_header} -Name: mingw-example -Version: 1.0.0 -Release: 1%{?dist} -Summary: MinGW compiled example library +Name: mingw-example +Version: 1.0.0 +Release: 1%{?dist} +Summary: MinGW compiled example library -License: LGPL-2.1-or-later -URL: https://fedoraproject.org -Source: https://fedoraproject.org/example-%{version}.tar.bz2 +License: LGPL-2.1-or-later +URL: https://fedoraproject.org +Source: https://fedoraproject.org/example-%{version}.tar.bz2 -BuildArch: noarch +BuildArch: noarch -BuildRequires: mingw32-filesystem -BuildRequires: mingw32-gcc -BuildRequires: mingw32-binutils -BuildRequires: mingw32-gettext -BuildRequires: mingw32-win-iconv -BuildRequires: mingw32-zlib +BuildRequires: mingw32-filesystem +BuildRequires: mingw32-gcc +BuildRequires: mingw32-binutils +BuildRequires: mingw32-gettext +BuildRequires: mingw32-win-iconv +BuildRequires: mingw32-zlib -BuildRequires: mingw64-filesystem -BuildRequires: mingw64-gcc -BuildRequires: mingw64-binutils -BuildRequires: mingw64-gettext -BuildRequires: mingw64-win-iconv -BuildRequires: mingw64-zlib +BuildRequires: mingw64-filesystem +BuildRequires: mingw64-gcc +BuildRequires: mingw64-binutils +BuildRequires: mingw64-gettext +BuildRequires: mingw64-win-iconv +BuildRequires: mingw64-zlib %description @@ -596,28 +596,28 @@ MinGW compiled example library. # Win32 %package -n mingw32-example -Summary: MinGW compiled example library for the Win32 target +Summary: MinGW compiled example library for the Win32 target %description -n mingw32-example MinGW compiled example library for the Win32 target. %package -n mingw32-example-static -Summary: Static version of the MinGW Win32 compiled example library -Requires: mingw32-example = %{version}-%{release} +Summary: Static version of the MinGW Win32 compiled example library +Requires: mingw32-example = %{version}-%{release} %description -n mingw32-example-static Static version of the MinGW Win32 compiled example library. # Win64 %package -n mingw64-example -Summary: MinGW compiled example library for the Win64 target +Summary: MinGW compiled example library for the Win64 target %description -n mingw64-example MinGW compiled example library for the Win64 target. %package -n mingw64-example-static -Summary: Static version of the MinGW Win64 compiled example library -Requires: mingw64-example = %{version}-%{release} +Summary: Static version of the MinGW Win64 compiled example library +Requires: mingw64-example = %{version}-%{release} %description -n mingw64-example-static Static version of the MinGW Win64 compiled example library. From b36bb4097135abea9f5bff7ddc3f488fac434278 Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Feb 03 2023 11:06:30 +0000 Subject: [PATCH 34/232] mingw: add docs about ucrt64 build target This was introduced in F37 https://fedoraproject.org/wiki/Changes/F37MingwUCRT Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index c252926..10e25fc 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -13,7 +13,10 @@ environment. This means that developers will not need to recompile the application stack themselves, but can concentrate just on the changes needed to their own application. -The targets Win32 and Win64 are supported. +The targets Win32 and Win64 are supported with the MSVCRT runtime. The target +Win64 with the UCRT runtime is also supported, however, only for the base +toolchain. Builds for UCRT are not enabled for packages above the toolchain +at this time. == Track Fedora native package versions @@ -35,14 +38,15 @@ MinGW packages require special naming to denote the appropriate CPU architecture the binaries have been built for. There should *never* be a package prefixed with `+mingw-+` output during a build. The `+mingw-+` prefix is exclusive for RPM spec file names and the source RPM file name. The CPU architecture specific -packages are created by sections with `+%files -n mingw32-foo+` or -`+%files -n mingw64-foo+`. +packages are created by sections with `+%files -n mingw32-foo+`, +`+%files -n mingw64-foo+` or `+%files -n ucrt64-foo+`. [cols=",",] |======================================================= |`+mingw-+` |Used for source package and RPM spec name -|`+mingw32-+` |Used for packages which are built for Win32 -|`+mingw64-+` |Used for packages which are built for Win64 +|`+mingw32-+` |Used for packages which are built for Win32 with the MSVCRT runtime +|`+mingw64-+` |Used for packages which are built for Win64 with the MSVCRT runtime +|`+ucrt64-+` |Used for packages which are built for Win64 with the UCRT runtime |======================================================= == Base packages @@ -55,11 +59,11 @@ packages should BuildRequire `+mingw32-filesystem+`, `+mingw64-filesystem+`, [cols=",",] |================================================================================================================================================================================================================================= -|`+mingw32-filesystem+` / `+mingw64-filesystem+` |Core filesystem directory layout, and RPM macros for spec files. Equivalent to 'filesystem' RPM -|`+mingw32-binutils+` / `+mingw64-binutils+` |Cross-compiled binutils (utilities like 'strip', 'as', 'ld') which understand Windows executables and DLLs. Equivalent to 'binutils' RPM -|`+mingw32-gcc+` / `+mingw64-gcc+` |GNU compiler collection. Compilers for C and C++ which cross-compile to a Windows target. Equivalent to gcc RPM -|`+mingw32-crt+` / `+mingw64-crt+` |Base libraries for core MinGW runtime & development environment. Equivalent to 'glibc' RPM -|`+mingw32-headers+` / `+mingw64-headers+` |Win32 and Win64 API. A free (public domain) reimplementation of the header files required to link to the Win32 and Win64 API. No direct equivalent in base Fedora - glibc-devel is closest +|`+mingw32-filesystem+` / `+mingw64-filesystem+` / `+ucrt64-filesystem+` |Core filesystem directory layout, and RPM macros for spec files. Equivalent to 'filesystem' RPM +|`+mingw32-binutils+` / `+mingw64-binutils+` / `+ucrt64-binutils+` |Cross-compiled binutils (utilities like 'strip', 'as', 'ld') which understand Windows executables and DLLs. Equivalent to 'binutils' RPM +|`+mingw32-gcc+` / `+mingw64-gcc+` / `+ucrt64-gcc+` |GNU compiler collection. Compilers for C and C++ which cross-compile to a Windows target. Equivalent to gcc RPM +|`+mingw32-crt+` / `+mingw64-crt+` / `+ucrt64-crt+` |Base libraries for core MinGW runtime & development environment. Equivalent to 'glibc' RPM +|`+mingw32-headers+` / `+mingw64-headers+` / `+ucrt64-headers+` |Win32 and Win64 API. A free (public domain) reimplementation of the header files required to link to the Win32 and Win64 API. No direct equivalent in base Fedora - glibc-devel is closest |================================================================================================================================================================================================================================= == Build for multiple targets @@ -70,24 +74,28 @@ To aid developers in this several RPM macros have been developed which are part of the mingw-filesystem package. These RPM macros will be explained later on in these guidelines. -By default a MinGW package will be built for both the Win32 and Win64 targets. +By default a MinGW package will be built for both the Win32 and Win64 targets +with the MSVCRT runtime. Building of the Win64 target with the UCRT64 runtime +is not yet enabled by default. -When a package can only be built for either one of these targets this can be -indicated by setting one of these: +When a package can only be built for a subset of these targets this can be +indicated by setting one or more of these: [cols=",",] |=============================================================== -|`+%global mingw_build_win32 0+` |Don't build for the Win32 target -|`+%global mingw_build_win64 0+` |Don't build for the Win64 target +|`+%global mingw_build_win32 0+` |Don't build for the Win32 target with the MSVCRT runtime +|`+%global mingw_build_win64 0+` |Don't build for the Win64 target with the MSVCRT runtime +|`+%global mingw_build_ucrt64 0+` |Don't build for the Win64 target with the UCRT runtime |=============================================================== == One source RPM, separate binary RPMs per-target Each cross compiled MinGW package which builds binaries for a specific target should put the binaries for that target in a separate subpackage. So if a -package `+foo+` builds binaries for the Win32 and Win64 targets, then the -source RPM should provide two subpackages named `+mingw32-foo+` and -`+mingw64-foo+`. +package `+foo+` builds binaries for the Win32 and Win64 targets with the MSVCRT +runtime, then the source RPM should provide two subpackages named `+mingw32-foo+` +and `+mingw64-foo+`. If a package builds for the UCRT runtime, it will also +have a `+ucrt64-foo+` subpackage. This means that a spec file must contains %package and %files sections for all the targets. @@ -103,14 +111,16 @@ like this: %mingw_find_lang foo .... -then two files will get created named `+mingw32-foo.lang+` and -`+mingw64-foo.lang+`. These file lists can be included in the %files section -for the targets: +then one file per mingw target will get created named `+mingw32-foo.lang+`, +`+mingw64-foo.lang+`, and `+ucrt64-foo.lang+`. These file lists can be +included in the %files section for the targets: .... %files -n mingw32-foo -f mingw32-foo.lang %files -n mingw64-foo -f mingw64-foo.lang + + %files -n ucrt64-foo -f ucrt64-foo.lang .... == Filesystem layout @@ -138,6 +148,9 @@ Integration into the main root filesystem layout is as follows: | +- x86_64-w64-mingw32-cpp | +- x86_64-w64-mingw32-gcc | +- x86_64-w64-mingw32-g++ + | +- x86_64-w64-mingw32ucrt-cpp + | +- x86_64-w64-mingw32ucrt-gcc + | +- x86_64-w64-mingw32ucrt-g++ | +- ... etc.. | +- lib @@ -149,12 +162,14 @@ Integration into the main root filesystem layout is as follows: | +- mingw-find-provides.sh - extra DLL names | +- mingw-find-requires.sh - discover required DLL names | - +- i686-w64-mingw32 - root of mingw toolchain and binaries for the Win32 target - see next diagram - +- x86_64-w64-mingw32 - root of mingw toolchain and binaries for the Win64 target - see next diagram+` + +- i686-w64-mingw32 - root of mingw toolchain and binaries for the Win32 target with MSVCRT runtime - see next diagram + +- x86_64-w64-mingw32 - root of mingw toolchain and binaries for the Win64 target with MSVCRT runtime - see next diagram+` + +- x86_64-w64-mingw32urt - root of mingw toolchain and binaries for the Win64 target with UCRT runtime - see next diagram+` .... The bulk of the packaged content is located under the respective MinGW root, -one of `+/usr/i686-w64-mingw32+` + `+/usr/x86_64-w64-mingw32+`: +one of `+/usr/i686-w64-mingw32+`, `+/usr/x86_64-w64-mingw32+` and +`+/usr/x86_64-w64-mingw32ucrt+`: .... [mingw-root] @@ -192,7 +207,7 @@ placed in `+%{_bindir}+` (i.e., `+/usr/bin+`) according to the FHS and Fedora guidelines. The MinGW cross-compilers and binutils which generate i686 binaries for Windows -are named: +with the MSVCRT runtime are named: .... %{_bindir}/i686-w64-mingw32-gcc @@ -216,8 +231,10 @@ name, i.e., etc. .... -The same also applies for the x86_64 target. This target uses -'x86_64-w64-mingw32' as prefix instead of 'i686-w64-mingw32' +The same also applies for the x86_64 target with both MSVCRT +and UCRT runtimes. The target with MSVCRT uses 'x86_64-w64-mingw32' +as prefix instead of 'i686-w64-mingw32', while UCRT uses +'x86_64-w64-mingw32ucrt'. == Naming of the root filesystem @@ -226,18 +243,26 @@ Windows-only files. It is necessary both because we need to store Windows libraries in order to link further libraries which depend on them, and also because MinGW requires a root filesystem location. -The location for Win32 target is provided by the macro: +The location for Win32 target with MSVCRT runtime is provided by the macro: .... %{mingw32_sysroot} %{_prefix}/i686-w64-mingw32/sys-root .... -And the Win64 target is provided by the macro: +The Win64 target with MSVCRT runtime is provided by the macro: .... %{mingw64_sysroot} %{_prefix}/x86_64-w64-mingw32/sys-root .... +The Win64 target with UCRT runtime is provided by the macro: + +.... + %{ucrt64_sysroot} %{_prefix}/x86_64-w64-mingw32ucrt/sys-root +.... + + + == Standard mingw RPM macros The `+mingw-filesystem+` package provides a number of convenience macros for @@ -268,7 +293,7 @@ Generic macros: |mingw_strip |>= 95 |cross compiler 'strip' binary (which supports both Win32 and Win64 binaries) |================================================================================================================================================== -Win32 specific macros: +Win32 with MSVCRT runtime specific macros: [cols=",,,",] |=================================================================================================================================================== @@ -293,7 +318,7 @@ Win32 specific macros: |mingw32_target |>= 95 |i686-w64-mingw32 |Target platform for build |=================================================================================================================================================== -Win64 specific macros: +Win64 with MSVCRT runtime specific macros: [cols=",,,",] |=================================================================================================================================================== @@ -318,12 +343,37 @@ Win64 specific macros: |mingw64_target |>= 95 |x86_64-w64-mingw32 |Target platform for build |=================================================================================================================================================== +Win64 with UCRT runtime specific macros: + +[cols=",,,",] +|=================================================================================================================================================== +|Macro |Available in ucrt64-filesystem | Value |Explanation +|ucrt64_ar |>= 133 |x86_64-w64-mingw32ucrt-ar |cross compiler 'ar' binary +|ucrt64_cc |>= 133 |x86_64-w64-mingw32ucrt-gcc |cross compiler 'gcc' binary +|ucrt64_cflags |>= 133 |-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions --param=ssp-buffer-size=4 |Default compiler flags for C/C++ binaries +|ucrt64_cmake |>= 133 | |Call the 'cmake' binary for the Win64 target +|ucrt64_configure |>= 133 | |standard invocation for autotools 'configure' scripts +|ucrt64_cpp |>= 133 |x86_64-w64-mingw32ucrt-gcc -E |cross compiler 'cpp' binary +|ucrt64_env |>= 133 | |Set the correct environment variables for the Win64 target +|ucrt64_host |>= 133 |x86_64-w64-mingw32 |Host platform for build +|ucrt64_meson |>= 104 | |Call the meson binary for the Win64 target +|ucrt64_ninja |>= 104 | |Call the ninja binary for the Win64 target +|ucrt64_objcopy |>= 133 |x86_64-w64-mingw32ucrt-objcopy |cross compiler 'objcopy' binary +|ucrt64_objdump |>= 133 |x86_64-w64-mingw32ucrt-objdump |cross compiler 'objdump' binary +|ucrt64_pkg_config |>= 133 |x86_64-w64-mingw32ucrt-pkg-config |Call the pkg-config command for the Win64 target +|ucrt64_qmake_qt4 |>= 133 |ucrt64-qmake-qt4 |Call the Qt4 qmake command for the Win64 target +|ucrt64_qmake_qt5 |>= 133 |ucrt64-qmake-qt5 |Call the Qt5 qmake command for the Win64 target +|ucrt64_ranlib |>= 133 |x86_64-w64-mingw32ucrt-ranlib |cross compiler 'ranlib' binary +|ucrt64_strip |>= 133 |x86_64-w64-mingw32ucrt-strip |cross compiler 'strip' binary +|ucrt64_target |>= 133 |x86_64-w64-mingw32 |Target platform for build +|=================================================================================================================================================== + === Filesystem location macros The following macros are for use in %build, %install and %files sections of the RPM spec -For the Win32 target: +For the Win32 with MSVCRT runtime target: [cols=",,",] |=================================================================================================== @@ -341,7 +391,7 @@ For the Win32 target: |mingw32_sysroot |%\{_prefix}/i686-w64-mingw32/sys-root |Windows system root. |=================================================================================================== -For the Win64 target: +For the Win64 with MSVCRT runtime target: [cols=",,",] |=================================================================================================== @@ -359,6 +409,24 @@ For the Win64 target: |mingw64_sysroot |%\{_prefix}/x86_64-w64-mingw32/sys-root |Windows system root. |=================================================================================================== +For the Win64 with UCRT runtime target: + +[cols=",,",] +|=================================================================================================== +|ucrt64_bindir |%\{ucrt64_prefix}/bin |Location of Windows executables. +|ucrt64_datadir |%\{ucrt64_prefix}/share |Shared data used under Windows. +|ucrt64_docdir |%\{ucrt64_prefix}/share/doc |Documentation. +|ucrt64_infodir |%\{ucrt64_prefix}/share/info |Info files (see note below). +|ucrt64_includedir |%\{ucrt64_prefix}/include |Header files used when cross-compiling for Windows. +|ucrt64_libdir |%\{ucrt64_prefix}/lib |Windows libraries (see sections below). +|ucrt64_libexecdir |%\{ucrt64_prefix}/libexec | +|ucrt64_mandir |%\{ucrt64_prefix}/share/man |Man pages (see note below). +|ucrt64_prefix |%\{ucrt64_sysroot}/mingw |Windows equivalent of %\{_prefix}, required by MinGW. +|ucrt64_sbindir |%\{ucrt64_prefix}/sbin | +|ucrt64_sysconfdir |%\{ucrt64_prefix}/etc |Configuration files used when running under Windows. +|ucrt64_sysroot |%\{_prefix}/x86_64-w64-mingw32ucrt/sys-root |Windows system root. +|=================================================================================================== + == Compilation of binaries In order to build binaries for multiple targets we have to call commands like @@ -545,11 +613,11 @@ found in Fedora native packages. These files should not be packaged in the MinGW package. The following files don't need to be packaged in the MinGW package when their native counterpart already contains them: -* Man pages (`+%{mingw32_mandir}+` / `+%{mingw64_mandir}+`) -* Info files (`+%{mingw32_infodir}+` / `+%{mingw64_infodir}+`) -* Generic documentation (`+%{mingw32_docdir}+` / `+%{mingw64_docdir}+`) -* Autoconf files (`+%{mingw32_datadir}/aclocal+` / `+%{mingw64_datadir}/aclocal+`) -* gtk-doc files (`+%{mingw32_datadir}/gtk-doc+` / `+%{mingw64_datadir}/gtk-doc+`) +* Man pages (`+%{mingw32_mandir}+` / `+%{mingw64_mandir}+` / `+%{ucrt64_mandir}+`) +* Info files (`+%{mingw32_infodir}+` / `+%{mingw64_infodir}+` / `+%{ucrt64_infodir}+`) +* Generic documentation (`+%{mingw32_docdir}+` / `+%{mingw64_docdir}+` / `+%{ucrt64_docdir}+`) +* Autoconf files (`+%{mingw32_datadir}/aclocal+` / `+%{mingw64_datadir}/aclocal+` / `+%{ucrt64_datadir}/aclocal+`) +* gtk-doc files (`+%{mingw32_datadir}/gtk-doc+` / `+%{mingw64_datadir}/gtk-doc+` / `+%{ucrt64_datadir}/gtk-doc+`) Note, generic Documentation aimed at end users, as opposed to developers, should be included where it is likely that application developers will want From 8d9f98c9aa490e0572048f532b4f951142917139 Mon Sep 17 00:00:00 2001 From: Jerry James Date: Feb 14 2023 22:20:26 +0000 Subject: [PATCH 35/232] Update GAP packaging guidelines - Instead of the entire GAP distribution being installed in /usr/lib/gap (%{_gap_dir}), it is now split between a noarch part in %{_datadir}/gap (%{gap_libdir}) and an architecture-specific part in %{_libdir}/gap (%{gap_archdir}). - Remove bad advice about having multiple ExclusiveArch tags in a single spec file. - Various minor clarifications and presentation improvements. --- diff --git a/guidelines/modules/ROOT/pages/GAP.adoc b/guidelines/modules/ROOT/pages/GAP.adoc index a135953..7d48af4 100644 --- a/guidelines/modules/ROOT/pages/GAP.adoc +++ b/guidelines/modules/ROOT/pages/GAP.adoc @@ -1,6 +1,6 @@ = GAP Packaging Guidelines -This document describes the conventions and customs surrounding the proper packaging of https://gap-system.org/[GAP] add-on packages in Fedora. Throughout this document, we use the word _add-on_ to substitute for GAP upstream's use of the word _package_, to avoid confusion with RPM packages. +This document describes the conventions and customs surrounding the proper packaging of https://www.gap-system.org/[GAP] add-on packages in Fedora. Throughout this document, we use the word _add-on_ to substitute for GAP upstream's use of the word _package_, to avoid confusion with RPM packages. == Naming @@ -8,7 +8,9 @@ The main GAP package and its attendant libraries and help system are in packages == Add-on Location -GAP add-ons are written to be installed simply by unpacking them in an existing GAP directory tree. For most add-ons, the only build action necessary is building the documentation. However, since the add-on authors assumed this would happen within the GAP tree, add-ons freely use relative paths to access GAP files. For example, packages that use TTH to build documentation (see below) commonly invoke `+../../../convert.pl+`. The RPM spec file MUST account for this, either by altering the add-on to point to paths under `+%{_gap_dir}+`, or by creating symbolic links to create the appearance that the build is taking place inside the GAP tree. If the add-on is altered for the build, the spec file SHOULD arrange for the original (unaltered) files to be installed, so that paths are correct after installation. +Architecture-independent (noarch) packages MUST be installed in `+%{gap_libdir}/pkg/%{pkgname}+`, and architecture-specific packages in `+%{gap_archdir}/pkg/%{pkgname}+`, where `+%{pkgname}+` expands to the GAP name for the add-on. + +GAP add-ons are written to be installed simply by unpacking them in an existing GAP directory tree. For most add-ons, the only build action necessary is building the documentation. However, since the add-on authors assumed this would happen within the GAP tree, add-ons freely use relative paths to access GAP files. For example, packages that use TTH to build documentation (see below) commonly invoke `+../../../convert.pl+`. The RPM spec file MUST account for this, either by altering the add-on to point to paths under `+%{gap_libdir}+`, or by creating symbolic links to create the appearance that the build is taking place inside the GAP tree. If the add-on is altered for the build, the spec file SHOULD arrange for the original (unaltered) files to be installed, so that paths are correct after installation. GAP add-ons are frequently distributed in tarballs with a top-level directory of the form `addon-version`. The add-on SHOULD be installed without the version number. @@ -25,13 +27,13 @@ All add-ons MUST include `+BuildRequires: gap-devel+`, as that package contains Add-ons that use a `+buildman.pe+` or `+convert.pl+` script to build documentation also need `+BuildRequires: tth+` in order to build HTML documentation pages from TeX input. Some add-ons bundle these scripts, as well as a few auxiliary files. Add-ons containing any of the following files should be modified to link to the version of the file contained in the gap or gap-devel packages. -* `+gapmacro.tex+` → `+%{_gap_dir}/doc/gapmacro.tex+` -* `+gapmacrodoc.tex+` → `+%{_gap_dir}/doc/gapmacrodoc.tex+` -* `+manualbib.xml+` → `+%{_gap_dir}/doc/manualbib.xml+` -* `+manualbib.xml.bib+` → `+%{_gap_dir}/doc/manualbib.xml.bib+` -* `+manualindex+` → `+%{_gap_dir}/doc/manualindex+` -* `+buildman.pe+` → `+%{_gap_dir}/etc/buildman.pe+` -* `+convert.pl+` → `+%{_gap_dir}/etc/convert.pl+` +* `+gapmacro.tex+` → `+%{gap_libdir}/doc/gapmacro.tex+` +* `+gapmacrodoc.tex+` → `+%{gap_libdir}/doc/gapmacrodoc.tex+` +* `+manualbib.xml+` → `+%{gap_libdir}/doc/manualbib.xml+` +* `+manualbib.xml.bib+` → `+%{gap_libdir}/doc/manualbib.xml.bib+` +* `+manualindex+` → `+%{gap_libdir}/doc/manualindex+` +* `+buildman.pe+` → `+%{gap_libdir}/etc/buildman.pe+` +* `+convert.pl+` → `+%{gap_libdir}/etc/convert.pl+` === GAPDoc @@ -50,12 +52,12 @@ How these dependencies map onto the 3-level RPM dependency system of Requires, R == Unnecessary Files -GAP add-ons are intended to be unpacked in place within a GAP directory tree. Ordinarily, the entire distribution directory is copied into `+%{_gap_dir}/pkg+`. This includes the documentation directories, which are consumed by the tools contained in gap-online-help. However, some files are not needed in the final install directory. Files that should not appear there include: +GAP add-ons are intended to be unpacked in place within a GAP directory tree. Ordinarily, the entire distribution directory is copied into `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+`. This includes the documentation directories, which are consumed by the tools contained in gap-online-help. However, some files are not needed in the final install directory. Files that should not appear there include: * Textual descriptions of the add-on, such as a README * License files (COPYING, COPYRIGHT, LICENSE, etc.) * Files for building documentation, often called `+make_doc+` -* Files generated by LaTeX, including files with these suffixes: +* Files generated by LaTeX and associated tools, including files with these suffixes: ** .aux ** .bbl ** .blg @@ -70,33 +72,32 @@ Note that License files MUST still be included in the package with the %license The `+%gap_copy_docs+` macro is intended to make installation of documentation files easier. For most packages, ensure that the `doc` subdirectory exists in the buildroot, then invoke the macro without arguments in `+%install+`. For special cases, two optional arguments can be given: + * `+-d directory+`: for cases where the documentation directory is not named `doc`, or there are multiple documentation directories * `+-n package+`: the installed add-on directory name is assumed to be available from a macro `+%pkgname+`. If that is not the case, use this macro to give the main add-on directory name. == Documentation -Since GAP documentation must be installed under `+%{_gap_dir}/pkg+` for the builtin documentation browser to find it, such documentation SHOULD NOT be duplicated with `+%doc+`. However, the documentation SHOULD still be marked as such so that documentation-free installs work as expected. Most add-ons SHOULD include `+%docdir+` declarations in the `+%files+` section of the spec file; e.g., `+%docdir %{_gap_dir}/pkg/%{pkgname}/doc+` and `+%docdir %{_gap_dir}/pkg/%{pkgname}/htm+`. +Since GAP documentation MUST be installed under `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+` for the builtin documentation browser to find it, such documentation SHOULD NOT be duplicated with `+%doc+`. However, the documentation SHOULD still be marked as such so that documentation-free installs work as expected. Most add-ons SHOULD include `+%docdir+` declarations in the `+%files+` section of the spec file; e.g., `+%docdir %{gap_libdir}/pkg/%{pkgname}/doc+` and `+%docdir %{gap_libdir}/pkg/%{pkgname}/htm+`. == Architecture Fedora now encourages packagers to https://fedoraproject.org/wiki/Changes/EncourageI686LeafRemoval[not build packages for i686]. -For that reason, noarch GAP add-ons must include these tags: +For that reason, noarch GAP add-ons MUST include these tags: .... BuildArch: noarch ExclusiveArch: %{gap_arches} noarch .... -Architecture-specific GAP add-ons must instead include this tag: +Architecture-specific GAP add-ons MUST instead include this tag: .... ExclusiveArch: %{gap_arches} .... -However, any noarch subpackages, such as a documentation subpackage, must include this tag: -.... -ExclusiveArch: %{gap_arches} noarch -.... == Other RPM macros Other RPM macros that may be useful for GAP add-on spec files include the following: + * `+%gap_version+`: the version of the main GAP package; e.g., 4.12.0. -* `+%gap_dir+`: the root directory of the GAP installation, currently `/usr/lib/gap`. +* `+%gap_archdir+`: parent directory for arch-specific GAP add-ons, currently `+%{_libdir}/gap+`. +* `+%gap_libdir+`: the root directory of the GAP installation, currently `+%{_datadir}/gap+`. * `+%gap_arch+`: the GAP name for the build architecture; e.g., `x86_64-redhat-linux-gnu`. From 2bd983c83f80ae425c1110b41a6ee374c9e5b16e Mon Sep 17 00:00:00 2001 From: Carl George Date: Feb 16 2023 04:34:29 +0000 Subject: [PATCH 36/232] Indicate that MUST, SHOULD, etc. follow the RFC 2119 definitions --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 0ae108c..dd32452 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -40,6 +40,10 @@ though they were originally based on many other documents. They have been significantly modified over the years by many members of the Packaging Committee. +The key words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY +in these guidelines are to be interpreted as described in +https://www.rfc-editor.org/rfc/rfc2119[RFC 2119]. + Report issues with these guidelines, including typos, https://pagure.io/packaging-committee[here]. From 8b3c2cb6918b3f4571ec1624b273deff97ea35d7 Mon Sep 17 00:00:00 2001 From: Jerry James Date: Feb 16 2023 23:03:27 +0000 Subject: [PATCH 37/232] Add semantic line breaks to GAP.adoc --- diff --git a/guidelines/modules/ROOT/pages/GAP.adoc b/guidelines/modules/ROOT/pages/GAP.adoc index 7d48af4..13a6fd2 100644 --- a/guidelines/modules/ROOT/pages/GAP.adoc +++ b/guidelines/modules/ROOT/pages/GAP.adoc @@ -1,16 +1,24 @@ = GAP Packaging Guidelines -This document describes the conventions and customs surrounding the proper packaging of https://www.gap-system.org/[GAP] add-on packages in Fedora. Throughout this document, we use the word _add-on_ to substitute for GAP upstream's use of the word _package_, to avoid confusion with RPM packages. +This document describes the conventions and customs surrounding the proper packaging of https://www.gap-system.org/[GAP] add-on packages in Fedora. +Throughout this document, we use the word _add-on_ to substitute for GAP upstream's use of the word _package_, to avoid confusion with RPM packages. == Naming -The main GAP package and its attendant libraries and help system are in packages named gap, gap-libs, gap-core, gap-online-help, gap-devel, gap-vim, and libgap. To distinguish add-on packages from these core packages, add-ons MUST have names of the form gap-pkg-foo. For example, the FGA add-on is named gap-pkg-fga. +The main GAP package and its attendant libraries and help system are in packages named gap, gap-libs, gap-core, gap-online-help, gap-devel, gap-vim, and libgap. +To distinguish add-on packages from these core packages, add-ons MUST have names of the form gap-pkg-foo. +For example, the FGA add-on is named gap-pkg-fga. == Add-on Location Architecture-independent (noarch) packages MUST be installed in `+%{gap_libdir}/pkg/%{pkgname}+`, and architecture-specific packages in `+%{gap_archdir}/pkg/%{pkgname}+`, where `+%{pkgname}+` expands to the GAP name for the add-on. -GAP add-ons are written to be installed simply by unpacking them in an existing GAP directory tree. For most add-ons, the only build action necessary is building the documentation. However, since the add-on authors assumed this would happen within the GAP tree, add-ons freely use relative paths to access GAP files. For example, packages that use TTH to build documentation (see below) commonly invoke `+../../../convert.pl+`. The RPM spec file MUST account for this, either by altering the add-on to point to paths under `+%{gap_libdir}+`, or by creating symbolic links to create the appearance that the build is taking place inside the GAP tree. If the add-on is altered for the build, the spec file SHOULD arrange for the original (unaltered) files to be installed, so that paths are correct after installation. +GAP add-ons are written to be installed simply by unpacking them in an existing GAP directory tree. +For most add-ons, the only build action necessary is building the documentation. +However, since the add-on authors assumed this would happen within the GAP tree, add-ons freely use relative paths to access GAP files. +For example, packages that use TTH to build documentation (see below) commonly invoke `+../../../convert.pl+`. +The RPM spec file MUST account for this, either by altering the add-on to point to paths under `+%{gap_libdir}+`, or by creating symbolic links to create the appearance that the build is taking place inside the GAP tree. +If the add-on is altered for the build, the spec file SHOULD arrange for the original (unaltered) files to be installed, so that paths are correct after installation. GAP add-ons are frequently distributed in tarballs with a top-level directory of the form `addon-version`. The add-on SHOULD be installed without the version number. @@ -21,11 +29,14 @@ GAP itself can retrieve the version number from the add-on's `+PackageInfo.g+` f == BuildRequires -All add-ons MUST include `+BuildRequires: gap-devel+`, as that package contains essential tools needed for compiling binary modules and building documentation, as well as a set of RPM macros for use in spec files. Each add-on also MUST contain a `+BuildRequires+` that is dependent on the documentation style used by the GAP add-on. +All add-ons MUST include `+BuildRequires: gap-devel+`, as that package contains essential tools needed for compiling binary modules and building documentation, as well as a set of RPM macros for use in spec files. +Each add-on also MUST contain a `+BuildRequires+` that is dependent on the documentation style used by the GAP add-on. === TTH -Add-ons that use a `+buildman.pe+` or `+convert.pl+` script to build documentation also need `+BuildRequires: tth+` in order to build HTML documentation pages from TeX input. Some add-ons bundle these scripts, as well as a few auxiliary files. Add-ons containing any of the following files should be modified to link to the version of the file contained in the gap or gap-devel packages. +Add-ons that use a `+buildman.pe+` or `+convert.pl+` script to build documentation also need `+BuildRequires: tth+` in order to build HTML documentation pages from TeX input. +Some add-ons bundle these scripts, as well as a few auxiliary files. +Add-ons containing any of the following files should be modified to link to the version of the file contained in the gap or gap-devel packages. * `+gapmacro.tex+` → `+%{gap_libdir}/doc/gapmacro.tex+` * `+gapmacrodoc.tex+` → `+%{gap_libdir}/doc/gapmacrodoc.tex+` @@ -37,11 +48,13 @@ Add-ons that use a `+buildman.pe+` or `+convert.pl+` script to build documentati === GAPDoc -Add-ons that use GAPDoc to build documentation MUST include `+BuildRequires: GAPDoc-latex+` to pull in the necessary LaTeX packages. These packages do not need `+Requires: GAPDoc+`, since `+gap-core+` depends on GAPDoc. +Add-ons that use GAPDoc to build documentation MUST include `+BuildRequires: GAPDoc-latex+` to pull in the necessary LaTeX packages. +These packages do not need `+Requires: GAPDoc+`, since `+gap-core+` depends on GAPDoc. === Autodoc -Add-ons that use Autodoc to build documentation MUST include `+BuildRequires: gap-pkg-autodoc+`. Such packages do not need to include `+BuildRequires: GAPDoc-latex+`, as the Autodoc package `+Requires: GAPDoc-latex+`. +Add-ons that use Autodoc to build documentation MUST include `+BuildRequires: gap-pkg-autodoc+`. +Such packages do not need to include `+BuildRequires: GAPDoc-latex+`, as the Autodoc package `+Requires: GAPDoc-latex+`. == Requires, Recommends, and Suggests @@ -52,7 +65,11 @@ How these dependencies map onto the 3-level RPM dependency system of Requires, R == Unnecessary Files -GAP add-ons are intended to be unpacked in place within a GAP directory tree. Ordinarily, the entire distribution directory is copied into `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+`. This includes the documentation directories, which are consumed by the tools contained in gap-online-help. However, some files are not needed in the final install directory. Files that should not appear there include: +GAP add-ons are intended to be unpacked in place within a GAP directory tree. +Ordinarily, the entire distribution directory is copied into `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+`. +This includes the documentation directories, which are consumed by the tools contained in gap-online-help. +However, some files are not needed in the final install directory. +Files that should not appear there include: * Textual descriptions of the add-on, such as a README * License files (COPYING, COPYRIGHT, LICENSE, etc.) @@ -78,7 +95,9 @@ For special cases, two optional arguments can be given: == Documentation -Since GAP documentation MUST be installed under `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+` for the builtin documentation browser to find it, such documentation SHOULD NOT be duplicated with `+%doc+`. However, the documentation SHOULD still be marked as such so that documentation-free installs work as expected. Most add-ons SHOULD include `+%docdir+` declarations in the `+%files+` section of the spec file; e.g., `+%docdir %{gap_libdir}/pkg/%{pkgname}/doc+` and `+%docdir %{gap_libdir}/pkg/%{pkgname}/htm+`. +Since GAP documentation MUST be installed under `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+` for the builtin documentation browser to find it, such documentation SHOULD NOT be duplicated with `+%doc+`. +However, the documentation SHOULD still be marked as such so that documentation-free installs work as expected. +Most add-ons SHOULD include `+%docdir+` declarations in the `+%files+` section of the spec file; e.g., `+%docdir %{gap_libdir}/pkg/%{pkgname}/doc+` and `+%docdir %{gap_libdir}/pkg/%{pkgname}/htm+`. == Architecture From 2ed3e656849db99dc93f2d2935325047a6c5e1e0 Mon Sep 17 00:00:00 2001 From: James Antill Date: Feb 23 2023 17:20:48 +0000 Subject: [PATCH 38/232] Merge #1224 `Clean up the MinGW packaging guidelines` --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index cc5fbb3..10e25fc 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -2,69 +2,108 @@ == Introduction -The Fedora MinGW project's mission is to provide an excellent development environment for Fedora users who wish to cross-compile their programs to run on Windows, minimizing the need to use Windows at all. In the past developers have had to port and compile all of the libraries and tools they have needed, and this huge effort has happened independently many times over. We aim to eliminate duplication of work for application developers by providing a range of libraries and development tools which have already been ported to the MinGW cross-compiler environment. This means that developers will not need to recompile the application stack themselves, but can concentrate just on the changes needed to their own application. - -As of Fedora 17 a set of RPM macros and packages have been introduced which help packagers compile binaries for multiple targets. The targets Win32 and Win64 are supported. +The Fedora MinGW project's mission is to provide an excellent development +environment for Fedora users who wish to cross-compile their programs to run on +Windows, minimizing the need to use Windows at all. In the past developers have +had to port and compile all of the libraries and tools they have needed, and +this huge effort has happened independently many times over. We aim to eliminate +duplication of work for application developers by providing a range of libraries +and development tools which have already been ported to the MinGW cross-compiler +environment. This means that developers will not need to recompile the +application stack themselves, but can concentrate just on the changes needed to +their own application. + +The targets Win32 and Win64 are supported with the MSVCRT runtime. The target +Win64 with the UCRT runtime is also supported, however, only for the base +toolchain. Builds for UCRT are not enabled for packages above the toolchain +at this time. == Track Fedora native package versions -In general terms, cross-compiled MinGW versions of packages which are already natively available in Fedora, should follow the native Fedora package as closely as possible. This means they should stay at the same version, include all the same patches as the native -Fedora package, and be built with the same configuration options. - -The MinGW SIG have written an RPM comparison tool which makes it possible to compare cross compiled MinGW packages with the Fedora native packages, in order to determine whether versions, patches and configuration are aligned. +In general terms, cross-compiled MinGW versions of packages which are already +natively available in Fedora, should follow the native Fedora package as closely +as possible. This means they should stay at the same version, include all the +same patches as the native Fedora package, and be built with the same +configuration options. == Follow Fedora policy -Cross compiled MinGW packages must follow Fedora policy, except where noted in this document. Cross compiled packages go through the same review process, GIT admin process etc. as other Fedora packages. +Cross compiled MinGW packages must follow Fedora policy, except where noted in +this document. Cross compiled packages go through the same review process, GIT +admin process etc. as other Fedora packages. == Package naming -MinGW packages require special naming to denote the appropriate CPU architecture the binaries have been built for. There should *never* be a package prefixed with `+mingw-+` output during a build. The `+mingw-+` prefix is exclusive for RPM spec file names and the source RPM file name. The CPU architecture specific packages are created by sections with `+%files -n mingw32-foo+` or `+%files -n mingw64-foo+`. +MinGW packages require special naming to denote the appropriate CPU architecture +the binaries have been built for. There should *never* be a package prefixed +with `+mingw-+` output during a build. The `+mingw-+` prefix is exclusive for +RPM spec file names and the source RPM file name. The CPU architecture specific +packages are created by sections with `+%files -n mingw32-foo+`, +`+%files -n mingw64-foo+` or `+%files -n ucrt64-foo+`. [cols=",",] |======================================================= |`+mingw-+` |Used for source package and RPM spec name -|`+mingw32-+` |Used for packages which are built for Win32 -|`+mingw64-+` |Used for packages which are built for Win64 +|`+mingw32-+` |Used for packages which are built for Win32 with the MSVCRT runtime +|`+mingw64-+` |Used for packages which are built for Win64 with the MSVCRT runtime +|`+ucrt64-+` |Used for packages which are built for Win64 with the UCRT runtime |======================================================= == Base packages -The base packages provide a root filesystem, base libraries, binutils (basic programs like 'strip', 'ld' etc), the compiler (gcc) and the Win32/Win64 API. Packages may need to depend on one or more of these. In particular, almost all packages should BuildRequire `+mingw32-filesystem+`, `+mingw64-filesystem+`, `+mingw32-gcc+` and `+mingw64-gcc+`. The correct Requires flags will get added automatically when the `+%{?mingw_package_header}+` macro is mentioned in the spec file (as will be described later on in these guidelines) +The base packages provide a root filesystem, base libraries, binutils (basic +programs like 'strip', 'ld' etc), the compiler (gcc) and the Win32/Win64 API. +Packages may need to depend on one or more of these. In particular, almost all +packages should BuildRequire `+mingw32-filesystem+`, `+mingw64-filesystem+`, +`+mingw32-gcc+` and `+mingw64-gcc+`. [cols=",",] |================================================================================================================================================================================================================================= -|`+mingw32-filesystem+` / `+mingw64-filesystem+` |Core filesystem directory layout, and RPM macros for spec files. Equivalent to 'filesystem' RPM -|`+mingw32-binutils+` / `+mingw64-binutils+` |Cross-compiled binutils (utilities like 'strip', 'as', 'ld') which understand Windows executables and DLLs. Equivalent to 'binutils' RPM -|`+mingw32-gcc+` / `+mingw64-gcc+` |GNU compiler collection. Compilers for C and C++ which cross-compile to a Windows target. Equivalent to gcc RPM -|`+mingw32-crt+` / `+mingw64-crt+` |Base libraries for core MinGW runtime & development environment. Equivalent to 'glibc' RPM -|`+mingw32-headers+` / `+mingw64-headers+` |Win32 and Win64 API. A free (public domain) reimplementation of the header files required to link to the Win32 and Win64 API. No direct equivalent in base Fedora - glibc-devel is closest +|`+mingw32-filesystem+` / `+mingw64-filesystem+` / `+ucrt64-filesystem+` |Core filesystem directory layout, and RPM macros for spec files. Equivalent to 'filesystem' RPM +|`+mingw32-binutils+` / `+mingw64-binutils+` / `+ucrt64-binutils+` |Cross-compiled binutils (utilities like 'strip', 'as', 'ld') which understand Windows executables and DLLs. Equivalent to 'binutils' RPM +|`+mingw32-gcc+` / `+mingw64-gcc+` / `+ucrt64-gcc+` |GNU compiler collection. Compilers for C and C++ which cross-compile to a Windows target. Equivalent to gcc RPM +|`+mingw32-crt+` / `+mingw64-crt+` / `+ucrt64-crt+` |Base libraries for core MinGW runtime & development environment. Equivalent to 'glibc' RPM +|`+mingw32-headers+` / `+mingw64-headers+` / `+ucrt64-headers+` |Win32 and Win64 API. A free (public domain) reimplementation of the header files required to link to the Win32 and Win64 API. No direct equivalent in base Fedora - glibc-devel is closest |================================================================================================================================================================================================================================= == Build for multiple targets -The goal of the MinGW framework is to provide an easy way for package maintainers to build their packages for multiple targets using one .spec file. To aid developers in this several RPM macros have been developed which are part of the mingw-filesystem package. -These RPM macros will be explained later on in these guidelines. +The goal of the MinGW framework is to provide an easy way for package +maintainers to build their packages for multiple targets using one .spec file. +To aid developers in this several RPM macros have been developed which are part +of the mingw-filesystem package. These RPM macros will be explained later on in +these guidelines. -By default a MinGW package will be built for both the Win32 and Win64 targets. +By default a MinGW package will be built for both the Win32 and Win64 targets +with the MSVCRT runtime. Building of the Win64 target with the UCRT64 runtime +is not yet enabled by default. -When a package can only be built for either one of these targets this can be indicated by setting one of these: +When a package can only be built for a subset of these targets this can be +indicated by setting one or more of these: [cols=",",] |=============================================================== -|`+%global mingw_build_win32 0+` |Don't build for the Win32 target -|`+%global mingw_build_win64 0+` |Don't build for the Win64 target +|`+%global mingw_build_win32 0+` |Don't build for the Win32 target with the MSVCRT runtime +|`+%global mingw_build_win64 0+` |Don't build for the Win64 target with the MSVCRT runtime +|`+%global mingw_build_ucrt64 0+` |Don't build for the Win64 target with the UCRT runtime |=============================================================== == One source RPM, separate binary RPMs per-target -Each cross compiled MinGW package which builds binaries for a specific target should put the binaries for that target in a separate subpackage. So if a package `+foo+` builds binaries for the Win32 and Win64 targets, then the source RPM should provide two subpackages named `+mingw32-foo+` and `+mingw64-foo+`. +Each cross compiled MinGW package which builds binaries for a specific target +should put the binaries for that target in a separate subpackage. So if a +package `+foo+` builds binaries for the Win32 and Win64 targets with the MSVCRT +runtime, then the source RPM should provide two subpackages named `+mingw32-foo+` +and `+mingw64-foo+`. If a package builds for the UCRT runtime, it will also +have a `+ucrt64-foo+` subpackage. -This means that a spec file must contains %package and %files sections for all the targets. +This means that a spec file must contains %package and %files sections for all +the targets. -If a package contains translations then all calls to the `+%find_lang+` must be replaced by `+%mingw_find_lang+`. -This causes all translation filelists to be split in per-target filelists. -For example: when a spec file contains something like this: +If a package contains translations then all calls to the `+%find_lang+` must be +replaced by `+%mingw_find_lang+`. This causes all translation filelists to be +split in per-target filelists. For example: when a spec file contains something +like this: .... %install @@ -72,84 +111,103 @@ For example: when a spec file contains something like this: %mingw_find_lang foo .... -then two files will get created named `+mingw32-foo.lang+` and `+mingw64-foo.lang+`. -These file lists can be included in the %files section for the targets: +then one file per mingw target will get created named `+mingw32-foo.lang+`, +`+mingw64-foo.lang+`, and `+ucrt64-foo.lang+`. These file lists can be +included in the %files section for the targets: .... %files -n mingw32-foo -f mingw32-foo.lang %files -n mingw64-foo -f mingw64-foo.lang + + %files -n ucrt64-foo -f ucrt64-foo.lang .... == Filesystem layout -`+[root]+` + -`+  |+` + -`+  +- etc+` + -`+  |   |+` + -`+  |   +- rpm+` + -`+  |       |+` + -`+  |       +- macros.mingw+` + -`+  |       +- macros.mingw32+` + -`+  |       +- macros.mingw64+` + -`+  |+` + -`+  +- usr+` + -`+      |+` + -`+      +- bin   - Links to MinGW cross compiler toolchain+` + -`+      |   |+` + -`+      |   +- i686-w64-mingw32-cpp+` + -`+      |   +- i686-w64-mingw32-gcc+` + -`+      |   +- i686-w64-mingw32-g+++` + -`+      |   +- x86_64-w64-mingw32-cpp+` + -`+      |   +- x86_64-w64-mingw32-gcc+` + -`+      |   +- x86_64-w64-mingw32-g+++` + -`+      |   +- ... etc..+` + -`+      |+` + -`+      +- lib+` + -`+      |   |+` + -`+      |   +- rpm+` + -`+      |       |+` + -`+      |       +- mingw-find-debuginfo.sh - extract debug information from Win32 and Win64 binaries+` + -`+      |       +- mingw-find-lang.sh - generates per-target file lists containing translations+` + -`+      |       +- mingw-find-provides.sh - extra DLL names+` + -`+      |       +- mingw-find-requires.sh - discover required DLL names+` + -`+      |+` + -`+      +- i686-w64-mingw32  - root of mingw toolchain and binaries for the Win32 target - see next diagram+` + -`+      +- x86_64-w64-mingw32  - root of mingw toolchain and binaries for the Win64 target - see next diagram+` - -`+/usr/i686-w64-mingw32+` + -`+/usr/x86_64-w64-mingw32+` + -`+  |+` + -`+  +- bin  - Binutils toolchain binaries for the target+` + -`+  |   |+` + -`+  |   +- ar+` + -`+  |   +- as+` + -`+  |   +- dlltool+` + -`+  |   +- ld+` + -`+  |   +- ... etc ...+` + -`+  |+` + -`+  +- lib  - Binutils toolchain support libraries / files for the target+` + -`+  |+` + -`+  +- sys-root  - root for cross compiled MinGW binaries+` + -`+      |+` + -`+      +- mingw+` + -`+          |+` + -`+          +- bin     - cross-compiled MinGW binaries & runtime DLL parts+` + -`+          +- etc     - configuration files+` + -`+          +- include - include files for cross compiled MinGW libs+` + -`+          +- lib     - cross-compiled static MinGW libraries & linktime DLL parts+` + -`+          |   |+` + -`+          |   +- pkgconfig  - pkg-config definitions for libraries+` + -`+          |+` + -`+          +- share+` + -`+              |+` + -`+              +- man+` +Integration into the main root filesystem layout is as follows: + +.... +[root] + | + +- etc + | | + | +- rpm + | | + | +- macros.mingw + | +- macros.mingw32 + | +- macros.mingw64 + | + +- usr + | + +- bin - Links to MinGW cross compiler toolchain + | | + | +- i686-w64-mingw32-cpp + | +- i686-w64-mingw32-gcc + | +- i686-w64-mingw32-g++ + | +- x86_64-w64-mingw32-cpp + | +- x86_64-w64-mingw32-gcc + | +- x86_64-w64-mingw32-g++ + | +- x86_64-w64-mingw32ucrt-cpp + | +- x86_64-w64-mingw32ucrt-gcc + | +- x86_64-w64-mingw32ucrt-g++ + | +- ... etc.. + | + +- lib + | | + | +- rpm + | | + | +- mingw-find-debuginfo.sh - extract debug information from Win32 and Win64 binaries + | +- mingw-find-lang.sh - generates per-target file lists containing translations + | +- mingw-find-provides.sh - extra DLL names + | +- mingw-find-requires.sh - discover required DLL names + | + +- i686-w64-mingw32 - root of mingw toolchain and binaries for the Win32 target with MSVCRT runtime - see next diagram + +- x86_64-w64-mingw32 - root of mingw toolchain and binaries for the Win64 target with MSVCRT runtime - see next diagram+` + +- x86_64-w64-mingw32urt - root of mingw toolchain and binaries for the Win64 target with UCRT runtime - see next diagram+` +.... + +The bulk of the packaged content is located under the respective MinGW root, +one of `+/usr/i686-w64-mingw32+`, `+/usr/x86_64-w64-mingw32+` and +`+/usr/x86_64-w64-mingw32ucrt+`: + +.... +[mingw-root] + | + +- bin - Binutils toolchain binaries for the target + | | + | +- ar + | +- as + | +- dlltool + | +- ld + | +- ... etc ... + | + +- lib - Binutils toolchain support libraries / files for the target + | + +- sys-root - root for cross compiled MinGW binaries + | + +- mingw + | + +- bin - cross-compiled MinGW binaries & runtime DLL parts + +- etc - configuration files + +- include - include files for cross compiled MinGW libs + +- lib - cross-compiled static MinGW libraries & linktime DLL parts + | | + | +- pkgconfig - pkg-config definitions for libraries + | + +- share + | + +- man +.... == Filenames of the cross-compilers and binutils -The MinGW cross-compilers and binutils are Fedora binaries and are therefore placed in `+%{_bindir}+` (i.e., `+/usr/bin+`) according to the FHS and Fedora guidelines. +The MinGW cross-compilers and binutils are Fedora binaries and are therefore +placed in `+%{_bindir}+` (i.e., `+/usr/bin+`) according to the FHS and Fedora +guidelines. -The MinGW cross-compilers and binutils which generate i686 binaries for Windows are named: +The MinGW cross-compilers and binutils which generate i686 binaries for Windows +with the MSVCRT runtime are named: .... %{_bindir}/i686-w64-mingw32-gcc @@ -173,28 +231,43 @@ name, i.e., etc. .... -The same also applies for the x86_64 target. This target uses 'x86_64-w64-mingw32' as prefix instead of 'i686-w64-mingw32' +The same also applies for the x86_64 target with both MSVCRT +and UCRT runtimes. The target with MSVCRT uses 'x86_64-w64-mingw32' +as prefix instead of 'i686-w64-mingw32', while UCRT uses +'x86_64-w64-mingw32ucrt'. == Naming of the root filesystem -The root filesystem contains Windows executables and DLLs and any other Windows-only files. It is necessary both because we need to store Windows libraries in order to link further libraries which depend on them, and also because MinGW requires a root filesystem location. +The root filesystem contains Windows executables and DLLs and any other +Windows-only files. It is necessary both because we need to store Windows +libraries in order to link further libraries which depend on them, and also +because MinGW requires a root filesystem location. -The location for Win32 target is provided by the macro: +The location for Win32 target with MSVCRT runtime is provided by the macro: .... %{mingw32_sysroot} %{_prefix}/i686-w64-mingw32/sys-root .... -And the Win64 target is provided by the macro: +The Win64 target with MSVCRT runtime is provided by the macro: .... %{mingw64_sysroot} %{_prefix}/x86_64-w64-mingw32/sys-root .... +The Win64 target with UCRT runtime is provided by the macro: + +.... + %{ucrt64_sysroot} %{_prefix}/x86_64-w64-mingw32ucrt/sys-root +.... + + + == Standard mingw RPM macros -The `+mingw-filesystem+` package provides a number of convenience macros for the cross compiled sysroot directories, and -toolchain. It is mandatory to use these macros in all MinGW cross compiled packages submitted to Fedora. +The `+mingw-filesystem+` package provides a number of convenience macros for +the cross compiled sysroot directories, and toolchain. It is mandatory to use +these macros in all MinGW cross compiled packages submitted to Fedora. === Toolchain macros @@ -204,8 +277,7 @@ Generic macros: [cols=",,",] |================================================================================================================================================== -|Macro |Available in + -mingw-filesystem |Explanation +|Macro |Available in mingw-filesystem |Explanation |mingw_cmake |>= 95 |Call the 'cmake' binary for all the configured targets |mingw_cmake_kde4 |>= 95 |Call the 'cmake' binary for all the configured targets with KDE4 specific parameters set |mingw_configure |>= 95 |Call the configure command for all the configured targets @@ -221,12 +293,11 @@ mingw-filesystem |Explanation |mingw_strip |>= 95 |cross compiler 'strip' binary (which supports both Win32 and Win64 binaries) |================================================================================================================================================== -Win32 specific macros: +Win32 with MSVCRT runtime specific macros: [cols=",,,",] |=================================================================================================================================================== -|Macro |Available in + -mingw32-filesystem | Value |Explanation +|Macro |Available in mingw32-filesystem | Value |Explanation |mingw32_ar |>= 95 |i686-w64-mingw32-ar |cross compiler 'ar' binary |mingw32_cc |>= 95 |i686-w64-mingw32-gcc |cross compiler 'gcc' binary |mingw32_cflags |>= 95 |-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions --param=ssp-buffer-size=4 |Default compiler flags for C/C++ binaries @@ -247,12 +318,11 @@ mingw32-filesystem | Value |Explanation |mingw32_target |>= 95 |i686-w64-mingw32 |Target platform for build |=================================================================================================================================================== -Win64 specific macros: +Win64 with MSVCRT runtime specific macros: [cols=",,,",] |=================================================================================================================================================== -|Macro |Available in + -mingw64-filesystem | Value |Explanation +|Macro |Available in mingw64-filesystem | Value |Explanation |mingw64_ar |>= 95 |x86_64-w64-mingw32-ar |cross compiler 'ar' binary |mingw64_cc |>= 95 |x86_64-w64-mingw32-gcc |cross compiler 'gcc' binary |mingw64_cflags |>= 95 |-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions --param=ssp-buffer-size=4 |Default compiler flags for C/C++ binaries @@ -273,11 +343,37 @@ mingw64-filesystem | Value |Explanation |mingw64_target |>= 95 |x86_64-w64-mingw32 |Target platform for build |=================================================================================================================================================== +Win64 with UCRT runtime specific macros: + +[cols=",,,",] +|=================================================================================================================================================== +|Macro |Available in ucrt64-filesystem | Value |Explanation +|ucrt64_ar |>= 133 |x86_64-w64-mingw32ucrt-ar |cross compiler 'ar' binary +|ucrt64_cc |>= 133 |x86_64-w64-mingw32ucrt-gcc |cross compiler 'gcc' binary +|ucrt64_cflags |>= 133 |-O2 -g -pipe -Wall -Wp,-D_FORTIFY_SOURCE=2 -fexceptions --param=ssp-buffer-size=4 |Default compiler flags for C/C++ binaries +|ucrt64_cmake |>= 133 | |Call the 'cmake' binary for the Win64 target +|ucrt64_configure |>= 133 | |standard invocation for autotools 'configure' scripts +|ucrt64_cpp |>= 133 |x86_64-w64-mingw32ucrt-gcc -E |cross compiler 'cpp' binary +|ucrt64_env |>= 133 | |Set the correct environment variables for the Win64 target +|ucrt64_host |>= 133 |x86_64-w64-mingw32 |Host platform for build +|ucrt64_meson |>= 104 | |Call the meson binary for the Win64 target +|ucrt64_ninja |>= 104 | |Call the ninja binary for the Win64 target +|ucrt64_objcopy |>= 133 |x86_64-w64-mingw32ucrt-objcopy |cross compiler 'objcopy' binary +|ucrt64_objdump |>= 133 |x86_64-w64-mingw32ucrt-objdump |cross compiler 'objdump' binary +|ucrt64_pkg_config |>= 133 |x86_64-w64-mingw32ucrt-pkg-config |Call the pkg-config command for the Win64 target +|ucrt64_qmake_qt4 |>= 133 |ucrt64-qmake-qt4 |Call the Qt4 qmake command for the Win64 target +|ucrt64_qmake_qt5 |>= 133 |ucrt64-qmake-qt5 |Call the Qt5 qmake command for the Win64 target +|ucrt64_ranlib |>= 133 |x86_64-w64-mingw32ucrt-ranlib |cross compiler 'ranlib' binary +|ucrt64_strip |>= 133 |x86_64-w64-mingw32ucrt-strip |cross compiler 'strip' binary +|ucrt64_target |>= 133 |x86_64-w64-mingw32 |Target platform for build +|=================================================================================================================================================== + === Filesystem location macros -The following macros are for use in %build, %install and %files sections of the RPM spec +The following macros are for use in %build, %install and %files sections of the +RPM spec -For the Win32 target: +For the Win32 with MSVCRT runtime target: [cols=",,",] |=================================================================================================== @@ -295,7 +391,7 @@ For the Win32 target: |mingw32_sysroot |%\{_prefix}/i686-w64-mingw32/sys-root |Windows system root. |=================================================================================================== -For the Win64 target: +For the Win64 with MSVCRT runtime target: [cols=",,",] |=================================================================================================== @@ -313,21 +409,46 @@ For the Win64 target: |mingw64_sysroot |%\{_prefix}/x86_64-w64-mingw32/sys-root |Windows system root. |=================================================================================================== -== Compilation of binaries +For the Win64 with UCRT runtime target: -In order to build binaries for multiple targets we have to call commands like `+./configure+` and `+make+` multiple times (once for each target). -If one has to write this all out in a spec file then it will lead to duplicate code. -To reduce the amount of duplication, several RPM macros have been introduced to help with the compilation. -These macros are `+%mingw_configure+`, `+%mingw_cmake+`, `+%mingw_cmake_kde4+`, `+%mingw_qmake_qt4+`, `+%mingw_qmake_qt5+` and `+%mingw_make+` +[cols=",,",] +|=================================================================================================== +|ucrt64_bindir |%\{ucrt64_prefix}/bin |Location of Windows executables. +|ucrt64_datadir |%\{ucrt64_prefix}/share |Shared data used under Windows. +|ucrt64_docdir |%\{ucrt64_prefix}/share/doc |Documentation. +|ucrt64_infodir |%\{ucrt64_prefix}/share/info |Info files (see note below). +|ucrt64_includedir |%\{ucrt64_prefix}/include |Header files used when cross-compiling for Windows. +|ucrt64_libdir |%\{ucrt64_prefix}/lib |Windows libraries (see sections below). +|ucrt64_libexecdir |%\{ucrt64_prefix}/libexec | +|ucrt64_mandir |%\{ucrt64_prefix}/share/man |Man pages (see note below). +|ucrt64_prefix |%\{ucrt64_sysroot}/mingw |Windows equivalent of %\{_prefix}, required by MinGW. +|ucrt64_sbindir |%\{ucrt64_prefix}/sbin | +|ucrt64_sysconfdir |%\{ucrt64_prefix}/etc |Configuration files used when running under Windows. +|ucrt64_sysroot |%\{_prefix}/x86_64-w64-mingw32ucrt/sys-root |Windows system root. +|=================================================================================================== -These macros use out of source compilation to build binaries for all the targets. -Almost all packages support out of source compilation or require slight patching. The only known exceptions to date are zlib and openssl. -Packages which don't support out of source compilation may require a different approach like performing everything in the %install phase. -If you happen to stumble across a package which requires a different approach feel free to contact us on the Fedora MinGW mailing list +== Compilation of binaries -Some packages need to be built multiple times for each target. Examples of this are packages which have to be built once for a static version and once for a shared version. -Such packages can add a custom suffix to the build directory used. -Say you've got something like below: +In order to build binaries for multiple targets we have to call commands like +`+./configure+` and `+make+` multiple times (once for each target). If one has +to write this all out in a spec file then it will lead to duplicate code. To +reduce the amount of duplication, several RPM macros have been introduced to +help with the compilation. These macros are `+%mingw_configure+`, +`+%mingw_cmake+`, `+%mingw_cmake_kde4+`, `+%mingw_qmake_qt4+`, +`+%mingw_qmake_qt5+` and `+%mingw_make+` + +These macros use out of source compilation to build binaries for all the +targets. Almost all packages support out of source compilation or require +slight patching. The only known exceptions to date are zlib and openssl. +Packages which don't support out of source compilation may require a different +approach like performing everything in the %install phase. If you happen to +stumble across a package which requires a different approach feel free to +contact us on the Fedora MinGW mailing list + +Some packages need to be built multiple times for each target. Examples of this +are packages which have to be built once for a static version and once for a +shared version. Such packages can add a custom suffix to the build directory +used. Say you've got something like below: .... mkdir build_shared @@ -348,42 +469,57 @@ This can be rewritten to something like this: .... Most packages used the command `+make %{?_smp_mflags}+` to build the package. -In the MinGW cross compiler framework you have to use `+%mingw_make %{?_smp_mflags}+` to build the package for all configured targets. -As with the `+%mingw_configure+` macro you can also use the MINGW_BUILDDIR_SUFFIX environment variable to indicate a custom suffix to the build directory used - -To install the package the command `+make install DESTDIR=$RPM_BUILD_ROOT+` was used in almost all cases. -This can be rewritten to `+%mingw_make install DESTDIR=$RPM_BUILD_ROOT+` to install the package for all configured targets -The environment variable MINGW_BUILDDIR_SUFFIX can also be used here - -Some packages require some custom instructions before the files are ready to be packaged. Such code can remain as is. However, you may need to duplicate these instructions multiple times (for all configured targets). +In the MinGW cross compiler framework you have to use +`+%mingw_make %{?_smp_mflags}+` to build the package for all configured targets. +As with the `+%mingw_configure+` macro you can also use the +MINGW_BUILDDIR_SUFFIX environment variable to indicate a custom suffix to the +build directory used + +To install the package the command `+make install DESTDIR=$RPM_BUILD_ROOT+` was +used in almost all cases. This can be rewritten to +`+%mingw_make install DESTDIR=$RPM_BUILD_ROOT+` to install the package for all +configured targets. The environment variable MINGW_BUILDDIR_SUFFIX can also be +used here. + +Some packages require some custom instructions before the files are ready to be +packaged. Such code can remain as is. However, you may need to duplicate these +instructions multiple times (for all configured targets). == Dependencies -If a package contains binaries which depend on a DLL provided by another package, these dependencies should be expressed in the form: +If a package contains binaries which depend on a DLL provided by another +package, these dependencies should be expressed in the form: .... mingw32(foo.dll) .... -where `+foo.dll+` is the name of the DLL. The name must be converted to lowercase because Windows binaries contain case -insensitive dependencies. The form 'mingw32(foo.dll)' should be used for Win32 binaries and the form 'mingw64(foo.dll)' for Win64 binaries. +where `+foo.dll+` is the name of the DLL. The name must be converted to +lowercase because Windows binaries contain case insensitive dependencies. The +form 'mingw32(foo.dll)' should be used for Win32 binaries and the form +'mingw64(foo.dll)' for Win64 binaries. -Correct dependency generation is done automatically. Packagers should start their spec files with this line: +Correct dependency generation is done automatically. Packagers should start +their spec files with this line: .... %{?mingw_package_header} .... -All binary packages should depend on `+mingw32-filesystem+` or `+mingw64-filesystem+` (depending on the files in the package). If the line mentioned above is used then it will be added automatically, so you don't have to add it yourself +All binary packages should depend on `+mingw32-filesystem+` or +`+mingw64-filesystem+` (depending on the files in the package). -All specfiles should BuildRequire at least one of these (depending on the targets for which you want to build): +All specfiles should BuildRequire at least one of these (depending on the +targets for which you want to build): -`+BuildRequires:  mingw32-filesystem >= minimum-version+` + -`+BuildRequires:  mingw64-filesystem >= minimum-version+` +`+BuildRequires:  mingw32-filesystem+` + +`+BuildRequires:  mingw64-filesystem+` and any other BuildRequires that they need. -The `+minimum-version+` must be at least 95 or any later version which provides the functionality you need +Most mingw RPM macros can be assumed to exist in all non-EOL Fedora releases. +If the package does, however, rely on a newly introduced macro, a versioned +dependancy on the `+mingw-XX-filesystem+` packages should be used. == Build architecture @@ -397,26 +533,34 @@ unless they contain Fedora native executables. All libraries must be built as DLLs. -Because of the peculiarity of Windows, DLLs are stored in the `+%{mingw32_bindir}+` directory, along with a control file in -the `+%{mingw32_libdir}+` directory. For example, for a library called `+foo+` there would be: +Because of the peculiarity of Windows, DLLs are stored in the +`+%{mingw32_bindir}+` directory, along with a control file in the +`+%{mingw32_libdir}+` directory. For example, for a library called `+foo+` +there would be: .... %{mingw32_bindir}/foo.dll %{mingw32_libdir}/foo.dll.a .... -The `+foo.dll+` file is the main library, `+foo.dll.a+` is a stub linked to applications so they can find the library at runtime. All of these files are required in those locations in order to link successfully. The `+.dll+` may contain a version number although not always (e.g., `+foo-0.dll+`). +The `+foo.dll+` file is the main library, `+foo.dll.a+` is a stub linked to +applications so they can find the library at runtime. All of these files are +required in those locations in order to link successfully. The `+.dll+` may +contain a version number although not always (e.g., `+foo-0.dll+`). === Do not use %\{mingw32_bindir}/* or %\{mingw32_libdir}/* in %files section -The `+%files+` section must list DLLs and import libraries separately. Packages must NOT use `+%{mingw32_bindir}/*+` or -`+%{mingw32_libdir}/*+` +The `+%files+` section must list DLLs and import libraries separately. Packages +must NOT use `+%{mingw32_bindir}/*+` or `+%{mingw32_libdir}/*+` -The reason for this is that libtool is very fragile and will give up on building a DLL very easily. Therefore we force the name of the DLL to be listed explicitly in the `+%files+` section in order to catch this during RPM builds. +The reason for this is that libtool is very fragile and will give up on building +a DLL very easily. Therefore we force the name of the DLL to be listed +explicitly in the `+%files+` section in order to catch this during RPM builds. === Stripping -Libraries and executables should be stripped. This is done correctly and automatically if the spec file starts with this line: +Libraries and executables should be stripped. This is done correctly and +automatically if the spec file starts with this line: .... %{?mingw_package_header} @@ -424,7 +568,9 @@ Libraries and executables should be stripped. This is done correctly and automat === Debuginfo subpackage -Most binaries contain debugging symbols when the package gets built. To split the debugging symbols to a separate debuginfo package (as is done with native Fedora packages) the spec file must include these lines: +Most binaries contain debugging symbols when the package gets built. To split +the debugging symbols to a separate debuginfo package (as is done with native +Fedora packages) the spec file must include these lines: .... %{?mingw_package_header} @@ -432,55 +578,80 @@ Most binaries contain debugging symbols when the package gets built. To split th %{?mingw_debug_package} .... -The `+%{?mingw_debug_package}+` line must be placed after the `+%description tag+`. Otherwise spectool and other RPM tools may fail to function +The `+%{?mingw_debug_package}+` line must be placed after the +`+%description tag+`. Otherwise spectool and other RPM tools may fail to +function. + +== File listing + +The MinGW packages are intended to allow developers to compile and test the +Windows support of their applications. It is furthermore expected that +developers will build Windows installers (MSIs) for their applications using +the MinGW package content. + +Thus the Fedora MinGW package file listing must include content needed to +satisfy either build/test usage or the creation of Windows installers. + +=== Executables (EXEs) -== Executables (EXEs) +Most libraries also provide executables. These can include executables which +can be used to test or showcase the library in question (for example +gtk3-demo.exe in mingw-gtk3). Other examples are helper executables which are +used by the library itself internally (for example gspawn-win32-helper.exe in +mingw-glib2). -Most libraries also provide executables. These can include executables which can be used to test or showcase the library in question (for example gtk3-demo.exe in mingw-gtk3). -Other examples are helper executables which are used by the library itself internally (for example gspawn-win32-helper.exe in mingw-glib2). +Executables which are required for proper functionality of the libraries must be +packaged in the matching mingw32/mingw64 subpackage. Other optional executables +targetted at end users should be packaged (for example certtool.exe in GNUTLS). +Executables targetted at developers are discouraged, but may be packaged in +optional (dependent) subpackages at a packager's discretion. -Executables which are required for proper functionality of the libraries must be packaged in the matching mingw32/mingw64 subpackage. All other executables are discouraged, but may be packaged in optional (dependent) subpackages at a packager's discretion. +=== Files which are already part of native packages -== Files which are already part of native packages +There are various types of files which are simply duplicates of equivalent files +found in Fedora native packages. These files should not be packaged in the MinGW +package. The following files don't need to be packaged in the MinGW package when +their native counterpart already contains them: -There are various types of files which are simply duplicates of equivalent files found in Fedora native packages. These files should not be packaged in the MinGW package. -The following files don't need to be packaged in the MinGW package when their native counterpart already contains them: +* Man pages (`+%{mingw32_mandir}+` / `+%{mingw64_mandir}+` / `+%{ucrt64_mandir}+`) +* Info files (`+%{mingw32_infodir}+` / `+%{mingw64_infodir}+` / `+%{ucrt64_infodir}+`) +* Generic documentation (`+%{mingw32_docdir}+` / `+%{mingw64_docdir}+` / `+%{ucrt64_docdir}+`) +* Autoconf files (`+%{mingw32_datadir}/aclocal+` / `+%{mingw64_datadir}/aclocal+` / `+%{ucrt64_datadir}/aclocal+`) +* gtk-doc files (`+%{mingw32_datadir}/gtk-doc+` / `+%{mingw64_datadir}/gtk-doc+` / `+%{ucrt64_datadir}/gtk-doc+`) -* Man pages (`+%{mingw32_mandir}+` / `+%{mingw64_mandir}+`) -* Info files (`+%{mingw32_infodir}+` / `+%{mingw64_infodir}+`) -* Generic documentation (`+%{mingw32_docdir}+` / `+%{mingw64_docdir}+`) -* Autoconf files (`+%{mingw32_datadir}/aclocal+` / `+%{mingw64_datadir}/aclocal+`) -* gtk-doc files (`+%{mingw32_datadir}/gtk-doc+` / `+%{mingw64_datadir}/gtk-doc+`) +Note, generic Documentation aimed at end users, as opposed to developers, +should be included where it is likely that application developers will want +to bundle it with their Windows installers. == Example Specfile .... %{?mingw_package_header} -Name: mingw-example -Version: 1.0.0 -Release: 1%{?dist} -Summary: MinGW compiled example library +Name: mingw-example +Version: 1.0.0 +Release: 1%{?dist} +Summary: MinGW compiled example library -License: LGPL-2.1-or-later -URL: https://fedoraproject.org -Source: https://fedoraproject.org/example-%{version}.tar.bz2 +License: LGPL-2.1-or-later +URL: https://fedoraproject.org +Source: https://fedoraproject.org/example-%{version}.tar.bz2 -BuildArch: noarch +BuildArch: noarch -BuildRequires: mingw32-filesystem >= 113 -BuildRequires: mingw32-gcc -BuildRequires: mingw32-binutils -BuildRequires: mingw32-gettext -BuildRequires: mingw32-win-iconv -BuildRequires: mingw32-zlib +BuildRequires: mingw32-filesystem +BuildRequires: mingw32-gcc +BuildRequires: mingw32-binutils +BuildRequires: mingw32-gettext +BuildRequires: mingw32-win-iconv +BuildRequires: mingw32-zlib -BuildRequires: mingw64-filesystem >= 113 -BuildRequires: mingw64-gcc -BuildRequires: mingw64-binutils -BuildRequires: mingw64-gettext -BuildRequires: mingw64-win-iconv -BuildRequires: mingw64-zlib +BuildRequires: mingw64-filesystem +BuildRequires: mingw64-gcc +BuildRequires: mingw64-binutils +BuildRequires: mingw64-gettext +BuildRequires: mingw64-win-iconv +BuildRequires: mingw64-zlib %description @@ -493,28 +664,28 @@ MinGW compiled example library. # Win32 %package -n mingw32-example -Summary: MinGW compiled example library for the Win32 target +Summary: MinGW compiled example library for the Win32 target %description -n mingw32-example MinGW compiled example library for the Win32 target. %package -n mingw32-example-static -Summary: Static version of the MinGW Win32 compiled example library -Requires: mingw32-example = %{version}-%{release} +Summary: Static version of the MinGW Win32 compiled example library +Requires: mingw32-example = %{version}-%{release} %description -n mingw32-example-static Static version of the MinGW Win32 compiled example library. # Win64 %package -n mingw64-example -Summary: MinGW compiled example library for the Win64 target +Summary: MinGW compiled example library for the Win64 target %description -n mingw64-example MinGW compiled example library for the Win64 target. %package -n mingw64-example-static -Summary: Static version of the MinGW Win64 compiled example library -Requires: mingw64-example = %{version}-%{release} +Summary: Static version of the MinGW Win64 compiled example library +Requires: mingw64-example = %{version}-%{release} %description -n mingw64-example-static Static version of the MinGW Win64 compiled example library. From 44fa4d4faaf8e94a5714eb5de7c399eb9ac22243 Mon Sep 17 00:00:00 2001 From: Benson Muite Date: Feb 23 2023 17:23:47 +0000 Subject: [PATCH 39/232] Add sourcehut Instructions for using commits from git on Sourcehut --- diff --git a/guidelines/modules/ROOT/pages/SourceURL.adoc b/guidelines/modules/ROOT/pages/SourceURL.adoc index ef3dd83..2a87dd4 100644 --- a/guidelines/modules/ROOT/pages/SourceURL.adoc +++ b/guidelines/modules/ROOT/pages/SourceURL.adoc @@ -192,6 +192,7 @@ Once the commit hash and git tag are known, you can define them in your spec fil %global shortcommit %(c=%{commit}; echo ${c:0:7}) [GitHub] %global shortcommit %(c=%{commit}; echo ${c:0:11}) [Bitbucket] %global shortcommit %(c=%{commit}; echo ${c:0:7}) [GitLab] +%global shortcommit %(c=%{commit}; echo ${c:0:8}) [Sourcehut] .... === Commit Revision @@ -202,12 +203,14 @@ For the source tarball, you can use the following syntax: Source: https://github.com/OWNER/PROJECT/archive/%{commit}/%{name}-%{shortcommit}.tar.gz [GitHub] Source: https://bitbucket.org/OWNER/PROJECT/get/%{commit}.tar.gz#/%{name}-%{shortcommit}.tar.gz [BitBucket] Source: https://gitlab.com/OWNER/PROJECT/-/archive/%{commit}/%{name}-%{shortcommit}.tar.gz [GitLab] +Source: https://sr.ht/~OWNER/PROJECT/archive/%{shortcommit}.tar.gz [Sourcehut] ... %prep %autosetup -n PROJECT-%{commit} [GitHub] %autosetup -n OWNER-PROJECT-%{shortcommit} [BitBucket] %autosetup -n PROJECT-%{commit} [GitLab] +%autosetup -n PROJECT-%{shortcommit} [Sourcehut] .... If the release corresponds to a git tag with a sane numeric version, @@ -239,12 +242,14 @@ For the source tarball, you can use the following syntax: Source: https://github.com/OWNER/PROJECT/archive/%{gittag}/%{name}-%{version}.tar.gz [GitHub] Source: https://bitbucket.org/OWNER/PROJECT/get/%{gittag}.tar.gz#/%{name}-%{version}.tar.gz [BitBucket] Source: https://gitlab.com/OWNER/PROJECT/-/archive/%{gittag}/%{name}-%{version}.tar.gz [GitLab] +Source: https://sr.ht/~OWNER/PROJECT/archive/%{version}.tar.gz [Sourcehut] ... %prep %autosetup -n PROJECT-%{gittag} [GitHub] %autosetup -n OWNER-PROJECT-%{shortcommit} [BitBucket] %autosetup -n PROJECT-%{version} [GitLab] +%autosetup -n PROJECT-%{version} [Sourcehut] .... == Using %\{version} From 2e47427af75846d830d120944db178c7f15768db Mon Sep 17 00:00:00 2001 From: Sérgio M. Basto Date: Feb 23 2023 18:18:32 +0000 Subject: [PATCH 40/232] Update guidelines/modules/ROOT/pages/Golang.adoc like https://pagure.io/packaging-committee/blob/master/f/guidelines/modules/ROOT/pages/Rust.adoc advertise go2rpm before starting --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index bf4b870..bf32dd8 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -4,6 +4,8 @@ This document details best practices for packaging Golang packages. Most of it is automated by an extensive use of macros. +== go2rpm + https://pagure.io/GoSIG/go2rpm/[go2rpm] is tool that automates many of these steps. It is advisable to try `+go2rpm import_path+` first before attempting to write a SPEC by hand. From 0c4dfc34f16b67d8faa7a4538d61902971142d1a Mon Sep 17 00:00:00 2001 From: Benson Muite Date: Mar 01 2023 16:12:27 +0000 Subject: [PATCH 41/232] Update sourcehut url to include git --- diff --git a/guidelines/modules/ROOT/pages/SourceURL.adoc b/guidelines/modules/ROOT/pages/SourceURL.adoc index 2a87dd4..c3d3987 100644 --- a/guidelines/modules/ROOT/pages/SourceURL.adoc +++ b/guidelines/modules/ROOT/pages/SourceURL.adoc @@ -200,10 +200,10 @@ Once the commit hash and git tag are known, you can define them in your spec fil For the source tarball, you can use the following syntax: .... -Source: https://github.com/OWNER/PROJECT/archive/%{commit}/%{name}-%{shortcommit}.tar.gz [GitHub] -Source: https://bitbucket.org/OWNER/PROJECT/get/%{commit}.tar.gz#/%{name}-%{shortcommit}.tar.gz [BitBucket] -Source: https://gitlab.com/OWNER/PROJECT/-/archive/%{commit}/%{name}-%{shortcommit}.tar.gz [GitLab] -Source: https://sr.ht/~OWNER/PROJECT/archive/%{shortcommit}.tar.gz [Sourcehut] +Source: https://github.com/OWNER/PROJECT/archive/%{commit}/%{name}-%{shortcommit}.tar.gz [GitHub] +Source: https://bitbucket.org/OWNER/PROJECT/get/%{commit}.tar.gz#/%{name}-%{shortcommit}.tar.gz [BitBucket] +Source: https://gitlab.com/OWNER/PROJECT/-/archive/%{commit}/%{name}-%{shortcommit}.tar.gz [GitLab] +Source: https://git.sr.ht/~OWNER/PROJECT/archive/%{shortcommit}.tar.gz#/PROJECT-%{version}.tar.gz [Sourcehut] ... %prep @@ -242,7 +242,7 @@ For the source tarball, you can use the following syntax: Source: https://github.com/OWNER/PROJECT/archive/%{gittag}/%{name}-%{version}.tar.gz [GitHub] Source: https://bitbucket.org/OWNER/PROJECT/get/%{gittag}.tar.gz#/%{name}-%{version}.tar.gz [BitBucket] Source: https://gitlab.com/OWNER/PROJECT/-/archive/%{gittag}/%{name}-%{version}.tar.gz [GitLab] -Source: https://sr.ht/~OWNER/PROJECT/archive/%{version}.tar.gz [Sourcehut] +Source: https://git.sr.ht/~OWNER/PROJECT/archive/%{version}.tar.gz#/PROJECT-%{version}.tar.gz [Sourcehut] ... %prep From f9dbedd76cfad758a6974be63887606baaef6e8a Mon Sep 17 00:00:00 2001 From: Benson Muite Date: Mar 01 2023 16:12:27 +0000 Subject: [PATCH 42/232] Fix error in Sourcehut link --- diff --git a/guidelines/modules/ROOT/pages/SourceURL.adoc b/guidelines/modules/ROOT/pages/SourceURL.adoc index c3d3987..51bb955 100644 --- a/guidelines/modules/ROOT/pages/SourceURL.adoc +++ b/guidelines/modules/ROOT/pages/SourceURL.adoc @@ -200,10 +200,10 @@ Once the commit hash and git tag are known, you can define them in your spec fil For the source tarball, you can use the following syntax: .... -Source: https://github.com/OWNER/PROJECT/archive/%{commit}/%{name}-%{shortcommit}.tar.gz [GitHub] -Source: https://bitbucket.org/OWNER/PROJECT/get/%{commit}.tar.gz#/%{name}-%{shortcommit}.tar.gz [BitBucket] -Source: https://gitlab.com/OWNER/PROJECT/-/archive/%{commit}/%{name}-%{shortcommit}.tar.gz [GitLab] -Source: https://git.sr.ht/~OWNER/PROJECT/archive/%{shortcommit}.tar.gz#/PROJECT-%{version}.tar.gz [Sourcehut] +Source: https://github.com/OWNER/PROJECT/archive/%{commit}/%{name}-%{shortcommit}.tar.gz [GitHub] +Source: https://bitbucket.org/OWNER/PROJECT/get/%{commit}.tar.gz#/%{name}-%{shortcommit}.tar.gz [BitBucket] +Source: https://gitlab.com/OWNER/PROJECT/-/archive/%{commit}/%{name}-%{shortcommit}.tar.gz [GitLab] +Source: https://git.sr.ht/~OWNER/PROJECT/archive/%{shortcommit}.tar.gz#/PROJECT-%{shortcommit}.tar.gz [Sourcehut] ... %prep From ad5dbe67aa47c5ccdf8907791d2955031adb97e2 Mon Sep 17 00:00:00 2001 From: Zdenek Dohnal Date: Mar 01 2023 16:16:14 +0000 Subject: [PATCH 43/232] Add note to versioning examples Add note to versioning examples to prevent confusion about b being beta, which cost me a great deal, because I didn't realize the whole example is a sequence of the releases... --- diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index 6eaa069..4fc178a 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -264,7 +264,7 @@ $ rpmdev-vercmp 2~almost^post 2.0.1 | 5.2a | 5.2a | 1%{?dist} | Upstream introduced a letter to indicate a patch release. You trust upstream to use letters in alphabetical order, so it's OK to use the version as is. -| 5.2b | 5.2b | 1%{?dist} | +| 5.2b | 5.2b | 1%{?dist} | Another patch release after 5.2 - this is not a beta. | 5.2b.1 | 5.2b.1 | 1%{?dist} | Even this is OK as long as the sequence increases. From 9c71fa59737b4265821343abb5e46efd2d6733d3 Mon Sep 17 00:00:00 2001 From: Tim Landscheidt Date: Mar 12 2023 13:50:25 +0000 Subject: [PATCH 44/232] Fix escapes --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index 19158b3..43fb3bb 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -350,7 +350,7 @@ This macro simply runs `+ansible-galaxy collection build+`. This macro pulls out the collection namespace, name, and version from `+galaxy.yml+` and then uses it to run `+ansible-galaxy collection install+`. -After that, it writes out `+%{ansible_collection_filelist}` based on the +After that, it writes out `+%{ansible_collection_filelist}+` based on the metadata it previously extracted diff --git a/guidelines/modules/ROOT/pages/Perl.adoc b/guidelines/modules/ROOT/pages/Perl.adoc index e782c76..f0a4fe5 100644 --- a/guidelines/modules/ROOT/pages/Perl.adoc +++ b/guidelines/modules/ROOT/pages/Perl.adoc @@ -47,7 +47,7 @@ It is recommended to include explicit dependencies for core modules, because the === Versioned MODULE_COMPAT_ Requires or `+perl-libs+` -Packages with Perl modules installed in %{perl_vendorarch}, %{perl_vendorlib}, %{perl_privlib} or %{perl_archlib} will automatically gain dependency on `+perl-libs+` for pure Perl modules or a dependency on `+perl(:MODULE_COMPAT_)+` for libraries with compiled code. The dependency is handled by `+perl-generators+`. +Packages with Perl modules installed in %\{perl_vendorarch}, %\{perl_vendorlib}, %\{perl_privlib} or %\{perl_archlib} will automatically gain dependency on `+perl-libs+` for pure Perl modules or a dependency on `+perl(:MODULE_COMPAT_)+` for libraries with compiled code. The dependency is handled by `+perl-generators+`. Packages that require the Perl interpreter or `+libperl.so+` but do not install modules to the aforementioned directories or explicitly link to `+libperl.so.+` need to handle the dependency manually. From 157fa4605d05dcfd18f249a48dffcf1912d98213 Mon Sep 17 00:00:00 2001 From: josef radinger Date: Mar 15 2023 21:00:47 +0000 Subject: [PATCH 45/232] small typo --- diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc index 7ec93ce..945de27 100644 --- a/guidelines/modules/ROOT/pages/Python.adoc +++ b/guidelines/modules/ROOT/pages/Python.adoc @@ -617,7 +617,7 @@ or a macro should be used to get the version. Packages *SHOULD NOT* have an explicit runtime dependency on `+python3+`. Instead of depending on `+python3+`, -packges have an automatic dependency on `+python(abi) = 3.X+` +packages have an automatic dependency on `+python(abi) = 3.X+` when they install files to `+%{python3_sitelib}+` or `+%{python3_sitearch}+`, or they have an automatic dependency on `+/usr/bin/python3+` if they have executable Python scripts, From e5671d7e9838bc8b1a39b186bdde01fb2f313899 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Mar 16 2023 12:46:46 +0000 Subject: [PATCH 46/232] file and dir dependencies: mention explicit path dependencies, reorder The text is inverted, to list the allowed uses first, and then to exclude the unwanted ones. The text didn't mention the case where one package has an explicit Provides:/some/path and another package uses Requires|Recommends|Suggests:/some/path. Those explicit Provides are included in the primary metadata and can be used with no problem and they are sometimes useful to coordinate functionality between packages. Also, with dnf5 the split between "primary" and "filelists" metadata matters again, and the latter is not dowloaded by default. So reword the explanation a bit to discourage packagers from using it. The rule is extended to also cover directories. I suspect that the omission was just clumsy language and not intentional. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index dd32452..09f6e51 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -838,13 +838,16 @@ supported in RPM. RPM gives you the ability to depend on arbitrary files or directories instead of packages. -Packages SHOULD NOT include file dependencies -outside of the following directories: +Packages MAY include such dependencies for paths inside one of the following directories: * `+/usr/bin+` * `+/usr/sbin+` * `+/etc+` +They also MAY depend on paths listed in an explicit `Provides:`. +They SHOULD NOT include dependencies on other paths +as that requires additional repository metadata to be downloaded. + Please also note that it is not uncommon for multiple packages to provide the same directory. Directory dependencies SHOULD ONLY be used From 656086e874ccb7d503f4e6ff797a2b11b09a1cb1 Mon Sep 17 00:00:00 2001 From: Miro Hrončok Date: Mar 30 2023 11:27:44 +0000 Subject: [PATCH 47/232] Document %{py3_test_envvars} --- diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc index 945de27..28df2a6 100644 --- a/guidelines/modules/ROOT/pages/Python.adoc +++ b/guidelines/modules/ROOT/pages/Python.adoc @@ -1086,8 +1086,30 @@ appropriate for `+%check+`: * Locations in the buildroot are added to `+$PATH+` and `+$PYTHONPATH+`. * `+$PYTHONDONTWRITEBYTECODE+` is set to avoid writing pytest-specific cache files to buildroot +* `+$PYTEST_XDIST_AUTO_NUM_WORKERS+` is set to `+%{_smp_build_ncpus}+` * If unset, `+$CFLAGS+` and `+$LDFLAGS+` are set to match the build flags +==== Other test runners + +If upstream doesn’t use `+tox+` or `+pytest+`, +other test runners can be invoked with <> macro, +available since Fedora Linux 38. + +This macro sets several environment variables similarly to `+%pytest+`, +but requires the actual test runner to be invoked after the macro, for example: + +[source,spec] +---- +%{py3_test_envvars} %{python3} -m unittest +---- + +Or: + +[source,spec] +---- +%{py3_test_envvars} %{python3} tests/run_tests.py +---- + === Test dependencies One part of the Python packaging ecosystem that is still not standardized @@ -1563,6 +1585,14 @@ See <> for details. + The command that `+%pytest+` uses. May be redefined. +[#py3_test_envvars] +* `+%py3_test_envvars+` (`+PATH=... PYTHONPATH=... PYTHONDONTWRITEBYTECODE=1 ...+`) ++ +The environment variables used by `+%pytest+` and `+%tox+`. +It may be used to invoke custom test runners in `+%check+`. +See <> for details. +Introduced in Fedora Linux 38. + [#py3_check_import] * `+%py3_check_import+` + From ff67aa29656073443b741ffd42bf1ad305d62e1b Mon Sep 17 00:00:00 2001 From: Jerry James Date: Apr 06 2023 16:24:14 +0000 Subject: [PATCH 48/232] Update OCaml Guidelines - Modernize example spec file and discussion of its contents - Remove obsolete discussion of internal dependency generator - Add example spec files that use dune and topkg - Use modern RPM macros - Add semantic line breaks --- diff --git a/guidelines/modules/ROOT/examples/ocaml-dune-example.spec b/guidelines/modules/ROOT/examples/ocaml-dune-example.spec new file mode 100644 index 0000000..79ec39e --- /dev/null +++ b/guidelines/modules/ROOT/examples/ocaml-dune-example.spec @@ -0,0 +1,69 @@ +%undefine _package_note_flags + +%ifnarch %{ocaml_native_compiler} +%global debug_package %{nil} +%endif + +Name: ocaml-foolib +Version: 1.2.3 +Release: %autorelease +Summary: OCaml library for fooing bars + +License: LGPL-2.1-or-later +URL: https://www.example.com/foolib +Source: https://www.example.com/foolib-%{version}.tar.gz + +BuildRequires: ocaml +BuildRequires: ocaml-dune + +%description +OCaml library for fooing bars. This library can also foo bazes. + + +%package devel +Summary: Development files for %{name} +Requires: %{name}%{?_isa} = %{version}-%{release} + + +%description devel +The %{name}-devel package contains libraries and signature files for +developing applications that use %{name}. + + +%prep +%autosetup -n foolib-%{version} + + +%build +# Build all installable targets +%dune_build +# Build a specific set of targets +%dune_build -p bazzer,boffer +# Build non-default targets +%dune_build @install @doc + + +%install +# Install all installable targets +%dune_install +# Install a specific set of targets +%dune_install bazzer boffer + + +%check +# Check all installable targets +%dune_check +# Check a specific set of targets +%dune_check -p bazzer,boffer + + +%files -f .ofiles +%doc README +%license LICENSE + + +%files devel -f .ofiles-devel + + +%changelog +%autochangelog diff --git a/guidelines/modules/ROOT/examples/ocaml-example.spec b/guidelines/modules/ROOT/examples/ocaml-example.spec index ff8f69b..02591d8 100644 --- a/guidelines/modules/ROOT/examples/ocaml-example.spec +++ b/guidelines/modules/ROOT/examples/ocaml-example.spec @@ -1,21 +1,20 @@ -%global opt %(test -x %{_bindir}/ocamlopt && echo 1 || echo 0) +%undefine _package_note_flags + +%ifnarch %{ocaml_native_compiler} %global debug_package %{nil} +%endif Name: ocaml-foolib Version: 1.2.3 -Release: 1%{?dist} +Release: %autorelease Summary: OCaml library for fooing bars License: LGPL-2.1-or-later URL: https://www.example.com/foolib -Source: https://www.example.com/foolib-1.2.3.tar.gz -BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root-%(%{__id_u} -n) +Source: https://www.example.com/foolib-%{version}.tar.gz -BuildRequires: ocaml, ocaml-findlib-devel - -%global _use_internal_dependency_generator 0 -%global __find_requires /usr/lib/rpm/ocaml-find-requires.sh -%global __find_provides /usr/lib/rpm/ocaml-find-provides.sh +BuildRequires: ocaml +BuildRequires: ocaml-findlib %description OCaml library for fooing bars. This library can also foo bazes. @@ -23,7 +22,7 @@ OCaml library for fooing bars. This library can also foo bazes. %package devel Summary: Development files for %{name} -Requires: %{name} = %{version}-%{release} +Requires: %{name}%{?_isa} = %{version}-%{release} %description devel @@ -32,52 +31,46 @@ developing applications that use %{name}. %prep -%setup -q -n foolib-%{version} -# You may need a ./configure step here. +%autosetup -n foolib-%{version} %build +# You may need a ./configure step here. make byte -%if %opt +%ifarch %{ocaml_native_compiler} make opt %endif %install # These rules work if the library uses 'ocamlfind install' to install itself. -export DESTDIR=$RPM_BUILD_ROOT -export OCAMLFIND_DESTDIR=$RPM_BUILD_ROOT%{_libdir}/ocaml -mkdir -p $OCAMLFIND_DESTDIR $OCAMLFIND_DESTDIR/stublibs -make install - - -%clean -rm -rf $RPM_BUILD_ROOT +export OCAMLFIND_DESTDIR=%{buildroot}%{ocamldir} +mkdir -p $OCAMLFIND_DESTDIR/stublibs +%make_install %files %doc README -%{_libdir}/ocaml/foolib -%if %opt -%exclude %{_libdir}/ocaml/foolib/*.a -%exclude %{_libdir}/ocaml/foolib/*.cmxa -%exclude %{_libdir}/ocaml/foolib/*.cmx +%license LICENSE +%{ocamldir}/foolib +%ifarch %{ocaml_native_compiler} +%exclude %{ocamldir}/foolib/*.a +%exclude %{ocamldir}/foolib/*.cmxa +%exclude %{ocamldir}/foolib/*.cmx %endif -%exclude %{_libdir}/ocaml/foolib/*.mli -%{_libdir}/ocaml/stublibs/*.so -%{_libdir}/ocaml/stublibs/*.so.owner +%exclude %{ocamldir}/foolib/*.mli +%{ocamldir}/stublibs/*.so +%{ocamldir}/stublibs/*.so.owner %files devel -%doc README -%if %opt -%{_libdir}/ocaml/foolib/*.a -%{_libdir}/ocaml/foolib/*.cmxa -%{_libdir}/ocaml/foolib/*.cmx +%ifarch %{ocaml_native_compiler} +%{ocamldir}/foolib/*.a +%{ocamldir}/foolib/*.cmxa +%{ocamldir}/foolib/*.cmx %endif -%{_libdir}/ocaml/foolib/*.mli +%{ocamldir}/foolib/*.mli %changelog -* Sat May 26 2007 Your Name - 1.2.3-1 -- Initial RPM release. +%autochangelog diff --git a/guidelines/modules/ROOT/examples/ocaml-topkg-example.spec b/guidelines/modules/ROOT/examples/ocaml-topkg-example.spec new file mode 100644 index 0000000..7d5d969 --- /dev/null +++ b/guidelines/modules/ROOT/examples/ocaml-topkg-example.spec @@ -0,0 +1,74 @@ +%undefine _package_note_flags + +%ifnarch %{ocaml_native_compiler} +%global debug_package %{nil} +%endif + +Name: ocaml-foolib +Version: 1.2.3 +Release: %autorelease +Summary: OCaml library for fooing bars + +License: LGPL-2.1-or-later +URL: https://www.example.com/foolib +Source: https://www.example.com/foolib-%{version}.tar.gz + +BuildRequires: ocaml +BuildRequires: ocaml-findlib +BuildRequires: ocaml-topkg-devel +BuildRequires: python3 + +%description +OCaml library for fooing bars. This library can also foo bazes. + + +%package devel +Summary: Development files for %{name} +Requires: %{name}%{?_isa} = %{version}-%{release} + + +%description devel +The %{name}-devel package contains libraries and signature files for +developing applications that use %{name}. + + +%prep +%autosetup -n foolib-%{version} + +# Enable debuginfo if upstream does not +echo true: debug >> _tags + + +%build +ocaml pkg/pkg.ml build --tests true + + +%install +mkdir -p %{buildroot}%{ocamldir}/foolib +cp -p _build/{opam,pkg/META} %{buildroot}%{ocamldir}/foolib +%ifarch %{ocaml_native_compiler} +cp -a _build/src/*.{a,cma,cmi,cmt,cmti,cmx,cmxa,cmxs,mli} \ + %{buildroot}%{ocamldir}/foolib +%else +cp -a _build/src/*.{cma,cmi,cmt,cmti,mli} %{buildroot}%{ocamldir}/foolib +%endif + +# This macro requires python3 in the buildroot +%ocaml_files + + +%check +ocaml pkg/pkg.ml test + + +%files -f .ofiles +%doc README +%license LICENSE + + +%files devel -f .ofiles-devel +%ifarch %{ocaml_native_compiler} + + +%changelog +%autochangelog diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc index 69ddbf0..565a9eb 100644 --- a/guidelines/modules/ROOT/pages/OCaml.adoc +++ b/guidelines/modules/ROOT/pages/OCaml.adoc @@ -1,27 +1,22 @@ = OCaml Packaging Guidelines -This document seeks to document the conventions and customs surrounding the proper packaging of OCaml modules in Fedora. It does not intend to cover all situations, but to codify those practices which have served the Fedora OCaml community well. +This document seeks to document the conventions and customs surrounding the proper packaging of OCaml modules in Fedora. +It does not intend to cover all situations, but to codify those practices which have served the Fedora OCaml community well. == Naming The base OCaml compiler is called ocaml. -OCaml modules, libraries and syntax extensions should be named ocaml-foo. Examples include: ocaml-extlib, ocaml-ssl. +OCaml modules, libraries and syntax extensions should be named ocaml-foo. +Examples include: ocaml-extlib, ocaml-ssl. -This naming does not apply to applications written in OCaml, which can be given their normal name. Examples include: mldonkey, virt-top, cduce. +This naming does not apply to applications written in OCaml, which can be given their normal name. +Examples include: coccinelle, frama-c, virt-top. Rationale: this is how they are named in other distros (Debian, PLD) and this is consistent with Perl / PHP / Python naming. == Packaging libraries -The following is an example specfile for an imaginary OCaml library called _foolib_. - -.ocaml-example.spec -[source] ----- -include::{examplesdir}/ocaml-example.spec[] ----- - === Main package In order to allow OCaml scripts and the toplevel to use a library, the main package should contain only files matching: @@ -31,17 +26,17 @@ In order to allow OCaml scripts and the toplevel to use a library, the main pack * *.so (if present, contains OCaml <-> C stubs) * META (the findlib description) * *.so.owner (if present, used by findlib) -* a license file (if present) marked %doc +* a license file (if present) marked %license -* .cmo files are not normally included. There are two exceptions where *.cmo files may be included: -* if file is needed for link (like gtkInit.cmo in lablgtk or std_exit.cmo in OCaml itself), then it must be included to allow the library to be linked properly. -* if the cmo file is a camlp4 preprocessor (like Camlp4OCamlPrinter.cmo in OCaml), then it must be included because otherwise the syntax extension would not be available. +* .cmo files are not normally included. There is one exception where *.cmo files may be included: if the cmo file is needed to link, then it must be included to allow the library to be linked properly. -If the package contains *.so files, then they should have rpaths removed, as per Fedora packaging guidelines. +If the package contains *.so files, then they should not have rpaths, as per Fedora packaging guidelines. -The packager should check the META file footnote:[http://projects.camlcity.org/projects/dl/findlib-1.9.1/doc/ref-html/r759.html[findlib Reference Manual - META files.]]. If there is no META file, then the packager should create one, include it in the package, and pass it to the upstream maintainer. +The packager should check the META file footnote:[http://projects.camlcity.org/projects/dl/findlib-1.9.5/doc/ref-html/r759.html[findlib Reference Manual - META files.]]. +If there is no META file, then the packager should create one, include it in the package, and pass it to the upstream maintainer. -Rationale: OCaml does not support dynamic linking of binaries, and even if it did with the current module hash system for expressing strict typing requirements almost any conceivable change to a library would require the binary to be recompiled. OCaml scripts are the closest we come to dynamic linking, in as much as they do not usually depend on a specific version of a library (albeit this only works because the scripts are recompiled each time they run). +Rationale: OCaml does not support dynamic linking of binaries, and even if it did with the current module hash system for expressing strict typing requirements almost any conceivable change to a library would require the binary to be recompiled. +OCaml scripts are the closest we come to dynamic linking, in as much as they do not usually depend on a specific version of a library (albeit this only works because the scripts are recompiled each time they run). === -devel subpackage @@ -52,17 +47,21 @@ The -devel subpackage of a library should contain all other files required to al * *.cmx (if present, allows cross-module optimizations) * *.mli (contains the signature of the library) -* .o files are not normally included. There is however one exception -- if file is needed for link (like gtkInit.cmx and gtkInit.o in lablgtk or std_exit.cmx and std_exit.o in OCaml itself), then it should be included. +* .o files are not normally included. There is one exception -- if the file is needed to link (like std_exit.cmx and std_exit.o in OCaml itself), then it should be included. * .ml files are not normally included. The exception is if the file describes a module signature _and_ there is no corresponding .mli file, then the .ml file should be included. (Note that Debian is more permissive and they often distribute *.ml files, allowing the programmer to peek at the implementation of a module). -Documentation, examples and other articles which are useful to the developer may be included in the -devel sub-package. The license file (which is in the main package) does not need to be included again in the -devel subpackage. +Documentation, examples and other articles which are useful to the developer may be included in the -devel sub-package. +The license file (which is in the main package) does not need to be included again in the -devel subpackage. If the -devel subpackage would only contain documentation files, then the packager may at their discretion place the documentation files in the main package and not have a -devel subpackage at all. -The -devel subpackage should require the exact name-version-release of the main package (as per Fedora policy). It should also require any C libraries required for development, and sometimes this means an explicit 'Requires' is needed. For example, ocaml-pcre-devel needs an explicit 'Requires: pcre-devel' to make it usable for development. +The -devel subpackage should require the exact name-version-release of the main package (as per Fedora policy). +It should also require any C libraries required for development, and sometimes this means an explicit 'Requires' is needed. +For example, ocaml-pcre-devel needs an explicit 'Requires: pcre-devel' to make it usable for development. -Rationale for inclusion of all cmx files: [*.cmx files] are needed even for module included in .cmxa libraries in order to enable cross-module optimizations (inlining, constant propagation and direct function calls). The .o files are not needed. [From a private email from Alain Frisch] +Rationale for inclusion of all cmx files: [*.cmx files] are needed even for modules included in .cmxa libraries in order to enable cross-module optimizations (inlining, constant propagation and direct function calls). +The .o files are not needed. [From a private email from Alain Frisch] === -doc subpackage @@ -83,15 +82,12 @@ Similarly for each module that library A may provide to other libraries, library A library must depend on the precise version of the OCaml compiler, for example: ocaml(runtime) = 3.10.0 -There are two scripts in the base ocaml package which automatically calculate the right Requires and Provides for a library. To use them, just add the following to the spec file: +The correct Requires and Provides should be generated automatically. -.... -%global _use_internal_dependency_generator 0 -%global __find_requires /usr/lib/rpm/ocaml-find-requires.sh -%global __find_provides /usr/lib/rpm/ocaml-find-provides.sh -.... - -Rationale: OCaml does not offer binary compatibility between releases of the compiler (even between bugfixes). Furthermore the module system uses a hash over the interface and some internals of a module which basically means a library or program must be linked against the identical modules it was compiled with. The Requires and Provides lines express the module name and hash so that RPM enforces the same requirements as the OCaml linker itself. Please see the further reading at the end of this page for more details. +Rationale: OCaml does not offer binary compatibility between releases of the compiler (even between bugfixes). +Furthermore the module system uses a hash over the interface and some internals of a module which basically means a library or program must be linked against the identical modules it was compiled with. +The Requires and Provides lines express the module name and hash so that RPM enforces the same requirements as the OCaml linker itself. +Please see the further reading at the end of this page for more details. == Packaging binaries @@ -103,7 +99,9 @@ However if the OCaml package also contains a library, then you should follow the Binaries should be stripped, as per ordinary Fedora packaging guidelines. -There is one exception where a binary should not be stripped. If the package was compiled with ocamlc -custom then the package contains bytecode which strip will remove, thus rendering the binary inoperable. It is easy to test for this: If after stripping, any attempt to run the binary results in the message _No bytecode file specified_ then the binary is compiled like this and should not be stripped. +There is one exception where a binary should not be stripped. +If the package was compiled with `ocamlc -custom` then the package contains bytecode which strip will remove, thus rendering the binary inoperable. +It is easy to test for this: if after stripping, any attempt to run the binary results in the message _No bytecode file specified_ then the binary is compiled like this and should not be stripped. Rationale: https://bugs.debian.org/256900 @@ -113,20 +111,17 @@ The packager should attempt to ship native code compiled binaries in preference == Bytecode-only architectures -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, do: - -.... -%global opt %(test -x %{_bindir}/ocamlopt && echo 1 || echo 0) -.... +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. -then define conditional sections in %build, %install and %files if necessary. For example: +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: .... %build make byte -%if %opt +%ifarch %{ocaml_native_compiler} make opt %endif .... @@ -147,7 +142,71 @@ The following files should not normally be distributed: If a security issue arises in an OCaml library, then all libraries and binaries which depend on it must be recompiled. -OCaml scripts do not need to be changed (unless resolving the security issue requires changing the public interface to the library and the script is broken by the change). This is because OCaml scripts are recompiled each time they run. +OCaml scripts do not need to be changed (unless resolving the security issue requires changing the public interface to the library and the script is broken by the change). +This is because OCaml scripts are recompiled each time they run. + +== RPM Macros + +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: + * -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). + +== Examples + +This section contains example spec files illustrating how to build OCaml library and binary packages with various build tools. + +=== Dune + +Dune is a popular build tool for OCaml packages. +RPM macros are available to make building with dune simple. +* `%dune_build`: Invoke dune to build all installable artifacts in release mode. 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`. + * -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact. + * --: 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. + * --: 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`. + * -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact. + * --: separate flags for this macro from flags to pass to dune +* `%odoc_package`: Declare a subpackage that olds odoc-generated documentation. Flags: + * -L : give the name of a file to include in the subpackage as a license file. + +The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with dune. + +.ocaml-dune-example.spec +[source] +---- +include::{examplesdir}/ocaml-dune-example.spec[] +---- + +=== Topkg + +Topkg, the "transitory OCaml software packager", generates scripts that are executed to perform various package and build tasks. + +The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with topkg. + +.ocaml-topkg-example.spec +[source] +---- +include::{examplesdir}/ocaml-topkg-example.spec[] +---- + +=== Other build tools + +The following is an example specfile for an imaginary OCaml library called _foolib_. + +.ocaml-example.spec +[source] +---- +include::{examplesdir}/ocaml-example.spec[] +---- == Further reading From 3397f78dc0ab59108b7be611ccdcf816956f7935 Mon Sep 17 00:00:00 2001 From: Neal Gompa Date: Apr 19 2023 19:18:38 +0000 Subject: [PATCH 49/232] guidelines/Naming: Add note of naming convention for GStreamer plugins This has been the generally accepted practice for quite a while now, let's document it so people are aware. --- diff --git a/guidelines/modules/ROOT/pages/Naming.adoc b/guidelines/modules/ROOT/pages/Naming.adoc index 7ff5ec1..1fce4b6 100644 --- a/guidelines/modules/ROOT/pages/Naming.adoc +++ b/guidelines/modules/ROOT/pages/Naming.adoc @@ -328,6 +328,15 @@ with the prefix `+gnome-shell-extension-+`. In particular, this prefix SHOULD NOT be pluralized (i.e., it SHOULD NOT be `+gnome-shell-extensions+`). +=== GStreamer plugins + +Packages that extend GStreamer SHOULD begin +with the prefix `+gstreamer1-plugin-+`. +In particular, this prefix SHOULD NOT be pluralized +(i.e., it SHOULD NOT be `+gstreamer1-plugins+`) +unless it is a collection of plugins +(i.e., `+gstreamer1-plugins-good+`). + === LibreOffice extensions Packages of LibreOffice extensions From aa17c26399c4ed0ceca85b734db43bf823bae0dd Mon Sep 17 00:00:00 2001 From: Neal Gompa Date: Apr 19 2023 19:23:57 +0000 Subject: [PATCH 50/232] guidelines/Naming: Add information about NGINX module packages It has been possible to package NGINX modules for a few cycles now and a few packages exist in the distribution. This documents the pattern being used there. --- diff --git a/guidelines/modules/ROOT/pages/Naming.adoc b/guidelines/modules/ROOT/pages/Naming.adoc index 1fce4b6..a7409cd 100644 --- a/guidelines/modules/ROOT/pages/Naming.adoc +++ b/guidelines/modules/ROOT/pages/Naming.adoc @@ -381,6 +381,16 @@ Some examples: |============================================= +=== NGINX modules + +Packages of NGINX modules SHOULD begin +with the prefix `+nginx-mod-+`. +In particular, this prefix SHOULD NOT be pluralized +(i.e., it SHOULD NOT be `+nginx-mods+`). +Some upstream projects may use `+module+` as a +prefix, and this should be accounted for and +replaced accordingly in the package name. + === OCaml modules OCaml modules, libraries and syntax extensions From 34480a83b52c5d67516282c83c2cd615e8caa74f Mon Sep 17 00:00:00 2001 From: Neal Gompa Date: Apr 19 2023 19:28:58 +0000 Subject: [PATCH 51/232] guidelines/Naming: Add a note for OBS Studio plugin packages OBS Studio is now packaged in Fedora, and plugin packages are on the way. This documents the naming convention for these packages. --- diff --git a/guidelines/modules/ROOT/pages/Naming.adoc b/guidelines/modules/ROOT/pages/Naming.adoc index a7409cd..09cbfb7 100644 --- a/guidelines/modules/ROOT/pages/Naming.adoc +++ b/guidelines/modules/ROOT/pages/Naming.adoc @@ -391,6 +391,13 @@ Some upstream projects may use `+module+` as a prefix, and this should be accounted for and replaced accordingly in the package name. +=== OBS Studio plugins + +Packages of OBS Studio plugins SHOULD begin +with the prefix `+obs-studio-plugin-+`. +In particular, this prefix SHOULD NOT be pluralized +(i.e., it SHOULD NOT be `+obs-studio-plugins+`). + === OCaml modules OCaml modules, libraries and syntax extensions From 33d7924d64a86833701627dc82da383460fbf1db Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Apr 25 2023 09:13:22 +0000 Subject: [PATCH 52/232] mingw: use RPM source syntax highlighting Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index 10e25fc..bfcebf6 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -105,23 +105,25 @@ replaced by `+%mingw_find_lang+`. This causes all translation filelists to be split in per-target filelists. For example: when a spec file contains something like this: -.... +[source, rpm-spec] +---- %install %mingw_find_lang foo -.... +---- then one file per mingw target will get created named `+mingw32-foo.lang+`, `+mingw64-foo.lang+`, and `+ucrt64-foo.lang+`. These file lists can be included in the %files section for the targets: -.... +[source, rpm-spec] +---- %files -n mingw32-foo -f mingw32-foo.lang %files -n mingw64-foo -f mingw64-foo.lang %files -n ucrt64-foo -f ucrt64-foo.lang -.... +---- == Filesystem layout @@ -209,27 +211,29 @@ guidelines. The MinGW cross-compilers and binutils which generate i686 binaries for Windows with the MSVCRT runtime are named: -.... +[source, rpm-spec] +---- %{_bindir}/i686-w64-mingw32-gcc %{_bindir}/i686-w64-mingw32-g++ %{_bindir}/i686-w64-mingw32-ld %{_bindir}/i686-w64-mingw32-as %{_bindir}/i686-w64-mingw32-strip etc. -.... +---- The same binaries are present in `+%{_prefix}/i686-w64-mingw32/bin+` without any prefix in the name, i.e., -.... +[source, rpm-spec] +---- %{_prefix}/i686-w64-mingw32/bin/gcc %{_prefix}/i686-w64-mingw32/bin/g++ %{_prefix}/i686-w64-mingw32/bin/ld %{_prefix}/i686-w64-mingw32/bin/as %{_prefix}/i686-w64-mingw32/bin/strip etc. -.... +---- The same also applies for the x86_64 target with both MSVCRT and UCRT runtimes. The target with MSVCRT uses 'x86_64-w64-mingw32' @@ -245,21 +249,24 @@ because MinGW requires a root filesystem location. The location for Win32 target with MSVCRT runtime is provided by the macro: -.... +[source, rpm-spec] +---- %{mingw32_sysroot} %{_prefix}/i686-w64-mingw32/sys-root -.... +---- The Win64 target with MSVCRT runtime is provided by the macro: -.... +[source, rpm-spec] +---- %{mingw64_sysroot} %{_prefix}/x86_64-w64-mingw32/sys-root -.... +---- The Win64 target with UCRT runtime is provided by the macro: -.... +[source, rpm-spec] +---- %{ucrt64_sysroot} %{_prefix}/x86_64-w64-mingw32ucrt/sys-root -.... +---- @@ -450,7 +457,8 @@ are packages which have to be built once for a static version and once for a shared version. Such packages can add a custom suffix to the build directory used. Say you've got something like below: -.... +[source, rpm-spec] +---- mkdir build_shared pushd build_shared %{mingw32_configure} --enable-shared @@ -459,14 +467,15 @@ used. Say you've got something like below: pushd build_static %{mingw32_configure} --enable-static popd -.... +---- This can be rewritten to something like this: -.... +[source, rpm-spec] +---- MINGW_BUILDDIR_SUFFIX=shared %mingw_configure --enable-shared MINGW_BUILDDIR_SUFFIX=static %mingw_configure --enable-static -.... +---- Most packages used the command `+make %{?_smp_mflags}+` to build the package. In the MinGW cross compiler framework you have to use @@ -502,9 +511,10 @@ form 'mingw32(foo.dll)' should be used for Win32 binaries and the form Correct dependency generation is done automatically. Packagers should start their spec files with this line: -.... +[source, rpm-spec] +---- %{?mingw_package_header} -.... +---- All binary packages should depend on `+mingw32-filesystem+` or `+mingw64-filesystem+` (depending on the files in the package). @@ -512,8 +522,11 @@ All binary packages should depend on `+mingw32-filesystem+` or All specfiles should BuildRequire at least one of these (depending on the targets for which you want to build): -`+BuildRequires:  mingw32-filesystem+` + -`+BuildRequires:  mingw64-filesystem+` +[source, rpm-spec] +---- + BuildRequires:  mingw32-filesystem + BuildRequires:  mingw64-filesystem +---- and any other BuildRequires that they need. @@ -525,7 +538,10 @@ dependancy on the `+mingw-XX-filesystem+` packages should be used. All packages should have: -`+BuildArch: noarch+` +[source, rpm-spec] +---- + BuildArch: noarch +---- unless they contain Fedora native executables. @@ -538,10 +554,11 @@ Because of the peculiarity of Windows, DLLs are stored in the `+%{mingw32_libdir}+` directory. For example, for a library called `+foo+` there would be: -.... +[source, rpm-spec] +---- %{mingw32_bindir}/foo.dll %{mingw32_libdir}/foo.dll.a -.... +---- The `+foo.dll+` file is the main library, `+foo.dll.a+` is a stub linked to applications so they can find the library at runtime. All of these files are @@ -562,9 +579,10 @@ explicitly in the `+%files+` section in order to catch this during RPM builds. Libraries and executables should be stripped. This is done correctly and automatically if the spec file starts with this line: -.... +[source, rpm-spec] +---- %{?mingw_package_header} -.... +---- === Debuginfo subpackage @@ -572,11 +590,12 @@ Most binaries contain debugging symbols when the package gets built. To split the debugging symbols to a separate debuginfo package (as is done with native Fedora packages) the spec file must include these lines: -.... +[source, rpm-spec] +---- %{?mingw_package_header} [...] %{?mingw_debug_package} -.... +---- The `+%{?mingw_debug_package}+` line must be placed after the `+%description tag+`. Otherwise spectool and other RPM tools may fail to @@ -625,7 +644,8 @@ to bundle it with their Windows installers. == Example Specfile -.... +[source, rpm-spec] +---- %{?mingw_package_header} Name: mingw-example @@ -740,4 +760,4 @@ find %{buildroot} -name "*.la" -delete %changelog * Sun Apr 15 2012 Erik van Pienbroek - 1.0.0-1 - Initial release -.... +---- From cf7a8d2758ccb4dd8dee2b000acecfb500574693 Mon Sep 17 00:00:00 2001 From: Daniel P. Berrangé Date: Apr 27 2023 09:34:28 +0000 Subject: [PATCH 53/232] mingw: document approach for integrating mingw with native packages Historically the mingw packages were introduced as completely separate components in Fedora, with their own spec files, separate maintainers, etc. This was driven primarily from a reasonable concern that the maintenence of MinGW builds would be an unacceptable burden on the existing native package maintainers. In the many years since MinGW was introduced to Fedora, however, it has become clear that this concern was mostly unfounded. While some packages may be more difficult, the majority of MinGW packages are not difficult to keep building successfully in Fedora. Furthermore the existance of MinGW support in Fedora, has enabled upstream projects to actively test Windows support in their CI systems prior to release. There biggest problem for MinGW packages in Fedora has turned out to be caused by the very decision to package them as completely separated components. Specifically it is difficult to ensure that MinGW builds are being kept in sync with changes to the native package builds, even when both share the same maintainer. This is particularly apparent when looking at reports of unaddressed CVEs in Fedora packages. With this all in mind, it is the view of the MinGW SIG that Fedora is best served by having MinGW support integrated into the native packages in general. While the specific maintainer of the native package will have slightly more work, history has demonstrated this is not likely to be significant in most cases. For Fedora maintainers in aggregate, the amount of effort spent on MinGW will decrease, benefiting the project as a whole. This proposal thus strongly promotes the integrated MinGW packaging approach to be the default, though existing native package maintainers retain the ability to decline such proposals. The concept of integrating MinGW support into the native packages has already been put into practice on many packages where the same Fedora contributor maintained both the MinGW and native packages. Specifically examples implemented by Sandro Mani are: mingw-eigen3 mingw-enchant2 mingw-freeimage mingw-gdal mingw-GeographicLib mingw-geos mingw-giflib mingw-gtkspell3 mingw-gtkspellmm30 mingw-jxrlib mingw-leptonica mingw-libgeotiff mingw-libimagequant mingw-libkml mingw-librttopo mingw-libspatialite mingw-libwebp mingw-openjpeg2 mingw-OpenSceneGraph mingw-osgearth mingw-podofo mingw-proj mingw-python-pillow mingw-qtspell mingw-shapelib mingw-svg2svgt mingw-tesseract mingw-uriparser and examples by Daniel Berrange are mingw-libvirt mingw-gtk-vnc mingw-libvirt-glib mingw-libosinfo mingw-osinfo-db-tools Signed-off-by: Daniel P. Berrangé --- diff --git a/guidelines/modules/ROOT/pages/MinGW.adoc b/guidelines/modules/ROOT/pages/MinGW.adoc index bfcebf6..6c09a84 100644 --- a/guidelines/modules/ROOT/pages/MinGW.adoc +++ b/guidelines/modules/ROOT/pages/MinGW.adoc @@ -1,5 +1,5 @@ = Packaging Guidelines for MinGW Cross Compilers - + == Introduction The Fedora MinGW project's mission is to provide an excellent development @@ -18,6 +18,108 @@ Win64 with the UCRT runtime is also supported, however, only for the base toolchain. Builds for UCRT are not enabled for packages above the toolchain at this time. +== Separate vs integrated MinGW source packages + +There are two permitted ways to provide MinGW builds of software in Fedora: + +* **Separate source packages**: There are distinct RPM spec files for the + native and MinGW builds, maintained as independent components of Fedora. + This is the traditional approach to MinGW packaging in Fedora + +* **Integrated source packages**: There is a single RPM spec file for the + native and MinGW builds, as a single component of Fedora. The MinGW builds + are emitted as binary sub-RPMs. This is the modern, preferred, approach to + MinGW packaging in Fedora. + +The traditional approach of completely separated source packages was adopted +initially because of concerns that instability in the MinGW toolchain or +Windows builds may prevent timely updates to the native package. Experience +in Fedora since then has shown that is not generally a problem that impacts +most packages, especially where Windows support is an explicitly tested +deliverable of the upstream project. + +Using the separate packaging approach has a significantly higher overhead: + +* The addition of MinGW support must go through the full Fedora review + process for new packages, largely duplicating review already performed + on the native package. + +* There is an ongoing burden for the maintainer to ensure the MinGW source + package tracks changes to the corresponding native source package as it + rebases to new releases. + +* There is additional work in handling patches/updates in response to bug + reports. Bug reports are often only reported against one of the two + components not both, but with security vulnerabilities there are twice + the number of bug reports created. There are then also multiple koji + builds and updates to handle. + +With the integrated packaging approach there is a small extra overhead on the +native package maintainer to ensure MinGW builds keep working and a small +additional load of MinGW specific bug reports. This is usually negligible +compared to the overhead of maintaining separated packages. + +With this in mind, the recommendation of the MinGW SIG is thus: + +* Where the same Fedora contributor intends to maintain both the native + and MinGW builds of a package, they **MUST** use the integrated packaging + approach. + +* Where the upstream project explicitly supports the Windows platform as + a build target and has automated CI, contributors **SHOULD** prefer the + integrated MinGW packaging approach. Native package maintainers **SHOULD** + ordinarily accept addition of integrated MinGW support. If declining the + request the native maintainer should give a rationale for their decision. + +* Where the upstream project does not have automated testing of Windows + builds, the MinGW package support **MAY** use either packaging approach. + The native maintainer may decline the request for integrated packaging + at their discretion. + +* Where the upstream project only supports Windows builds, the separate + packaging approach **MUST** be used. There will be no corresponding + native package in Fedora expected. This situation is very rare. + +* When a contributor proposes a new native package to Fedora that provides + libraries that are known to support Windows, the reviewer **SHOULD** + inquire whether the contributor would like to add MinGW builds at the + same time. The contributor may decline this request at their discretion. + +== Adding MinGW support alongside a new native package + +When a corresponding native package does not already exist, it will always +be required to go through the standard Fedora new package review process. +The proposed MinGW support **MUST** follow the integrated packaging approach +to provide both the MinGW and native builds, where technically possible. +As noted in the previous section, in some rare situations there will be no +corresponding native package, thus requiring the separate pacakaging approach +to be taken. + +== Adding MinGW support to an existing native package + +When a corresponding native package is already present in Fedora, the +preference is to add MinGW support to the native source package. + +Where the source package changes are simple, the contributor **SHOULD**: + + * Make the required spec file additions in their fork of the package + * Submit a koji scratch-build to prove the changes have the expected + effect + * Open a merge request against the native package with the spec changes, + adding a link to the koji scratch-build results as a comment. + +The existing native package maintainer thus gets clear view of the impact of +the MinGW additions to their package, to evaluate the viability of following +the integrated packaging approach. + +Where there is doubt about the viability of following the integrated package +approach, a bug **MAY** be opened against the package ahead of starting work +to discuss the two packaging options with the native package maintainer. + +If the native maintainer declines the proposal to add MinGW support to the +existing package, the regular Fedora new package process MUST be followed +to introduce MinGW support following the separate packaging approach. + == Track Fedora native package versions In general terms, cross-compiled MinGW versions of packages which are already @@ -26,6 +128,9 @@ as possible. This means they should stay at the same version, include all the same patches as the native Fedora package, and be built with the same configuration options. +The preferred way to achieve this goal is for the MinGW support to use the +integrated packaging approach. + == Follow Fedora policy Cross compiled MinGW packages must follow Fedora policy, except where noted in @@ -43,7 +148,7 @@ packages are created by sections with `+%files -n mingw32-foo+`, [cols=",",] |======================================================= -|`+mingw-+` |Used for source package and RPM spec name +|`+mingw-+` |Used for source package and RPM spec name (only where the separate packaging approach is chosen) |`+mingw32-+` |Used for packages which are built for Win32 with the MSVCRT runtime |`+mingw64-+` |Used for packages which are built for Win64 with the MSVCRT runtime |`+ucrt64-+` |Used for packages which are built for Win64 with the UCRT runtime @@ -74,7 +179,7 @@ To aid developers in this several RPM macros have been developed which are part of the mingw-filesystem package. These RPM macros will be explained later on in these guidelines. -By default a MinGW package will be built for both the Win32 and Win64 targets +By default MinGW support will be built for both the Win32 and Win64 targets with the MSVCRT runtime. Building of the Win64 target with the UCRT64 runtime is not yet enabled by default. @@ -92,18 +197,22 @@ indicated by setting one or more of these: Each cross compiled MinGW package which builds binaries for a specific target should put the binaries for that target in a separate subpackage. So if a -package `+foo+` builds binaries for the Win32 and Win64 targets with the MSVCRT -runtime, then the source RPM should provide two subpackages named `+mingw32-foo+` -and `+mingw64-foo+`. If a package builds for the UCRT runtime, it will also -have a `+ucrt64-foo+` subpackage. +package `+mingw-foo+` or `+foo+` builds binaries for the Win32 and Win64 targets +with the MSVCRT runtime, then the source RPM should provide two subpackages +named `+mingw32-foo+` and `+mingw64-foo+`. If a package builds for the UCRT +runtime, it will also have a `+ucrt64-foo+` subpackage. This means that a spec file must contains %package and %files sections for all the targets. -If a package contains translations then all calls to the `+%find_lang+` must be -replaced by `+%mingw_find_lang+`. This causes all translation filelists to be -split in per-target filelists. For example: when a spec file contains something -like this: +When using the separate packaging approach, packages containing translations +must use `+%mingw_find_lang+` instead of `+%find_lang+`. + +When using the integrated packaging approach, packages containing translations +must use `+%find_lang` followed by `+%mingw_find_lang+`. + +This causes all translation filelists to be split in per-target filelists. For +example: when a spec file contains something like this: [source, rpm-spec] ---- @@ -543,7 +652,11 @@ All packages should have: BuildArch: noarch ---- -unless they contain Fedora native executables. +unless they contain Fedora native executables. Where using the separate +packaging approach, the `+BuildArch+` tag must be present in the common +spec file header. Where using the integrated packaging approach, the +`+BuildArch+` tag must be present under the %package header for each MinGW +sub-RPM that is present. == Libraries (DLLs) @@ -601,6 +714,17 @@ The `+%{?mingw_debug_package}+` line must be placed after the `+%description tag+`. Otherwise spectool and other RPM tools may fail to function. +When using the integrated packaging approach the `+%install+` section must +also contain a call to the `+%{mingw_debug_install_post}+` macro after any +binary files have been installed to the virtual root: + +[source, rpm-spec] +---- + %install + [...] + %{?mingw_debug_install_post} +---- + == File listing The MinGW packages are intended to allow developers to compile and test the @@ -642,7 +766,236 @@ Note, generic Documentation aimed at end users, as opposed to developers, should be included where it is likely that application developers will want to bundle it with their Windows installers. -== Example Specfile +== Converting between separate and integrated packaging + +In general it it possible to convert in either direction between the separate +and integrated packaging approaches. Both approaches result in the exact same +binary RPMs for MinGW content, only differing in their source RPM specfile. + +To convert from separate to integrated packaging + +* Ensure the existing native software package has either the same (or newer) + version number as the existing MinGW package. +* Add MinGW support to the existing native package spec file +* If both the native and existing MinGW packages were at the same version, + ensure the release number of the native package is newer than any previous + build of the MinGW package. +* Build the new native package with MinGW support +* Retire the separate MinGW package + +To convert from integrated to separate packaging + +* Go through the new package review process for the separate MinGW package, + ensuring it is the same version number as the existing integrated package +* Import the separate MinGW package to dist-git but don't build it. +* Drop MinGW support from the existing native package spec file +* Build the native package without MinGW support +* Ensure the separate MinGW package has a newer release number than any existing + MinGW binary sub-RPMs built from the native package +* Build the separate MinGW package + +In both cases the upgrade experience should be transparent to users installing +and updating Fedora deployments. + +It is recommended that such conversions only be performed in Rawhide. If there +is need to do a conversion from integrated to separate packaging in a stable +release stream, a single Bohdi update must include both the native and mingw +package builds. + +== Disabling MinGW packages + +When using the integrated packaging approach it **MUST** be possible to disable +the build of MinGW sub-RPMs, and the build **MUST** be disabled by default +except for the Fedora distribution target. This ensures that the native package +can still be built in derivative distros, such as RHEL, where the MinGW +toolchains not included. This is achieved by including a conditional near +the top of the specfile: + +[source, rpm-spec] +---- +%if 0%{?fedora} +%bcond_without mingw +%else +%bcond_with mingw +%endif +---- + +and then wrapping all MinGW related `+%package+` / `+%files` definitions and +relevant `+%build+` or `+%install+` commands in a conditional check: + +[source, rpm-spec] +---- +%if %{with mingw} +%package -n mingw32-example +Summary: %{summary} +BuildArch: noarch +[...] +%endif +---- + +== Example Integrated Package Specfile + +[source, rpm-spec] +---- +%if 0%{?fedora} +%bcond_without mingw +%else +%bcond_with mingw +%endif + +Name: example +Version: 1.0.0 +Release: 1%{?dist} +Summary: Example library + +License: LGPL-2.1-or-later +URL: https://fedoraproject.org +Source: https://fedoraproject.org/example-%{version}.tar.bz2 + +BuildRequires: gcc +BuildRequires: binutils +BuildRequires: gettext +BuildRequires: zlib + +%if %{with mingw} +BuildRequires: mingw32-filesystem +BuildRequires: mingw32-gcc +BuildRequires: mingw32-binutils +BuildRequires: mingw32-gettext +BuildRequires: mingw32-win-iconv +BuildRequires: mingw32-zlib + +BuildRequires: mingw64-filesystem +BuildRequires: mingw64-gcc +BuildRequires: mingw64-binutils +BuildRequires: mingw64-gettext +BuildRequires: mingw64-win-iconv +BuildRequires: mingw64-zlib +%endif + +%description +Example library. + +%package devel +Summary: Example library development package +... + +%description devel +Example library development headers and library. + +%if %{with mingw} +# If a package maintainer wishes to bundle static libraries then they +# can be placed in -static subpackages. Otherwise, the -static subpackages +# can be dropped + +# Win32 +%package -n mingw32-example +Summary: MinGW compiled example library for the Win32 target +BuildArch: noarch + +%description -n mingw32-example +MinGW compiled example library for the Win32 target. + +%package -n mingw32-example-static +Summary: Static version of the MinGW Win32 compiled example library +Requires: mingw32-example = %{version}-%{release} + +%description -n mingw32-example-static +Static version of the MinGW Win32 compiled example library. + +# Win64 +%package -n mingw64-example +Summary: MinGW compiled example library for the Win64 target + +%description -n mingw64-example +MinGW compiled example library for the Win64 target. +BuildArch: noarch + +%package -n mingw64-example-static +Summary: Static version of the MinGW Win64 compiled example library +Requires: mingw64-example = %{version}-%{release} + +%description -n mingw64-example-static +Static version of the MinGW Win64 compiled example library. + +%{?mingw_debug_package} +%endif + + +%prep +%autosetup -p1 -n example-%{version} + + +%build + +%define _configure ../../configure + +mkdir -p build/native +cd build/native +%configure ... +%make_build +cd ../.. + +%if %{with mingw} +%mingw_configure --enable-static --enable-shared --enable-foo +%mingw_make_build +%endif + +%install +cd build/native +%make_install + +%find_lang example +cd ../.. + +%if %{with mingw} +%mingw_make_install + +%mingw_find_lang example +%endif + +%files +%{_libdir}/libexample.so.* + +%files devel +%{_libdir}/libexample.so +%{_libdir}/pkgconfig/example.pc +%{_includedir}/example/ + +# Static subpackages are optional (as mentioned earlier) + +%if %{with mingw} +# Win32 +%files -n mingw32-example -f mingw32-example.lang +%{mingw32_bindir}/libexample-0.dll +%{mingw32_includedir}/example/ +%{mingw32_libdir}/libexample.dll.a +%{mingw32_libdir}/pkgconfig/example.pc + +%files -n mingw32-example-static +%{mingw32_libdir}/libexample.a + +# Win64 +%files -n mingw64-example -f mingw64-example.lang +%{mingw64_bindir}/libexample-0.dll +%{mingw64_includedir}/example/ +%{mingw64_libdir}/libexample.dll.a +%{mingw64_libdir}/pkgconfig/example.pc + +%files -n mingw64-example-static +%{mingw64_libdir}/libexample-0.a +%endif + +%changelog +* Sun Apr 15 2012 Erik van Pienbroek - 1.0.0-1 +- Initial release +---- + +== Example Separate Package Specfile + +The separate package specfile essentially extracts all the content within the +`+%{with mingw}+` conditionals from the previous example, and puts it into a +standalone specfile. [source, rpm-spec] ---- From 4fb2bfe23fada1ef54bcb9f0f5296f639b147c01 Mon Sep 17 00:00:00 2001 From: Fabio Valentini Date: Apr 27 2023 16:21:30 +0000 Subject: [PATCH 54/232] Rust: rust-packaging was renamed to cargo-rpm-macros --- diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc index 9672a4a..db66eff 100644 --- a/guidelines/modules/ROOT/pages/Rust.adoc +++ b/guidelines/modules/ROOT/pages/Rust.adoc @@ -100,7 +100,17 @@ but the packager SHOULD query upstream to include those missing files in their p == Package Dependencies -All Rust packages MUST have `+BuildRequires: rust-packaging+`. +All Rust packages MUST include `+BuildRequires: rust-packaging >= 21+`. + +However, if the package is for a Rust crate +whose `+Cargo.toml+` metadata uses syntax for feature dependencies +which was added with Rust 1.60, +i.e. *namespaced dependencies* (`+"dep:foo"+`) +or *weak dependency features* (`+"foo/bar"+`), +it MUST include `+BuildRequires: cargo-rpm-macros >= 24+` instead, +since support for this syntax was only added +as part of a complete rewrite of `+rust-packaging+` +that was shipped as `+cargo-rpm-macros+` version 24. === Bundled Dependencies @@ -126,7 +136,8 @@ every time the package or its bundled dependencies are updated. === Automatic Dependency Generation -`rust-packaging` automatically creates Requires and Provides +The RPM packaging machinery for Rust crates +automatically generates Requires and Provides based on cargo metadata in `+%{cargo_registry}/*/Cargo.toml+` files. The Provides generator creates: From 421f17826ce1891de6aa7078ad70e4c6d9ab02c2 Mon Sep 17 00:00:00 2001 From: Jens Petersen Date: Apr 27 2023 16:31:19 +0000 Subject: [PATCH 55/232] Haskell: add usage examples of cabal-tweak-* --- diff --git a/guidelines/modules/ROOT/pages/Haskell.adoc b/guidelines/modules/ROOT/pages/Haskell.adoc index 9936bb9..6fcd400 100644 --- a/guidelines/modules/ROOT/pages/Haskell.adoc +++ b/guidelines/modules/ROOT/pages/Haskell.adoc @@ -248,12 +248,20 @@ It should be defined at the top of Lib and BinLib packages: If needed Cabal flags for build options should be set by changing the package's `+.cabal+` file: this can usually be done with the `+cabal-tweak-flag+` script to avoid having to carry and maintain patches for this. +For example `+cabal-tweak-flag systemlib True+` might enable a flag to use a system library dependency. + `+%cabal_configure_options+` can be set to pass other options to Cabal. Modifying the `+.cabal+` file flags defaults allows packagers and tools like `+cabal-rpm+` to track actual package dependencies correctly. == Dependencies -The `+cabal-tweak-dep-ver+` script can used to change version bounds of dependencies in the package's .cabal file, and similarly `+cabal-tweak-drop-dep+` for dropping a redundant dependency (eg a compatibility dummy package). +The `+cabal-tweak-dep-ver+` script can used to change version bounds of dependencies in the package's .cabal file: `+cabal-tweak-dep-ver deppkg oldbound newbound+` + +eg: `+cabal-tweak-dep-ver base '< 4.16' '< 4.17'+` + +Similarly `+cabal-tweak-drop-dep+` for dropping a redundant dependency (eg a compatibility dummy package). + +eg: `+cabal-tweak-drop-dep mtl-compat+` Spec file build dependencies are generated by the `+cabal-rpm+` packaging tool. From 7c35b1f653a16f3b246f3d5f064e0c29758dd3d9 Mon Sep 17 00:00:00 2001 From: Frank Dana (FeRD) Date: Apr 27 2023 16:40:57 +0000 Subject: [PATCH 56/232] Alternatives: Tag specfile code blocks as rpm-spec Enables syntax highlighting --- diff --git a/guidelines/modules/ROOT/pages/Alternatives.adoc b/guidelines/modules/ROOT/pages/Alternatives.adoc index a3aba3f..a56bb9a 100644 --- a/guidelines/modules/ROOT/pages/Alternatives.adoc +++ b/guidelines/modules/ROOT/pages/Alternatives.adoc @@ -83,7 +83,8 @@ Using %ghost for this purpose allows using globs and generated file lists. Example from antlr.spec: -.... +[source, rpm-spec] +---- Requires(post): %{_sbindir}/update-alternatives Requires(postun): %{_sbindir}/update-alternatives ... @@ -104,12 +105,13 @@ fi ... %ghost %{_bindir}/antlr %{_bindir}/antlr-java -.... +---- And a more complex example of alternatives invocation from sendmail.spec, slightly edited: -.... +[source, rpm-spec] +---- Requires(post): %{_sbindir}/update-alternatives Requires(postun): %{_sbindir}/update-alternatives Requires(preun): %{_sbindir}/update-alternatives @@ -185,4 +187,4 @@ fi %{_mandir}/man5/aliases.sendmail.5.gz %attr(0755,root,root) %{_initrddir}/sendmail -.... +---- From cde06d717eab1f65ee9e339da3a7bbe97613cdc8 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Apr 27 2023 16:40:57 +0000 Subject: [PATCH 57/232] Filtering: Tag specfile code blocks as rpm-spec Enables syntax highlighting --- diff --git a/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc b/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc index f054df8..7060d99 100644 --- a/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc +++ b/guidelines/modules/ROOT/pages/AutoProvidesAndRequiresFiltering.adoc @@ -58,10 +58,11 @@ and that list contains `+libfoo.so+` you'll have to use `+libfoo\\.so+` to escape the ("`+.+`"). Example: -.... +[source, rpm-spec] +---- %global to_exclude libfoo\\.so %global __requires_exclude_from ^%{_datadir}/%{to_exclude}$ -.... +---- === Preventing files/directories from being scanned for deps (pre-scan filtering) @@ -72,14 +73,15 @@ These macros should be defined with a regular expression that matches all of the directories or files. For instance: -.... +[source, rpm-spec] +---- # Do not check any files in docdir for requires %global __requires_exclude_from ^%{_docdir}/.*$ # Do not check .so files in an application-specific library directory # or any files in the application's data directory for provides %global __provides_exclude_from ^(%{_libdir}/%{name}/.*\\.so.*|%{_datadir}/myapp/.*)$ -.... +---- Note that this macro replaces the `+%filter_provides_in+` macro from the old filtering guidelines but it does not do the same thing. @@ -110,14 +112,15 @@ matches the regular expression then it will be filtered out of the requires or provides. For example: -.... +[source, rpm-spec] +---- # This might be useful if plugins are being picked up by the dependency generator %global __provides_exclude ^libfoo-plugin\\.so.*$ # Something like this could be used to prevent excess deps from an # example python script in %doc %global __requires_exclude ^/usr/bin/python$ -.... +---- These macros serves a similar purpose to the old `+%filter_from_provides+` macro @@ -138,9 +141,10 @@ you still have the option to use the macros listed above. Perl extension modules can be filtered using this macro: -.... +[source, rpm-spec] +---- %{?perl_default_filter} -.... +---- Essentially, this filters dependencies arising from `+%doc+` files, from non-Linux-related modules, @@ -151,14 +155,15 @@ then define your filters first and call `+%perl_default_filter+` afterwards. The default filter macro will preserve the filters you previously defined. For example: -.... +[source, rpm-spec] +---- # Filter all provides from some directory %global __provides_exclude_from %{_libexecdir}/autoinst # Filter some specific requires by name %global __requires_exclude ^perl\\((autotest|basetest) # All of the default filters %{?perl_default_filter} -.... +---- == Examples @@ -173,9 +178,10 @@ and as such must not be exposed globally by RPM. To filter this out, we could use: -.... +[source, rpm-spec] +---- %global __provides_exclude_from ^%{_libdir}/purple-2/.*\\.so$ -.... +---- === Private Libraries @@ -211,13 +217,14 @@ so your regex needs to capture both. + * Add the excludes to the spec file for both requires and provides: -.... +[source, rpm-spec] +---- [...] %global _privatelibs libprivate[.]so.* %global __provides_exclude ^(%{_privatelibs})$ %global __requires_exclude ^(%{_privatelibs})$ [...] -.... +---- You can take a look at a https://lists.fedoraproject.org/pipermail/devel/2012-June/169190.html[more complex example] @@ -235,10 +242,11 @@ e.g. to ensure an arch-specific `perl-*` package won't provide or require things that it shouldn't, we could use an invocation as such: -.... +[source, rpm-spec] +---- # we don't want to provide private Perl extension libs %{?perl_default_filter} -.... +---- === `+%{_docdir}+` filtering @@ -247,11 +255,12 @@ to either "provide" or "require" anything. We can prevent this from happening by preventing anything under `+%{_docdir}+` from being scanned: -.... +[source, rpm-spec] +---- # we don't want to either provide or require anything from _docdir, per policy %global __provides_exclude_from ^%{_docdir}/.*$ %global __requires_exclude_from ^%{_docdir}/.*$ -.... +---- == Additional Information From 59c0f861c607f85cd99aa926c53e5d7320b32152 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Apr 27 2023 16:40:57 +0000 Subject: [PATCH 58/232] CMake: Tag specfile blocks as rpm-spec --- diff --git a/guidelines/modules/ROOT/pages/CMake.adoc b/guidelines/modules/ROOT/pages/CMake.adoc index b2c0602..1acccb4 100644 --- a/guidelines/modules/ROOT/pages/CMake.adoc +++ b/guidelines/modules/ROOT/pages/CMake.adoc @@ -10,9 +10,10 @@ in Fedora packages. You *MUST* add following BuildRequires: -.... +[source, rpm-spec] +---- BuildRequires: cmake -.... +---- == Available Macros @@ -71,7 +72,8 @@ It may be removed in the future. == Example Usage -.... +[source, rpm-spec] +---- %build %cmake %cmake_build @@ -81,7 +83,7 @@ It may be removed in the future. %check %ctest -.... +---- == Notes From bf1c6220b098764fa66aaaea928143f0408cec76 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Apr 27 2023 16:40:57 +0000 Subject: [PATCH 59/232] Conflicts: Tag specfile blocks as rpm-spec --- diff --git a/guidelines/modules/ROOT/pages/Conflicts.adoc b/guidelines/modules/ROOT/pages/Conflicts.adoc index d852b13..38b1179 100644 --- a/guidelines/modules/ROOT/pages/Conflicts.adoc +++ b/guidelines/modules/ROOT/pages/Conflicts.adoc @@ -60,9 +60,10 @@ above the `+Conflicts:+` field: *Example:* -.... +[source, rpm-spec] +---- Conflicts: unrar < 2.0 -.... +---- If the software links to the libraries of another package, it must use `+Requires:+` instead of `+Conflicts:+` to mark that dependency. @@ -98,19 +99,21 @@ between the files in the new package and the original package. Where the new package depends on the original package, this can be resolved with a versioned Requires: -.... +[source, rpm-spec] +---- # In the new package's spec file: Requires: original-package > EVR_BEFORE_SPLIT -.... +---- If the new package should be installable independently of whether the original package is installed, a versioned conflict is allowed: -.... +[source, rpm-spec] +---- # In the new package's spec file: Conflicts: original-package <= EVR_BEFORE_SPLIT -.... +---- In both of these cases, the new version of the original package should be updated From 51483e40e9779f95fdd2bd8a7ae8a3b0cd8af419 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Apr 27 2023 16:40:57 +0000 Subject: [PATCH 60/232] CronFiles: Tag specfile blocks as rpm-spec --- diff --git a/guidelines/modules/ROOT/pages/CronFiles.adoc b/guidelines/modules/ROOT/pages/CronFiles.adoc index b6a5609..9f62791 100644 --- a/guidelines/modules/ROOT/pages/CronFiles.adoc +++ b/guidelines/modules/ROOT/pages/CronFiles.adoc @@ -83,19 +83,20 @@ and all cron daemon packages create (and own) that directory, === Example of cron job packaging -.... +[source, rpm-spec] +---- Name: -..... +... Source1: %{name}.cron Requires: crontabs -..... +... %install -..... +... mkdir -p $RPM_BUILD_ROOT%{_sysconfdir}/cron.monthly %{__install} -p -D -m 0750 %{SOURCE1} $RPM_BUILD_ROOT%{_sysconfdir}/cron.monthly/%{name} %files %config(noreplace) %{_sysconfdir}/cron.monthly/%{name} -.... +---- From 9ea194db0c596d92ac2d347354b14dc8c55c8b93 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Apr 27 2023 16:40:57 +0000 Subject: [PATCH 61/232] TmpFiles: Tag specfile blocks as rpm-spec --- diff --git a/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc b/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc index d915937..93032b8 100644 --- a/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc +++ b/guidelines/modules/ROOT/pages/Tmpfiles.d.adoc @@ -35,7 +35,8 @@ Information on other options is available on the https://www.freedesktop.org/sof In the spec file, the packager needs to install the tmpfiles.d conf file into the `+%{_tmpfilesdir}+` directory and also make sure the directory is included in the rpm. -.... +[source, rpm-spec] +---- # For the _tmpfilesdir macro. BuildRequires: systemd-rpm-macros @@ -62,7 +63,7 @@ chmod 0644 %{buildroot}/run/%{name}.pid %dir /run/%{name}/ %verify(not size mtime md5) /run/%{name}.pid %{_tmpfilesdir}/%{name}.conf -.... +---- `+%{_tmpfilesdir}+` expands to `+%{_prefix}/lib/tmpfiles.d+` which is the location that the package's default tmpfile creation scripts should install into. `+%{_tmpfilesdir}/%{name}.conf+` is *not* marked as a `+%config+` file because it is not supposed to be edited by administrators. Administrators can override the package's `+%{name}.conf+` by placing an identically named file in `+/etc/tmpfiles.d/+`, but this should very rarely be needed. From 67b6169de975be0fa5a69dcfe4069889bff2259d Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: May 08 2023 09:15:00 +0000 Subject: [PATCH 62/232] Adjust guidelines for %autorelease+%autochangelog See https://fedoraproject.org/wiki/Changes/Rpmautospec_by_Default The general approach is the the previous recommendations are described with "may" and moved to the end or to a separate page. Use of rpmautospec is shown briefly, but with enough information for normal packaging workflows. Links are provided to the rpmautospec docs in case packagers need more information. --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 2e11852..49bfab1 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -14,6 +14,7 @@ * xref:Initial_Service_Setup.adoc[Initial Service Setup] * xref:Langpacks.adoc[Language Packs] * xref:LicensingGuidelines.adoc[Licensing] +* xref:manual-changelog.adoc[Manual Changelog] * xref:Naming.adoc[Naming] * xref:PatchUpstreamStatus.adoc[Patch Status] * xref:Per-Product_Configuration.adoc[Per-Product Configuration] diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index 4fc178a..b4e7b7e 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -9,6 +9,9 @@ The overriding goal is to provide sequences of packages which are treated as updates by RPM's version comparison algorithm while accommodating varied and often inconsistent upstream versioning schemes. +The `+Version:+` field contains the upstream project version, +and the `+Release:+` field specifies the downstream release number. + == Some definitions Note that upstreams may each have their own terminology @@ -51,7 +54,7 @@ non-sorting version sequence:: from RPM's implementation then simply using upstream's versions directly will result in updates which don't actually update any packages. -== Epoch: tag +== `+Epoch+` tag The `+Epoch:+` tag provides the most significant input to RPM's version comparison function. If present, it **must** consist of a positive integer. @@ -60,6 +63,26 @@ when necessary to avoid ordering issues. The `+Epoch:+` tag, once introduced to a package, **must never** be removed or decreased. +== `+Release+` tag + +The `+Release:+` **should** be managed automatically using the `+%autorelease+` macro: +[source, rpm-spec] +---- +Release: %autorelease +---- + +As described in +https://docs.pagure.org/fedora-infra.rpmautospec/autorelease.html[%autorelease documentation], +the build machinery will +replace the macro with the number of builds since the last commit that changed the `+Version+` field, +suffixed with the `%{?dist}` tag. +This means that a commit that changes `+Version+` automatically gets `Release: 1%{?dist}`, +and commits after that get `Release: 2%{?dist}`, `Release: 3%{?dist}`, and so on. + +Alternatively, the `+Release:+` field **may** be updated manually. +See xref:Versioning.adoc#traditional-versioning[Traditional versioning +with part of the upstream version information in the release field]. + == Simple versioning Most upstream versioning schemes are "simple"; @@ -79,12 +102,8 @@ and the vast majority of software projects use something which works like this. To package *release versions* of software using this versioning scheme: -* Use the upstream verbatim in the `+Version:+` tag. +* Use the upstream project version verbatim in the `+Version:+` tag. Don't trim leading zeroes. -* Use a `+Release:+` tag starting with 1 (never 0). - Append the xref:DistTag.adoc[Dist Tag]. - Increment the release (by 1) for each update you make. - Reset to 1 whenever you change `+Version:+`. == Complex versioning @@ -105,6 +124,9 @@ in a particular situation: * More than one of the above may apply (lucky you). Follow all of the relevant recommendations below together. +This subsection describes how to modify the upstream project version to be suitable for the `+Version+` field. +Use of `Release: +%autorelease+` remains unchanged. + === Handling non-sorting versions with tilde, dot, and caret The tilde symbol ('`+~+`') is used before a version component which must sort *earlier* than any non-tilde component. @@ -177,6 +199,7 @@ you **must** use `+Version: 0+`. "`+0+`" sorts lower than any other possible value that upstream might choose. If upstream does choose to release "version 0", then just set `+Release:+` higher than the previous value. +(When `%autorelease` is used, this happens automatically.) === Upstream uses invalid characters in the version @@ -241,118 +264,136 @@ $ rpmdev-vercmp 2~almost^post 2.0.1 [%header] |=== -|Upstream| Version field | Release field | Explanation - -|1.0 |1.0 | 1%{?dist} | The first release. - -|1.1 |1.1 | 1%{?dist} | An upstream update. +|Upstream version | Version tag | Explanation -|1.1 |1.1 | 2%{?dist} | You made a change to the package but the upstream version didn't change. +|1.0 |1.0 | The first release. -|1.2 |1.2 | 1%{?dist} | The upstream version changed, so Release: goes back to 1. +|1.1 |1.1 | An upstream update. -|1.2.1 |1.2.1 |1%{?dist} | Extra levels of versioning are OK… +|1.2.1 |1.2.1 | Another upstream update. Extra levels of versioning are OK… -|1.3 |1.3 |1%{?dist} | …they can come and go without problems. +|1.3 |1.3 | …they can come and go without problems. |=== +In this case the full N-V-R could be e.g. `pkg-1.2.1-1.fc{CURRENTVER}` (immediately after an update) +or `pkg-1.2.1-5.fc{CURRENTVER}` (after downstream rebuilds with the same upstream version). + [%header] |=== -|Upstream| Version field | Release field | Explanation +|Upstream version | Version tag | Explanation -| 5.2 | 5.2 | 1%{?dist} | +| 5.2 | 5.2 | Upstream release. -| 5.2a | 5.2a | 1%{?dist} | Upstream introduced a letter to indicate a patch release. You trust upstream to use letters in alphabetical order, so it's OK to use the version as is. +| 5.2a | 5.2a | Upstream introduced a letter to indicate a patch release. You trust upstream to use letters in alphabetical order, so it's OK to use the version as is. -| 5.2b | 5.2b | 1%{?dist} | Another patch release after 5.2 - this is not a beta. +| 5.2b | 5.2b | Another patch release after 5.2 — this is not a beta. -| 5.2b.1 | 5.2b.1 | 1%{?dist} | Even this is OK as long as the sequence increases. +| 5.2b.1 | 5.2b.1 | Even this is OK as long as the sequence increases. -| 5.3 | 5.3 | 1%{?dist} | +| 5.3 | 5.3 | Another upstream release. |=== +In this case the full N-V-R could be e.g. `pkg-5.2b.1-1.fc{CURRENTVER}`. + ==== Complex versioning with a reasonable upstream [%header] |=== -|Upstream version | Full package NEVRA | Notes +|Upstream version | Version tag | Notes -| 1.0.0-rc1 | `+pkg-1.0.0~rc1-1%{?dist}+` | first prerelease +| 1.0.0-rc1 | `+1.0.0~rc1+` | first prerelease -| 1.0.0-rc2 | `+pkg-1.0.0~rc2-1%{?dist}+` | second prerelease +| 1.0.0-rc2 | `+1.0.0~rc2+` | second prerelease -| 1.0.0 | `+pkg-1.0.0-1%{?dist}+` | release +| 1.0.0 | `+1.0.0+` | release -| 1.0.1 | `+pkg-1.0.1-1%{?dist}+` | bugfix release +| 1.0.1 | `+1.0.1+` | bugfix release -| 1.0.1-security1 | `+pkg-1.0.1.security1-1%{?dist}+` | security bufix release +| 1.0.1-security1 | `+pkg-1.0.1.security1+` | security bufix release |=== +In this case the full N-V-R could be e.g. `pkg-1.0.0~rc2-42.fc{CURRENTVER}` (if many rebuilds were done). + ==== Complex versioning with non-sorting upstream post-release versions [%header] |=== -|Upstream version | Full package NEVRA | Notes - -| 1.1.0~BETA | `+pkg-1.1.0~BETA-1%{?dist}+` | this is a prerelease, first beta +|Upstream version | Version tag | Notes -| 1.1.0~BETA1 | `+pkg-1.1.0~BETA1-1%{?dist}+` | this is a prerelease, second beta +| 1.1.0~BETA | `+1.1.0~BETA+` | this is a prerelease, first beta -| 1.1.0~BETA2 | `+pkg-1.1.0~BETA2-1%{?dist}+` | this is a prerelease, third beta +| 1.1.0~BETA1 | `+1.1.0~BETA1+` | this is a prerelease, second beta -| 1.1.0~CR1 | `+pkg-1.1.0~CR1-1%{?dist}+` | this is a prerelease, candidate release 1 +| 1.1.0~BETA2 | `+1.1.0~BETA2+` | this is a prerelease, third beta -| 1.1.0~CR2 | `+pkg-1.1.0~CR2-1%{?dist}+` | this is a prerelease, candidate release 2 +| 1.1.0~CR1 | `+1.1.0~CR1+` | this is a prerelease, candidate release 1 -| | `+pkg-1.1.0~CR2-2%{?dist}+` | this is a prerelease, candidate release 2, second build +| 1.1.0~CR2 | `+1.1.0~CR2+` | this is a prerelease, candidate release 2 -| 1.1.0-1% | `+pkg-1.1.0-1%{?dist}+` | final release +| 1.1.0-1% | `+1.1.0+` | final release -| 1.1.0-GA1 | `+pkg-1.1.0.20201001.GA1-1%{?dist}+` | post release, GA1 +| 1.1.0-GA1 | `+1.1.0.20201001.GA1+` | post release, GA1 -| 1.1.0-CP1 | `+pkg-1.1.0.20201011.CP1-1%{?dist}+` | post release, CP1, after GA1, does not sort properly +| 1.1.0-CP1 | `+1.1.0.20201011.CP1+` | post release, CP1, after GA1, does not sort properly -| 1.1.0-CP2 | `+pkg-1.1.0.20201101.CP2-1%{?dist}+` | post release, CP2, after CP1 +| 1.1.0-CP2 | `+1.1.0.20201101.CP2+` | post release, CP2, after CP1 -| 1.1.0-SP1 | `+pkg-1.1.0.20210101.SP1-1%{?dist}+` | post release, SP1, after CP2 +| 1.1.0-SP1 | `+1.1.0.20210101.SP1+` | post release, SP1, after CP2 -| 1.1.0-SP1-CP1 | `+pkg-1.1.0.20210105.SP1_CP1-1%{?dist}+` | post release, SP1_CP1, after SP1 +| 1.1.0-SP1-CP1 | `+1.1.0.20210105.SP1_CP1+` | post release, SP1_CP1, after SP1 |=== +In this case the full N-V-R could be e.g. `pkg-1.1.0.20210105.SP1_CP1-1.fc{CURRENTVER}`. ==== Complex versioning with a pre- and post-release snapshots [%header] |=== -|Upstream version | Full package NEVRA | Notes +|Upstream version | Version | Notes -| 1.0.0-rc1 | `+pkg-1.0.0~rc1-1%{?dist}+` | First prerelease +| 1.0.0-rc1 | `+1.0.0~rc1+` | First prerelease -| 1.0.0-rc2 | `+pkg-1.0.0~rc2-1%{?dist}+` | Second prerelease +| 1.0.0-rc2 | `+1.0.0~rc2+` | Second prerelease -| git commit `f00fabd` | `+pkg-1.0.0~rc2^20210101gf00fabd-1%{?dist}+` | Post-prerelease snapshot +| git commit `f00fabd` | `+1.0.0~rc2^20210101gf00fabd+` | Post-prerelease snapshot -| 1.0.0 | `+pkg-1.0.0-1%{?dist}+` | A release +| 1.0.0 | `+1.0.0+` | A release -| | `+pkg-1.0.0-2%{?dist}+` | A rebuild from the same sources +| 1.0.1 | `+1.0.1+` | A bugfix release -| 1.0.1 | `+pkg-1.0.1-1%{?dist}+` | A bugfix release +| git commit `bbbccc0` | `+1.0.1^20210203gbbbccc0+` or `+pkg-1.0.1^1.gbbbccc0+` | A snapshot -| git commit `bbbccc0` | `+pkg-1.0.1^20210203gbbbccc0-1%{?dist}+` or `+pkg-1.0.1^1.gbbbccc0-1%{?dist}+` | A snapshot +| 1.0.1-security1 | `+1.0.1.security1+` | A security bufix release. From past history we know that the bugfix releases will have sortable versions. If not, we could use '`+.security1+`' instead. -| 1.0.1-security1 | `+pkg-1.0.1.security1-1%{?dist}+` | A security bufix release. From past history we know that the bugfix releases will have sortable versions. If not, we could use '`+.security1+`' instead. - -| git commit `abc0202` | `+pkg-1.0.1.security1^20210301gabc0202-1%{?dist}+` or `+pkg-1.0.1.security1^1.gabc0202-1%{?dist}+` | Another snapshot +| git commit `abc0202` | `+1.0.1.security1^20210301gabc0202+` or `+pkg-1.0.1.security1^1.gabc0202+` | Another snapshot |=== +In this case the full N-V-R could be e.g. `pkg-1.0.1.security1^20210301gabc0202-1.fc{CURRENTVER}`. + +== Only an old branch needs a change + +Sometimes, an older branch needs a fix, but the newer branches are fine. +For example, both F{PREVVER} and F{CURRENTVER} are built from the same dist-git commit, +and only F{PREVVER} needs a fix. +If only F{PREVVER} was changed, its `Release` would increase +and thus the E-V-R for F{PREVVER} would sort higher than E-V-R in F{CURRENTVER}. +To avoid this situation, rebuild the package also in the later branches, +possibly with just an empty commit to make `%autorelease` bump the release. + +If the package does not use `%autorelease`, +you **may** rebuild just the older branch, +see <`>>. -== Traditional versioning with part of the upstream version information in the release field +[#traditional-versioning] +== Traditional versioning with part of the upstream version information in the Release field The method described in this section is deprecated, but **may** be used. As mentioned in the <> section above, this method is recommended for packages with complex versioning when supporting RHEL7 and other systems with old rpm versions. +In this method, `+%autorelease+` is not used, and the `Release` field must be managed manually. + This method for dealing with most pre- and post-release versions and unsortable versions involves potentially removing some information from the `+Version:+` tag while imposing additional structure onto the `+Release:+` tag. @@ -382,7 +423,7 @@ in the use of `++` or `++`, and in most situations `++` won't be used at all. Simply do not include those which you don't have. -Note that the Dist tag is supplied by other portions of the system +Note that the dist tag is supplied by other portions of the system and may in some circumstances contain additional structure, including tildes. As this is not under the control of the packager, @@ -454,6 +495,17 @@ and increasing for each revision of the package. Release and post-release versions **must** use a `+Release:+` tag greater than or equal to 1. +=== Rebuilds in older branches using `` + +In the situation described in <>, +you **may** adjust the `+Release+` by appending a number *after* the dist tag, +creating a E-V-R for F{CURRENTVER} that still compares lower than the one in F{NEXTVER}. +Set `++` to an in integer beginning with '1' +and increase it by one for each minor bump you need to do. +Remove `++` once you are able +to increase the package release normally +without introducing ordering issues. + === Examples Examples of many possible versioning scenarios of traditional versioning @@ -461,29 +513,6 @@ are available from https://fedoraproject.org/wiki/Package_Versioning_Examples[Package Versioning Examples]. - - - -== You need to change an old branch without rebuilding the others - -Sometimes, you may find yourself in a situation where an older branch needs a fix, -but the newer branches are fine. -For example, if a package has a version-release of `+1.0-1%{?dist}+` -in F{CURRENTVER} and F{NEXTVER}, -and only F{CURRENTVER} needs a fix. -Normally, you would need to bump the release in each of the branches -to ensure that F{CURRENTVER} < F{NEXTVER}, -but that is a waste of time and energy for the newer branches -which do not need to be touched. - -In this case, you **may** set `++` -to an in integer beginning with '1' -and increasing by one for each minor bump you need to do. -Remove `++` once you are able -to increase the package release normally -without introducing ordering issues. - - == Rawhide is allowed to lag temporarily A package **may** temporarily have a lower EVR in Rawhide diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 09f6e51..0d10914 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1096,133 +1096,101 @@ 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. +The changelog describes the changes to the package that are relevant +to the users of the package. This includes new upstream versions, important +changes to how the package is built, rebuilds, and other changes affecting the outcome. +Changes which are only relevant to packagers should not be mentioned in the +changelog. This includes spec file cleanups, build error fixes or workarounds, +and other changes which don't have an effect on content of the binary packages. -If a particular change is related to a Bugzilla bug, -include the bug ID in the changelog entry for easy reference, e.g. +The changelog **should** be generated automatically from git commit logs +using the `+%autochangelog+` macro: [source, rpm-spec] ---- %changelog -* Wed Jun 14 2003 Joe Packager - 1.0-2 -- Added README file (#42). +%autochangelog ---- -You must use one of the following formats: +The commit subject (the first line of the commit message) +and optionally some additional lines +are used to generate the changelog text. +The commit author name and email address and the commit timestamp +are also used in changelog entry. -[source, rpm-spec] ----- -%changelog -* Fri Jun 23 2006 Jesse Keating - 0.6-4 -- And fix the link syntax. ----- +The text in the the commit message which will become part of the changelog +should should provide a brief summary of the changes relevant for the user. +The commit message may contain additional information that is relevant +to packagers. -[source, rpm-spec] ----- -%changelog -* Fri Jun 23 2006 Jesse Keating 0.6-4 -- And fix the link syntax. ----- +If a particular change is related to a Bugzilla bug, +include the bug ID in the changelog entry for easy reference, e.g. -[source, rpm-spec] +[source] ---- -%changelog -* Fri Jun 23 2006 Jesse Keating -- 0.6-4 -- And fix the link syntax. +Add README file (rhbz#1000042) ---- -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. +If a particular commit fixes a CVE, this information should be included too. + 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 +They must never simply contain an entire copy of the source CHANGELOG entries. +Links to upstream NEWS files or 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 +See https://docs.pagure.org/fedora-infra.rpmautospec/autochangelog.html[autochangelog documentation] +for the details of how the changelog is generated from git commit messages, +and how to create multi-line entries or skip entries for certain commits. -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: +Packagers **may** alternatively use a manual changelog instead of the `+%autochangelog+` macro. +This is described in xref:manual-changelog.adoc[Manual Changelog]. -==== Updating and replacing the existing date line +=== Example -In this situation, you have added this changelog entry, -but have not built the package yet: +The packager updates package to version 1.0 and creates a commit -[source, rpm-spec] ----- -%changelog -* 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: - -[source, rpm-spec] ----- -%changelog -* Nov 13 2010 Toshio Kuratomi - 1.0-1 -- Fix spelling errors in package description -- Add a patch to fix compilation problems on F15 +[console] ---- +$ git show +commit 0000000000001234567890ABCDEF000000000000 +Author: Joe Packager +Date: Wed Jun 14 2003 -Please remember that this is only acceptable if 1.0-1 has not yet been built. + Version 1.0 -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 <>. + ... (rhbz#1000024) + - Also fixes the slowdown reported in rhbz#1000025 + - Upstream changelog: https://example.com/package/NEWS.html#v1.0 -==== Repeat the old version release with a new entry + Whitespace in the spec file has been cleaned up. -In this situation, you have added this changelog entry, -but have not built the package yet: - -[source, rpm-spec] ----- -%changelog -* Nov 12 2010 Toshio Kuratomi - 1.0-1 -- Fix spelling errors in package description +diff --git package.spec package.spec +index 5c77064c03..efcd53a61c 100644 +--- package.spec ++++ package.spec +@@ -1,5 +1,5 @@ + Name: package +-Version: 0.1 ++Version: 0.2 + Release: %autorelease +... ---- -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: +When the package is built, an appropriate changelog entry will be generated. +It can be previewed with `rpmautospec generate-chagengelog`: -[source, rpm-spec] +[console] ---- -%changelog -* Nov 13 2010 Toshio Kuratomi - 1.0-1 -- Add a patch to fix compilation problems on F15 - -* Nov 12 2010 Toshio Kuratomi - 1.0-1 -- Fix spelling errors in package description +$ rpmautospec generate-changelog +* Wed Jun 14 2003 Joe Packager - 0.2-1 +- Version 1.0 (rhbz#1000024) +- Also fixes the slowdown reported in rhbz#1000025 +- Upstream changelog: https://example.com/package/NEWS.html#v1.0 ---- -Please remember that this is only acceptable if 1.0-1 has not yet been built. +Note that the sentence about whitespace is not included in the changelog. -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 diff --git a/guidelines/modules/ROOT/pages/manual-changelog.adoc b/guidelines/modules/ROOT/pages/manual-changelog.adoc new file mode 100644 index 0000000..45f7def --- /dev/null +++ b/guidelines/modules/ROOT/pages/manual-changelog.adoc @@ -0,0 +1,119 @@ += Manual Changelog + +This describes the traditional method of managing changelogs that provides a +separate text log of user-visible changes independently of the git commit messages. +This is an alternative for the recommended method with `+%autochangelog+` +described in xref:index.adoc#changelogs[Changelogs]. + +_Every time_ you make changes, that is, +whenever you increment the E-V-R of a package, +add a changelog entry in the `+%changelog+` section. + +Changelog entries should provide a brief summary +of the changes done to the package between releases. +They must never simply contain an entire copy of the source `CHANGELOG` entries. +The same general rules should be followed as described in +xref:index.adoc#changelogs[Changelogs]. + +You must use one of the following formats: + +[source, rpm-spec] +---- +%changelog +* Fri Jun 23 2006 Jesse Keating - 0.6-4 +- And fix the link syntax. +---- + +[source, rpm-spec] +---- +%changelog +* Fri Jun 23 2006 Jesse Keating 0.6-4 +- And fix the link syntax. +---- + +[source, rpm-spec] +---- +%changelog +* Fri Jun 23 2006 Jesse Keating +- 0.6-4 +- And fix the link syntax. +---- + +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: + +=== Updating and replacing the existing date line + +In this situation, you have added this changelog entry, +but have not built the package yet: + +[source, rpm-spec] +---- +%changelog +* 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: + +[source, rpm-spec] +---- +%changelog +* Nov 13 2010 Toshio Kuratomi - 1.0-1 +- Fix spelling errors in package description +- Add a patch to fix compilation problems on F15 +---- + +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 +xref:index.adoc#changelogs[Changelogs]. + +=== 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: + +[source, rpm-spec] +---- +%changelog +* 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: + +[source, rpm-spec] +---- +%changelog +* Nov 13 2010 Toshio Kuratomi - 1.0-1 +- Add a patch to fix compilation problems on F15 + +* Nov 12 2010 Toshio Kuratomi - 1.0-1 +- Fix spelling errors in package description +---- + +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 +xref:index.adoc#changelogs[Changelogs]. From 0cd555fc6e4eb3343297fa7223dd71188a8dc1bb Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: May 08 2023 09:15:00 +0000 Subject: [PATCH 63/232] Adjust "Renaming or replacing" for rpmautospec When rpmautospec is used, %{dist} is not directly visible to the maintainer, so adjust the text to use ".fcNN" instead, which is what the maintainer will see when %autorelease is expanded. With this adjustment, the text should apply to both %autorelease and traditional release handling. Also, add a note to point the maintainer to 'rpmautospec calculate-release'. Change '<=' to '<' in one more place: '<=' is just confusing, because equality generally cannot be achieved because of %{dist} and the operator was changed to '<' in most places, but apparently forgotten here. Addresses https://pagure.io/fedora-infra/rpmautospec/issue/225. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 0d10914..b004ae3 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2923,7 +2923,7 @@ 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 +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: @@ -2952,10 +2952,14 @@ 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. +remember that it needs to be higher than the previous `Release:`, +including the `+%{?dist}+` suffix. +Example: if the package previously had the release tag of `+-4.fcNN+`, +the release specified in $obsEVR should be at least 5. + +NOTE: If the replaced package uses `rpmautospec`, +either look at the built package (e.g. in koji) to find the actual release tag of the latest build, +or use `+rpmautospec calculate-release+` to calculate just the release number. If retired packages need to be removed from end user machines because they cause dependency issues which interfere with upgrades @@ -2972,14 +2976,15 @@ 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. +and the last foo package release being `+foo-1.0-3.fcNN+` with `+Epoch: 2+`. The following should be added to bar (and similarly for all subpackages as applicable): [source, rpm-spec] ---- 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} +# Important: We set the Obsoletes release to 4 to be higher than the last build of foo +Obsoletes: foo < 2:1.0-4 ---- Explicit `+Provides:+` need to be aware of whether From 3db83e48d5bd7d52a7f8a28601895c61f67048c2 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: May 08 2023 09:15:00 +0000 Subject: [PATCH 64/232] Drop discussion of builds in older branches with %autorelease There is a disagreement how to proceed with "rebuilds in older branches": - rpmautospec does not really support adding a minor bump. ('%{autorelease -b 0}.' sets the Release correctly, but %autochangelog is generated as if '-b' was not set, so the release fields disagree.) - But even if it could be made to work, it is quite inconvenient, so it's not clear if is worth the trouble. (In my opinion — no.) - We could either ask people to rebuild, - Or we could remove the requirement to have a higher version-release in later releases, - Or we could tweak that rul to only require a higher version, but allow a lower release. If we do this, we might want to adjust tooling to only warn about version downgrades, but silently allow release downgrades. A quick check using 'dnf repoquery' shows that there are packages using minorbumps, but it also seems that the majority are doing that in error: $ dnf repoquery --releasever=37 --qf '%{name}-%{version}-%{release}' \ '--disablerepo=*' '--enablerepo=updates-source' '--enablerepo=fedora-source' \ --arch=src | rg 'fc37.\d' | wc -l 96 $ dnf repoquery --releasever=37 --qf '%{name}-%{version}-%{release}' \ '--disablerepo=*' '--enablerepo=updates-source' '--enablerepo=fedora-source' \ --arch=src | rg 'fc38.\d' | wc -l 83 Considering that F38 hasn't been released yet, those 83 packages should not be using minorbumps. So there's probably ≤13 packages in F37 using a minorbump as intended. So let's remove this subsection for now, so that the other part of the changes can be merged, and discuss how to handle this case separately. --- diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index b4e7b7e..5ed52c0 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -370,20 +370,6 @@ In this case the full N-V-R could be e.g. `pkg-1.1.0.20210105.SP1_CP1-1.fc{CURRE In this case the full N-V-R could be e.g. `pkg-1.0.1.security1^20210301gabc0202-1.fc{CURRENTVER}`. -== Only an old branch needs a change - -Sometimes, an older branch needs a fix, but the newer branches are fine. -For example, both F{PREVVER} and F{CURRENTVER} are built from the same dist-git commit, -and only F{PREVVER} needs a fix. -If only F{PREVVER} was changed, its `Release` would increase -and thus the E-V-R for F{PREVVER} would sort higher than E-V-R in F{CURRENTVER}. -To avoid this situation, rebuild the package also in the later branches, -possibly with just an empty commit to make `%autorelease` bump the release. - -If the package does not use `%autorelease`, -you **may** rebuild just the older branch, -see <`>>. - [#traditional-versioning] == Traditional versioning with part of the upstream version information in the Release field From edc1b47de720ef979fed9c644159ae986aee42d1 Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: May 19 2023 12:46:38 +0000 Subject: [PATCH 65/232] UsersAndGroups: Use %sysusers_requires_compat to specify Requires(pre) ... for %sysusers_create_compat. Fallout from 6d066acbb16452e1befc2f384d2f14bab9f54361 https://pagure.io/packaging-committee/pull-request/1203 --- diff --git a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc index a756bed..f8195ce 100644 --- a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc +++ b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc @@ -145,11 +145,14 @@ u munge - "Runs Uid 'N' Gid Emporium" /run/munge /sbin/nologin ``` In the specfile, add a BuildRequires for systemd-rpm-macros, install the sysusers file, - and use the `%sysusers_create_compat` macro to consume it in the `%pre` section -(in this example the sysusers config file is `Source3` of the specfile): + use the `%sysusers_create_compat` macro to consume it in the `%pre` section +(in this example the sysusers config file is `Source3` of the specfile), and the +`%sysusers_requires_compat` macro to specify the runtime dependencies for the `%pre` +section: ``` [...] BuildRequires: systemd-rpm-macros +%{?sysusers_requires_compat} [...] %install From 4431afd0efbdb13a93a51d1f6db1466556719434 Mon Sep 17 00:00:00 2001 From: Miro Hrončok Date: May 22 2023 12:54:27 +0000 Subject: [PATCH 66/232] Fix the license tag of the python-pello example --- diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc index 28df2a6..f8b98f3 100644 --- a/guidelines/modules/ROOT/pages/Python.adoc +++ b/guidelines/modules/ROOT/pages/Python.adoc @@ -1222,11 +1222,11 @@ the extra is Recommended from the main package. [source,spec] ---- Name: python-pello -Version: 1.0.3 +Version: 1.0.4 Release: 1%{?dist} Summary: Example Python library -License: MIT +License: MIT-0 URL: https://github.com/fedora-python/Pello Source: %{url}/archive/v%{version}/Pello-%{version}.tar.gz From 1d19afc2a790c21e62d37abe1cbdc15c34c9489b Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 01:52:14 +0000 Subject: [PATCH 67/232] Per-Product Configuration: semantic newlines --- diff --git a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc index 6b94199..62de955 100644 --- a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc +++ b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc @@ -1,32 +1,72 @@ -In the Fedora.next world, we 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. The goal of this document is to set out the guidelines for creating per-Product configuration defaults. - -We want to ensure that all packages have sensible defaults for whichever Product on which they are installed, while also avoiding situations where users would have some packages installed with one Product's defaults and some packages with another. +In the Fedora.next world, +we 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. +The goal of this document +is to set out the guidelines for creating per-Product configuration defaults. + +We want to ensure that all packages have sensible defaults +for whichever Product on which they are installed, +while also avoiding situations where users would have some packages installed +with one Product's defaults and some packages with another. == Per-product Configuration Packaging === Requirements -* All packages MUST have a global default configuration. This configuration will be used whenever a Product-specific default configuration is not required. (For example, if a non-Product install is in use or only Fedora Cloud has a custom configuration and Fedora Workstation was installed). -* Any package that requires a per-product default configuration MUST provide all alternate configuration files in the same package. -* Any package that requires a configuration that differs between Products MUST obtain permission from that Product's Working Group before packaging it. +* All packages MUST have a global default configuration. + This configuration will be used + whenever a Product-specific default configuration is not required. + (For example, if a non-Product install is in use + or only Fedora Cloud has a custom configuration + and Fedora Workstation was installed). +* Any package that requires a per-product default configuration + MUST provide all alternate configuration files in the same package. +* Any package that requires a configuration that differs between Products + MUST obtain permission from that Product's Working Group before packaging it. === Global Default Configuration -* The global default configuration MUST be provided by the package that requires it. -* The global default configuration MUST be named based on the package's normal naming scheme, with the main part of the name being suffixed by -default. For example, if the package normally uses foo.conf, then the global default configuration MUST be named foo-default.conf +* The global default configuration + MUST be provided by the package that requires it. +* The global default configuration + MUST be named based on the package's normal naming scheme, + with the main part of the name being suffixed by -default. + For example, if the package normally uses foo.conf, + then the global default configuration MUST be named foo-default.conf === Per-Product Default Configuration -* For each Product requiring a unique default configuration, the packager MUST provide a copy of the default configuration file, modified as appropriate for the specific product. -* The product-specific configuration file MUST be named based on the package's normal naming scheme, with the main part of the name being suffixed by a dash followed by the name of the product. For example, if the package normally uses `+foo.conf+`, then the Server version MUST be named `+foo-server.conf+`. -* If the configuration will be symlinked in place, the product-specific configuration file MUST be located in an appropriate part of the /etc hierarchy. The divergent config file MUST be specified as `+%config(noreplace)+` in %files as per the usual /etc packaging guidelines. -* If the configuration will be copied in place, the product-specific configuration file MUST be located in an appropriate part of the /usr/share hierarchy. The divergent config file MUST be specified as a normal file in the %files section. +* For each Product requiring a unique default configuration, + the packager MUST provide a copy of the default configuration file, + modified as appropriate for the specific product. +* The product-specific configuration file + MUST be named based on the package's normal naming scheme, + with the main part of the name being suffixed by a dash + followed by the name of the product. + For example, if the package normally uses `+foo.conf+`, + then the Server version MUST be named `+foo-server.conf+`. +* If the configuration will be symlinked in place, + the product-specific configuration file + MUST be located in an appropriate part of the /etc hierarchy. + The divergent config file + MUST be specified as `+%config(noreplace)+` in %files + as per the usual /etc packaging guidelines. +* If the configuration will be copied in place, + the product-specific configuration file + MUST be located in an appropriate part of the /usr/share hierarchy. + The divergent config file + MUST be specified as a normal file in the %files section. === Applying Configuration -In order to apply the configuration, the packager MUST implement a mechanism in the `+%posttrans+` section of the specfile that behaves as follows: +In order to apply the configuration, +the packager MUST implement a mechanism +in the `+%posttrans+` section of the specfile that behaves as follows: -* It MUST first check whether the final config file already exists. If so, the script MUST make no changes. +* It MUST first check whether the final config file already exists. + If so, the script MUST make no changes. .... %posttrans @@ -35,7 +75,15 @@ if [ ! -e %{_sysconfdir}/foo/foo.conf ]; then fi .... -* Then it MUST use the value of the Fedora `+VARIANT_ID+` to symlink or copy one of the divergent config files (or the default) to the final config file location. It will get this value by importing the contents of /etc/os-release as shell values. Known values of this field at the time of this writing are "atomichost", "cloud", "server" and "workstation". For more detail, see https://www.freedesktop.org/software/systemd/man/os-release.html#VARIANT_ID=[the os-release(5) man page]. +* Then it MUST use the value of the Fedora `+VARIANT_ID+` + to symlink or copy one of the divergent config files + (or the default) to the final config file location. + It will get this value + by importing the contents of /etc/os-release as shell values. + Known values of this field at the time of this writing are + "atomichost", "cloud", "server" and "workstation". + For more detail, see + https://www.freedesktop.org/software/systemd/man/os-release.html#VARIANT_ID=[the os-release(5) man page]. .... . /etc/os-release || : @@ -49,13 +97,17 @@ fi esac .... -* Lastly, the final config file location MUST be listed in the %files section with %ghost: +* Lastly, the final config file location + MUST be listed in the %files section with %ghost: .... %ghost %config(noreplace) %{_sysconfdir}/foo/foo.conf .... -* For tracking purposes, the package providing the various configuration files MUST also contain a virtual Provides: for each variant configuration that may be applied: +* For tracking purposes, + the package providing the various configuration files + MUST also contain a virtual Provides: + for each variant configuration that may be applied: .... Provides: variant_config(Atomic.host) @@ -66,7 +118,10 @@ Provides: variant_config(Workstation) === Example (firewalld) -We will assume for the sake of demonstration that firewalld will need a custom configuration for Fedora Server and Fedora Workstation, but that Fedora Cloud will not require any changes from the global default. +We will assume for the sake of demonstration +that firewalld will need a custom configuration +for Fedora Server and Fedora Workstation, +but that Fedora Cloud will not require any changes from the global default. .... ... From 20c714a93ee5dee2501fedb42b3f1cb8a7b1e603 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 01:52:14 +0000 Subject: [PATCH 68/232] Per-Product Configuration: syntax/markup fixes - Set a title for the page (previously loaded as "Untitled") - Enable syntax highlighting in specfile code blocks - backslash-continue & wrap very long specfile lines - Add inline code-literal fencing around body text uses of filesystem paths and filenames, specfile directives, etc. - Attach code blocks to bulleted list items as child elements, where appropriate --- diff --git a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc index 62de955..1be3b02 100644 --- a/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc +++ b/guidelines/modules/ROOT/pages/Per-Product_Configuration.adoc @@ -1,3 +1,5 @@ += Per-product Configuration Packaging + In the Fedora.next world, we 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 @@ -11,9 +13,7 @@ for whichever Product on which they are installed, while also avoiding situations where users would have some packages installed with one Product's defaults and some packages with another. -== Per-product Configuration Packaging - -=== Requirements +== Requirements * All packages MUST have a global default configuration. This configuration will be used @@ -26,17 +26,18 @@ with one Product's defaults and some packages with another. * Any package that requires a configuration that differs between Products MUST obtain permission from that Product's Working Group before packaging it. -=== Global Default Configuration +== Global Default Configuration * The global default configuration MUST be provided by the package that requires it. * The global default configuration MUST be named based on the package's normal naming scheme, with the main part of the name being suffixed by -default. - For example, if the package normally uses foo.conf, - then the global default configuration MUST be named foo-default.conf + For example, if the package normally uses `+foo.conf+`, + then the global default configuration + MUST be named `+foo-default.conf+`. -=== Per-Product Default Configuration +== Per-Product Default Configuration * For each Product requiring a unique default configuration, the packager MUST provide a copy of the default configuration file, @@ -49,17 +50,17 @@ with one Product's defaults and some packages with another. then the Server version MUST be named `+foo-server.conf+`. * If the configuration will be symlinked in place, the product-specific configuration file - MUST be located in an appropriate part of the /etc hierarchy. + MUST be located in an appropriate part of the `+/etc+` hierarchy. The divergent config file - MUST be specified as `+%config(noreplace)+` in %files - as per the usual /etc packaging guidelines. + MUST be specified as `+%config(noreplace)+` in `+%files+` + as per the usual `+/etc+` packaging guidelines. * If the configuration will be copied in place, the product-specific configuration file - MUST be located in an appropriate part of the /usr/share hierarchy. + MUST be located in an appropriate part of the `+/usr/share+` hierarchy. The divergent config file - MUST be specified as a normal file in the %files section. + MUST be specified as a normal file in the `+%files+` section. -=== Applying Configuration +== Applying Configuration In order to apply the configuration, the packager MUST implement a mechanism @@ -67,63 +68,68 @@ in the `+%posttrans+` section of the specfile that behaves as follows: * It MUST first check whether the final config file already exists. If so, the script MUST make no changes. - -.... ++ +[source, rpm-spec] +---- %posttrans if [ ! -e %{_sysconfdir}/foo/foo.conf ]; then ... fi -.... +---- * Then it MUST use the value of the Fedora `+VARIANT_ID+` to symlink or copy one of the divergent config files (or the default) to the final config file location. It will get this value - by importing the contents of /etc/os-release as shell values. + by importing the contents of `+/etc/os-release+` as shell values. Known values of this field at the time of this writing are "atomichost", "cloud", "server" and "workstation". For more detail, see https://www.freedesktop.org/software/systemd/man/os-release.html#VARIANT_ID=[the os-release(5) man page]. - -.... - . /etc/os-release || : - case "$VARIANT_ID" in - server) - ln -sf foo-server.conf %{_sysconfdir}/foo/foo.conf || : - ;; - *) - ln -sf foo-default.conf %{_sysconfdir}/foo/foo.conf || : - ;; - esac -.... ++ +[source, rpm-spec] +---- +. /etc/os-release || : +case "$VARIANT_ID" in + server) + ln -sf foo-server.conf %{_sysconfdir}/foo/foo.conf || : + ;; + *) + ln -sf foo-default.conf %{_sysconfdir}/foo/foo.conf || : + ;; + esac +---- * Lastly, the final config file location - MUST be listed in the %files section with %ghost: - -.... + MUST be listed in the `+%files+` section with `+%ghost+`: ++ +[source, rpm-spec] +---- %ghost %config(noreplace) %{_sysconfdir}/foo/foo.conf -.... +---- * For tracking purposes, the package providing the various configuration files - MUST also contain a virtual Provides: + MUST also contain a virtual `+Provides:+` for each variant configuration that may be applied: - -.... ++ +[source, rpm-spec] +---- Provides: variant_config(Atomic.host) Provides: variant_config(Cloud) Provides: variant_config(Server) Provides: variant_config(Workstation) -.... +---- -=== Example (firewalld) +== Example (firewalld) We will assume for the sake of demonstration that firewalld will need a custom configuration for Fedora Server and Fedora Workstation, but that Fedora Cloud will not require any changes from the global default. -.... +[source, rpm-spec] +---- ... Provides: variant_config(Server) Provides: variant_config(Workstation) @@ -140,16 +146,19 @@ if [ ! -e %{_sysconfdir}/firewalld/firewalld.conf ]; then case "$VARIANT_ID" in server) ln -sf firewalld-server.conf %{_sysconfdir}/firewalld/firewalld.conf || : - ln -sf org.fedoraproject.FirewallD1.server.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : + ln -sf org.fedoraproject.FirewallD1.server.policy \ + %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : ;; workstation) ln -sf firewalld-workstation.conf %{_sysconfdir}/firewalld/firewalld.conf || : - ln -sf org.fedoraproject.FirewallD1.desktop.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : + ln -sf org.fedoraproject.FirewallD1.desktop.policy \ + %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : ;; *) ln -sf firewalld-default.conf %{_sysconfdir}/firewalld/firewalld.conf || : # The default firewall policy will be the same as Server - ln -sf org.fedoraproject.FirewallD1.server.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : + ln -sf org.fedoraproject.FirewallD1.server.policy \ + %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy || : ;; esac fi @@ -167,4 +176,4 @@ fi %ghost %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.desktop.policy %{_datadir}/polkit-1/actions/org.fedoraproject.FirewallD1.server.policy -.... +---- From 045de17ed32544fa0e39b187ebdc0e6d4fc0307b Mon Sep 17 00:00:00 2001 From: Coiby Xu Date: Jun 09 2023 02:02:41 +0000 Subject: [PATCH 69/232] Update guidelines/modules/ROOT/pages/Scriptlets.adoc For Fedora >= 37, the posttrans scriptlet now distinguishes between package install ($1 == 1) and upgrade ($1 == 2). --- diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc index cac2ccd..902bffb 100644 --- a/guidelines/modules/ROOT/pages/Scriptlets.adoc +++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc @@ -45,7 +45,7 @@ So for the common case of install, upgrade, and uninstall we have: |`+%post+` |`+$1 == 1+` |`+$1 == 2+` |(N/A) |`+%preun+` |(N/A) |`+$1 == 1+` |`+$1 == 0+` |`+%postun+` |(N/A) |`+$1 == 1+` |`+$1 == 0+` -|`+%posttrans+` |`+$1 == 1+` |`+$1 == 1+` |(N/A) +|`+%posttrans+` |`+$1 == 1+` |`+$1 == 2+` |(N/A) |=================================== Note that these values will vary From 5013e8f1f3f38c47bce469cb2af7eae9bf6c18b3 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 02:04:18 +0000 Subject: [PATCH 70/232] WebAssets: Fix interdoc links --- diff --git a/guidelines/modules/ROOT/pages/Web_Assets.adoc b/guidelines/modules/ROOT/pages/Web_Assets.adoc index 232162e..f765122 100644 --- a/guidelines/modules/ROOT/pages/Web_Assets.adoc +++ b/guidelines/modules/ROOT/pages/Web_Assets.adoc @@ -4,11 +4,11 @@ *Web Assets* are any static content that are shipped intact to web browsers, usually by web applications. These might be user interface frameworks, Flash video players, CSS frameworks, icon libraries, or lots of other possibilities. -If your package is primarily or solely shipped to a browser and not used locally, and is not JavaScript, it probably falls under these guidelines. JavaScript packages must follow the Packaging:JavaScript[JavaScript guidelines] in addition to these guidelines. +If your package is primarily or solely shipped to a browser and not used locally, and is not JavaScript, it probably falls under these guidelines. JavaScript packages must follow the xref:JavaScript.adoc[JavaScript guidelines] in addition to these guidelines. == Rationale -There are lots of little bits shipped to browsers that aren't just JavaScript that typically have been bundled along with web applications up to this point. Packaging:JavaScript#Rationale[There are a lot of good reasons why we shouldn't bundle JavaScript this way], so it only follows that we should fix it for the rest of that kind of stuff too. +There are lots of little bits shipped to browsers that aren't just JavaScript that typically have been bundled along with web applications up to this point. xref:JavaScript.adoc#_bundling_of_other_libraries[There are a lot of good reasons why we shouldn't bundle JavaScript this way], so it only follows that we should fix it for the rest of that kind of stuff too. == BuildRequires @@ -60,7 +60,7 @@ Regardless, web applications may want to make subdirectories of `+%{_webassetdir == Content Guidelines -Web Assets must follow the general guidelines for Packaging:Guidelines#CodeVsContent[content], unless stated otherwise in this document. +Web Assets must follow the general guidelines for xref:WhatCanBePackaged.adoc[what can be packaged], unless stated otherwise in this document. == CSS @@ -70,13 +70,13 @@ Pure CSS frameworks can be included as-is. CSS frameworks that use an alternativ Flash files (which typically use the `+.swf+` extension) must follow the general and licensing guidelines for code, not content, and must be built from source using a toolchain available in Fedora. -The Flash software needs to be compiled by a free software toolchain, such as `+swfc+`. Packaging:Guidelines#No_inclusion_of_pre-built_binaries_or_libraries[Pre-built `+.swf+` files *must not* be included in Fedora packages.] That compilation must be performed as part of the build process for the package. +The Flash software needs to be compiled by a free software toolchain, such as `+swfc+`. xref:WhatCanBePackaged.adoc#prebuilt-binaries-or-libraries[Pre-built `+.swf+` files *must not* be included in Fedora packages.] That compilation must be performed as part of the build process for the package. If the flash software is not compilable using the toolchains inside of Fedora then the flash software cannot be shipped. In some cases you may be able to patch out use of the flash software (for instance, if it's a fallback in case the browser doesn't support HTML5) or you may have to give up on packaging the software until the flash software toolchain is enhanced to allow building. == Java applets -Java applets should follow the general and licensing guidelines for code, not content. Additionally, they should follow the Packaging:Java[Java guidelines], with the exception that the actual `+.jar+` file for the Java applet should be installed into a subdirectory of `+%{_webassetdir}+`. +Java applets should follow the general and licensing guidelines for code, not content. Additionally, they should follow the xref:Java.adoc[Java guidelines], with the exception that the actual `+.jar+` file for the Java applet should be installed into a subdirectory of `+%{_webassetdir}+`. == Images From 8684de54635fe169221188011099c0fa010dd0cb Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 02:04:18 +0000 Subject: [PATCH 71/232] Web Assets: Adoc code blocks don't need escaping --- diff --git a/guidelines/modules/ROOT/pages/Web_Assets.adoc b/guidelines/modules/ROOT/pages/Web_Assets.adoc index f765122..65bd4d1 100644 --- a/guidelines/modules/ROOT/pages/Web_Assets.adoc +++ b/guidelines/modules/ROOT/pages/Web_Assets.adoc @@ -53,7 +53,7 @@ All HTTP daemons in the distribution should make `+%{_webassetdir}+` available i Therefore, if the `+fabulous-web-icons+` package ships an icon as `+%{_webassetdir}/fabulous-web-icons/important.png+`, you can include it in a web application with the following HTML: .... -<img src="/.sysassets/fabulous-web-icons/important.png"> + .... Regardless, web applications may want to make subdirectories of `+%{_webassetdir}+` available under their own directory via aliases or symlinks for compatibility purposes or to eliminate needless deviation from upstream. From 569c109aedbe41cad914c5214dd1be4f7a113467 Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 02:04:18 +0000 Subject: [PATCH 72/232] Web Assets: Semantic newlines --- diff --git a/guidelines/modules/ROOT/pages/Web_Assets.adoc b/guidelines/modules/ROOT/pages/Web_Assets.adoc index 65bd4d1..2cd8226 100644 --- a/guidelines/modules/ROOT/pages/Web_Assets.adoc +++ b/guidelines/modules/ROOT/pages/Web_Assets.adoc @@ -2,17 +2,31 @@ == Scope -*Web Assets* are any static content that are shipped intact to web browsers, usually by web applications. These might be user interface frameworks, Flash video players, CSS frameworks, icon libraries, or lots of other possibilities. - -If your package is primarily or solely shipped to a browser and not used locally, and is not JavaScript, it probably falls under these guidelines. JavaScript packages must follow the xref:JavaScript.adoc[JavaScript guidelines] in addition to these guidelines. +*Web Assets* are any static content that are shipped intact to web browsers, +usually by web applications. +These might be user interface frameworks, +Flash video players, CSS frameworks, icon libraries, +or lots of other possibilities. + +If your package is primarily or solely shipped to a browser +and not used locally, and is not JavaScript, +it probably falls under these guidelines. +JavaScript packages must follow the +xref:JavaScript.adoc[JavaScript guidelines] +in addition to these guidelines. == Rationale -There are lots of little bits shipped to browsers that aren't just JavaScript that typically have been bundled along with web applications up to this point. xref:JavaScript.adoc#_bundling_of_other_libraries[There are a lot of good reasons why we shouldn't bundle JavaScript this way], so it only follows that we should fix it for the rest of that kind of stuff too. +There are lots of little bits shipped to browsers +that aren't just JavaScript +that typically have been bundled along with web applications up to this point. +xref:JavaScript.adoc#_bundling_of_other_libraries[There are a lot of good reasons why we shouldn't bundle JavaScript this way], +so it only follows that we should fix it for the rest of that kind of stuff too. == BuildRequires -To ensure the presence of the necessary RPM macros, all packages that provide web assets must have: +To ensure the presence of the necessary RPM macros, +all packages that provide web assets must have: .... BuildRequires: web-assets-devel @@ -20,13 +34,15 @@ BuildRequires: web-assets-devel == Requires -To ensure the availability of the necessary directories, all packages that provide web assets must have: +To ensure the availability of the necessary directories, +all packages that provide web assets must have: .... Requires: web-assets-filesystem .... -Web application packages that ship configuration files for Apache HTTPd should ensure that the httpd configuration is installed as well: +Web application packages that ship configuration files for Apache HTTPd +should ensure that the httpd configuration is installed as well: .... Requires: web-assets-httpd @@ -42,50 +58,99 @@ Requires: web-assets-httpd == Install Location -All packages that contain static content useful to different web applications must install into a subdirectory of `+%{_assetdir}+`. For instance, the `+jquery-ui+` package should install itself into `+%{_webassetdir}/jquery-ui+`. +All packages that contain static content useful to different web applications +must install into a subdirectory of `+%{_assetdir}+`. +For instance, +the `+jquery-ui+` package should install itself into +`+%{_webassetdir}/jquery-ui+`. -All packages that contain static content that is only useful within the package in which they are shipped should continue to ship that content in the application's directory structure. However, they must follow the remainder of the guidelines outlined in this document. +All packages that contain static content +that is only useful within the package in which they are shipped +should continue to ship that content in the application's directory structure. +However, they must follow the remainder +of the guidelines outlined in this document. == Server Location -All HTTP daemons in the distribution should make `+%{_webassetdir}+` available in `+/.sysassets+`. +All HTTP daemons in the distribution +should make `+%{_webassetdir}+` available in `+/.sysassets+`. -Therefore, if the `+fabulous-web-icons+` package ships an icon as `+%{_webassetdir}/fabulous-web-icons/important.png+`, you can include it in a web application with the following HTML: +Therefore, if the `+fabulous-web-icons+` package +ships an icon as `+%{_webassetdir}/fabulous-web-icons/important.png+`, +you can include it in a web application with the following HTML: .... .... -Regardless, web applications may want to make subdirectories of `+%{_webassetdir}+` available under their own directory via aliases or symlinks for compatibility purposes or to eliminate needless deviation from upstream. +Regardless, web applications may want to +make subdirectories of `+%{_webassetdir}+` available +under their own directory via aliases or symlinks +for compatibility purposes or to eliminate needless deviation from upstream. == Content Guidelines -Web Assets must follow the general guidelines for xref:WhatCanBePackaged.adoc[what can be packaged], unless stated otherwise in this document. +Web Assets must follow the general guidelines +for xref:WhatCanBePackaged.adoc[what can be packaged], +unless stated otherwise in this document. == CSS -Pure CSS frameworks can be included as-is. CSS frameworks that use an alternative language that compiles to CSS, such as https://lesscss.org/[LESS], must compile to CSS as part of the build process. It is not acceptable to include pre-compiled CSS in Fedora packages. +Pure CSS frameworks can be included as-is. +CSS frameworks that use an alternative language that compiles to CSS, +such as https://lesscss.org/[LESS], +must compile to CSS as part of the build process. +It is not acceptable to include pre-compiled CSS in Fedora packages. == Flash -Flash files (which typically use the `+.swf+` extension) must follow the general and licensing guidelines for code, not content, and must be built from source using a toolchain available in Fedora. +Flash files (which typically use the `+.swf+` extension) +must follow the general and licensing guidelines for code, +not content, and must be built from source +using a toolchain available in Fedora. -The Flash software needs to be compiled by a free software toolchain, such as `+swfc+`. xref:WhatCanBePackaged.adoc#prebuilt-binaries-or-libraries[Pre-built `+.swf+` files *must not* be included in Fedora packages.] That compilation must be performed as part of the build process for the package. +The Flash software needs to be compiled by a free software toolchain, +such as `+swfc+`. +xref:WhatCanBePackaged.adoc#prebuilt-binaries-or-libraries[Pre-built `+.swf+` files *must not* be included in Fedora packages.] +That compilation must be performed as part of the build process for the package. -If the flash software is not compilable using the toolchains inside of Fedora then the flash software cannot be shipped. In some cases you may be able to patch out use of the flash software (for instance, if it's a fallback in case the browser doesn't support HTML5) or you may have to give up on packaging the software until the flash software toolchain is enhanced to allow building. +If the flash software is not compilable using the toolchains inside of Fedora +then the flash software cannot be shipped. +In some cases you may be able to patch out use of the flash software +(for instance, if it's a fallback in case the browser doesn't support HTML5) +or you may have to give up on packaging the software +until the flash software toolchain is enhanced to allow building. == Java applets -Java applets should follow the general and licensing guidelines for code, not content. Additionally, they should follow the xref:Java.adoc[Java guidelines], with the exception that the actual `+.jar+` file for the Java applet should be installed into a subdirectory of `+%{_webassetdir}+`. +Java applets should follow the general and licensing guidelines for code, +not content. +Additionally, they should follow the xref:Java.adoc[Java guidelines], +with the exception that the actual `+.jar+` file for the Java applet +should be installed into a subdirectory of `+%{_webassetdir}+`. == Images -Images that are part of a larger Web Asset package can be included in that package's subdirectory. For instance, a UI library might contain images for its UI components in its subdirectory. +Images that are part of a larger Web Asset package +can be included in that package's subdirectory. +For instance, a UI library might contain images for its UI components +in its subdirectory. -Web Asset packages that consist solely of images, such as a set of icons, may be shipped as their own package. +Web Asset packages that consist solely of images, +such as a set of icons, may be shipped as their own package. == Fonts -All system fonts (available in `+%{_datadir}/fonts+`) are automatically made available in `+%{_webassetdir}/fonts/+` via a symlink. For more information on packaging system fonts, see the xref:FontsPolicy.adoc[font guidelines]. Please note that [Web_Assets/Fonts|only fonts available in the Fedora package collection are made available on HTTP servers by default]. +All system fonts (available in `+%{_datadir}/fonts+`) +are automatically made available in `+%{_webassetdir}/fonts/+` via a symlink. +For more information on packaging system fonts, +see the xref:FontsPolicy.adoc[font guidelines]. +Please note that only fonts available in the Fedora package collection +are made available on HTTP servers by default. + +Please note that those guidelines prohibit packaging fonts elsewhere. +There is no compelling reason to support other font formats, +as most browsers that support web fonts +support the TTF or OTF formats used by system fonts, +therefore alternative web font formats like WOFF are prohibited. -Please note that those guidelines prohibit packaging fonts elsewhere. There is no compelling reason to support other font formats, as most browsers that support web fonts support the TTF or OTF formats used by system fonts, therefore alternative web font formats like WOFF are prohibited. From fcfaded2c17d148e7b1422990ea109d4fb8421cd Mon Sep 17 00:00:00 2001 From: FeRD (Frank Dana) Date: Jun 09 2023 02:04:18 +0000 Subject: [PATCH 73/232] WebAssets: Tag specfile code blocks as rpm-spec --- diff --git a/guidelines/modules/ROOT/pages/Web_Assets.adoc b/guidelines/modules/ROOT/pages/Web_Assets.adoc index 2cd8226..e2a7d7c 100644 --- a/guidelines/modules/ROOT/pages/Web_Assets.adoc +++ b/guidelines/modules/ROOT/pages/Web_Assets.adoc @@ -28,25 +28,28 @@ so it only follows that we should fix it for the rest of that kind of stuff too. To ensure the presence of the necessary RPM macros, all packages that provide web assets must have: -.... +[source, rpm-spec] +---- BuildRequires: web-assets-devel -.... +---- == Requires To ensure the availability of the necessary directories, all packages that provide web assets must have: -.... +[source, rpm-spec] +---- Requires: web-assets-filesystem -.... +---- Web application packages that ship configuration files for Apache HTTPd should ensure that the httpd configuration is installed as well: -.... +[source, rpm-spec] +---- Requires: web-assets-httpd -.... +---- == RPM Macros From 9eb680f9529cfd9d19e49d744aa18991b3f8416e Mon Sep 17 00:00:00 2001 From: Vít Ondruch Date: Jun 09 2023 02:06:00 +0000 Subject: [PATCH 74/232] Fix caret reference in traditional versioning section. --- diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc index 5ed52c0..0587168 100644 --- a/guidelines/modules/ROOT/pages/Versioning.adoc +++ b/guidelines/modules/ROOT/pages/Versioning.adoc @@ -374,7 +374,7 @@ In this case the full N-V-R could be e.g. `pkg-1.0.1.security1^20210301gabc0202- == Traditional versioning with part of the upstream version information in the Release field The method described in this section is deprecated, but **may** be used. -As mentioned in the <> section above, +As mentioned in the xref:_handling_non_sorting_versions_with_tilde_dot_and_caret[Handling non-sorting versions with tilde, dot, and caret] section above, this method is recommended for packages with complex versioning when supporting RHEL7 and other systems with old rpm versions. From 0437641412ac697bf25edb4fd3bb3356ede533e5 Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Jun 09 2023 02:13:30 +0000 Subject: [PATCH 75/232] Golang: Be consistent when describing the naming of source packages Saying 'Golang source packages MUST be named after their main import path' as the first bullet point, makes one think that all Golang source packages should be named that way. However, then, the second bullet point says that 'source packages that provide a well-known application' should be named differently. So, not all Golang source packages need to be named the same way? Remove the confusion, by using the same wording from the section on Go code packages. https://pagure.io/packaging-committee/pull-request/1262 --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index bf32dd8..e154f40 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -43,7 +43,8 @@ Perform this fixing in `+%prep+`. === Source packages (src.rpm) -* Golang source packages MUST be named after their main import path. +* Golang source packages dedicated to providing code MUST be named after their + main import path. This process is automated by the `+%{goname}+` macro. This macro will remove any capitalization, "go" keywords, and any duplication in From 11c1041cf8fd1df8465f15e08754f61598688db6 Mon Sep 17 00:00:00 2001 From: Debarshi Ray Date: Jun 09 2023 02:13:30 +0000 Subject: [PATCH 76/232] Golang: Clarify how %gopkg fits in with the naming of code packages There are many Golang source packages dedicated to providing code that use %{gopkg} and friends to declare the %{goname}-devel subpackage. It was confusing to compare such a package against the naming guidelines because it wasn't clear where the %{goname}-devel subpackage was coming from. Readers shouldn't be expected to read the sources of RPM macros to understand what's going on. https://pagure.io/packaging-committee/pull-request/1262 --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index e154f40..875b22b 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -103,8 +103,7 @@ collision. Packages that ship Go code in `+%{goipath}+` should be named `+%{goname}-devel+`. -If your source package is already named `+%{goname}+`, that is easily achieved -with: +If your source package is already named `+%{goname}+` then: [source,RPMSpec] ---- @@ -115,6 +114,9 @@ with: %files devel -f devel.file-list ---- +This has been automated by the `+%{gopkg}+` and `+%{gopdevelkg}+` macros +described in the <> section below. + ==== In a another kind of source package If your source package is named something other than `+%{goname}+`, you SHOULD From f21b74025104235a82c28ed8803540b89af4bb99 Mon Sep 17 00:00:00 2001 From: Timothée Ravier Date: Jul 03 2023 16:15:17 +0000 Subject: [PATCH 77/232] UsersAndGroups: Add postgresql (26) See: https://src.fedoraproject.org/rpms/postgresql/pull-request/60 --- diff --git a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc index f8195ce..1788136 100644 --- a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc +++ b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc @@ -254,6 +254,7 @@ mail,8,https://src.fedoraproject.org/rpms/setup[setup], operator,11,https://src.fedoraproject.org/rpms/setup[setup], games,12,https://src.fedoraproject.org/rpms/setup[setup], ftp,14,https://src.fedoraproject.org/rpms/setup[setup], +postgres,26,https://src.fedoraproject.org/rpms/postgresql[postgresql], rpc,32,https://src.fedoraproject.org/rpms/rpcbind[rpcbind], gdm,42,https://src.fedoraproject.org/rpms/gdm[gdm], tss,59,https://src.fedoraproject.org/rpms/tpm2-tss[tpm2-tss], @@ -285,6 +286,7 @@ dialout,18,https://src.fedoraproject.org/rpms/setup[setup], floppy,19,https://src.fedoraproject.org/rpms/setup[setup], games,20,https://src.fedoraproject.org/rpms/setup[setup], utmp,22,https://src.fedoraproject.org/rpms/libutempter[libutempter], +postgres,26,https://src.fedoraproject.org/rpms/postgresql[postgresql], rpc,32,https://src.fedoraproject.org/rpms/rpcbind[rpcbind], tape,33,https://src.fedoraproject.org/rpms/setup[setup], utempter,35,https://src.fedoraproject.org/rpms/libutempter[libutempter], From 064d6c9011d74bfbec164096ed026f2e107deaba Mon Sep 17 00:00:00 2001 From: Miro Hrončok Date: Jul 04 2023 21:46:07 +0000 Subject: [PATCH 78/232] Fixup a Python version conditional It could lead to syntax errors without this. --- diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc index f8b98f3..888f42b 100644 --- a/guidelines/modules/ROOT/pages/Python.adoc +++ b/guidelines/modules/ROOT/pages/Python.adoc @@ -1808,7 +1808,7 @@ similar to the Python string prefixes: [source,spec] ---- -%if v"%{python3_version}" > v"3.8" +%if v"0%{?python3_version}" > v"3.8" ... %endif ---- From a083d5ba8877b9cf3aae1ff755d4196e2efbe5af Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Jul 11 2023 16:52:12 +0000 Subject: [PATCH 79/232] Ansible_collections: fix copy-paste error --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index 43fb3bb..ce8980e 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -422,8 +422,8 @@ Now, the macros extract the collection namespace from the `galaxy.yml`. ---- The ansible-packaging macros previously required -packagers to manually set `+%collection_namespace+` in specfiles. -Now, the macros extract the collection namespace from the `galaxy.yml`. +packagers to manually set `+%collection_name+` in specfiles. +Now, the macros extract the collection name from the `galaxy.yml`. [#ansible_collection_files] From bfad073c09b62f278ff425deccc38cdd91bc34c2 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Jul 11 2023 16:52:12 +0000 Subject: [PATCH 80/232] Ansible_collections: update EPEL compatibility note Naming specific RHEL minor versions will get outdated quickly. Both RHEL 8.8 and 9.2 now build against python3.11. The RHEL people like to make our job difficult by continually changing the Python version [1]. [1]: That's not the actual reason they do it, but it's an unfortunate side effect. --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index ce8980e..ed8b396 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -132,12 +132,8 @@ The `+%ansible_test_unit+` macro MUST be used to run tests. ==== It is currently impossible to run unit tests on EPEL 8 and 9. -ansible-core in RHEL 8.6 is built against python38. In c8s and the next RHEL -8 minor release, it will be built against python39. The testing dependencies -are not yet packaged for either Python version in EPEL 8. - -ansible-test in RHEL 9.0 still needs python3-mock, but this -requirement has been removed in CentOS 9 Stream. +ansible-core in RHEL 8 and 9 are built against alternative python stacks for +which the necessary test dependencies are not available. The rest of these guidelines are applicable to EPEL 8 and 9, and `+ansible-packaging+` itself is available there. From 545bb921acb7a40281ab93fa1206d62bd94a4bda Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Jul 11 2023 16:52:12 +0000 Subject: [PATCH 81/232] Ansible_collections: s/principal/principle/ 🫣 --- diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc index ed8b396..a6d534a 100644 --- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc +++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc @@ -101,7 +101,7 @@ but it doesn't make sense for the larger, more general ansible-collection-community-general collection to Recommend `+python3-redis+` for the `+redis+` lookup plugin. This guideline seeks to prevent ballooning collection packages. -`+ansible-core+` and `+ansible+` follow this same principal. +`+ansible-core+` and `+ansible+` follow this same principle. == Build and Installation From 1d79d4cbfd9ce2ebc65364771014fe55e0207596 Mon Sep 17 00:00:00 2001 From: Link Dupont Date: Jul 14 2023 16:54:35 +0000 Subject: [PATCH 82/232] golang: add GO111MODULE=off to golist example golist relies on GOPATH for analysis, so in order for `go get` to work outside a package directory, G111MODULE must be set to off. --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 875b22b..de0be1e 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -319,6 +319,7 @@ For example:[[manual_br]] [source,bash] ---- export GOPATH=/home/user/go + export GO111MODULE=off export goipath="github.com/sirupsen/logrus" go get $goipath (sort -u | xargs -I{} echo "BuildRequires: golang({})") <<< "$( From 89e7be28da465f502c6ef7fae3460a8d732747e9 Mon Sep 17 00:00:00 2001 From: Jerry James Date: Jul 21 2023 21:28:55 +0000 Subject: [PATCH 83/232] Remove `%undefine _package_note_flags` from OCaml examples --- diff --git a/guidelines/modules/ROOT/examples/ocaml-dune-example.spec b/guidelines/modules/ROOT/examples/ocaml-dune-example.spec index 79ec39e..17c9cdf 100644 --- a/guidelines/modules/ROOT/examples/ocaml-dune-example.spec +++ b/guidelines/modules/ROOT/examples/ocaml-dune-example.spec @@ -1,5 +1,3 @@ -%undefine _package_note_flags - %ifnarch %{ocaml_native_compiler} %global debug_package %{nil} %endif diff --git a/guidelines/modules/ROOT/examples/ocaml-example.spec b/guidelines/modules/ROOT/examples/ocaml-example.spec index 02591d8..5167b9f 100644 --- a/guidelines/modules/ROOT/examples/ocaml-example.spec +++ b/guidelines/modules/ROOT/examples/ocaml-example.spec @@ -1,5 +1,3 @@ -%undefine _package_note_flags - %ifnarch %{ocaml_native_compiler} %global debug_package %{nil} %endif diff --git a/guidelines/modules/ROOT/examples/ocaml-topkg-example.spec b/guidelines/modules/ROOT/examples/ocaml-topkg-example.spec index 7d5d969..4365de2 100644 --- a/guidelines/modules/ROOT/examples/ocaml-topkg-example.spec +++ b/guidelines/modules/ROOT/examples/ocaml-topkg-example.spec @@ -1,5 +1,3 @@ -%undefine _package_note_flags - %ifnarch %{ocaml_native_compiler} %global debug_package %{nil} %endif From 94f570b5ee807de18d122360ae6071544a33f221 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Jul 26 2023 17:29:00 +0000 Subject: [PATCH 84/232] Fix golang example licenses Fix various License: tags in the golang example specs. --- diff --git a/guidelines/modules/ROOT/examples/golang/golang-cloud-google-go.spec b/guidelines/modules/ROOT/examples/golang/golang-cloud-google-go.spec index 2b11619..5365be5 100644 --- a/guidelines/modules/ROOT/examples/golang/golang-cloud-google-go.spec +++ b/guidelines/modules/ROOT/examples/golang/golang-cloud-google-go.spec @@ -27,7 +27,7 @@ Release: 1%{?dist} Summary: Google Cloud client libraries for Go # Upstream license specification: Apache-2.0 -License: Apache-2.0-or-later +License: Apache-2.0 URL: %{gourl} Source: %{gosource} diff --git a/guidelines/modules/ROOT/examples/golang/golang-github-stretchr-testify.spec b/guidelines/modules/ROOT/examples/golang/golang-github-stretchr-testify.spec index 84faa82..59c9d08 100644 --- a/guidelines/modules/ROOT/examples/golang/golang-github-stretchr-testify.spec +++ b/guidelines/modules/ROOT/examples/golang/golang-github-stretchr-testify.spec @@ -19,7 +19,7 @@ Features include: Name: %{goname} Release: 1%{?dist} Summary: Tools for testifying that your code will behave as you intend -License: BSD +License: MIT URL: %{gourl} Source: %{gosource} diff --git a/guidelines/modules/ROOT/examples/golang/golang-gopkg-square-jose-2.spec b/guidelines/modules/ROOT/examples/golang/golang-gopkg-square-jose-2.spec index 07590b8..40250d7 100644 --- a/guidelines/modules/ROOT/examples/golang/golang-gopkg-square-jose-2.spec +++ b/guidelines/modules/ROOT/examples/golang/golang-gopkg-square-jose-2.spec @@ -24,7 +24,7 @@ Summary: An implementation of JOSE standards (JWE, JWS, JWT) in Go # Detected licences # - *No copyright* Apache License (v2.0) at 'LICENSE' # json/ is BSD-3-Clause -License: Apache-2.0-or-later AND BSD-3-Clause +License: Apache-2.0 AND BSD-3-Clause URL: %{gourl} Source: %{gosource} From 9f2bf3436922b6de204f691fc7a468d46794df79 Mon Sep 17 00:00:00 2001 From: Amit Shah Date: Jul 27 2023 16:46:20 +0000 Subject: [PATCH 85/232] Add notes on new dist macros Add information on the new dist macros, as introduced in https://src.fedoraproject.org/rpms/fedora-release/pull-request/223 --- diff --git a/guidelines/modules/ROOT/pages/DistTag.adoc b/guidelines/modules/ROOT/pages/DistTag.adoc index 1ecf643..f83174e 100644 --- a/guidelines/modules/ROOT/pages/DistTag.adoc +++ b/guidelines/modules/ROOT/pages/DistTag.adoc @@ -130,6 +130,20 @@ and *NOT* Without the extra 0, if `+%{rhel}+` is undefined, the `+%if+` conditional will cease to exist, and the rpm will fail to build. +=== Distribution-specific values + +Fedora 37 onwards, a few helper macros are defined to help packagers write distribution-agnostic spec files: + +`+%{dist_vendor}+`: The vendor of the distribution. For Fedora, this is `+Fedora+`. +`+%{dist_name}+`: The name of the distribution. For Fedora, this is `+Fedora Linux+`. +`+%{dist_home_url}+`: The URL of the homepage of the distribution. For Fedora, this is `+https://fedoraproject.org/+` +`+%{dist_bug_report_url}+`: The URL for reporting bugs. For Fedora, this is `+https://bugzilla.redhat.com/+` +`+%{dist_debuginfod_url}+`: The URL where the debuginfod server runs (if any). This is used +in elfutils.spec. For Fedora, this is `+https://debuginfod.fedoraproject.org/+`. + +These values are configured via the `+fedora-release+` package. Downstream distributions of +Fedora are expected to provide their distribution-specific values here. + === Things that you cannot use +%{?dist}+ for * You must not override the variables for `+%{dist}+` (or any of the related variables). From 6fff70c49675ad5da0f0aa7a1a4afae15c998cb7 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Jul 27 2023 17:21:20 +0000 Subject: [PATCH 86/232] Update version macros. --- diff --git a/guidelines/modules/ROOT/pages/_partials/versions.adoc b/guidelines/modules/ROOT/pages/_partials/versions.adoc index b579e12..104773f 100644 --- a/guidelines/modules/ROOT/pages/_partials/versions.adoc +++ b/guidelines/modules/ROOT/pages/_partials/versions.adoc @@ -12,6 +12,6 @@ versions, because then those guidelines will be wrong when these macros are updated. In that you instead simply hardcode the version numbers. //// -:NEXTVER: 36 -:CURRENTVER: 35 -:PREVVER: 34 +:NEXTVER: 39 +:CURRENTVER: 38 +:PREVVER: 37 From 0116fc57b2ea316f890e17f2dc433858238bc809 Mon Sep 17 00:00:00 2001 From: Amit Shah Date: Aug 02 2023 15:03:00 +0000 Subject: [PATCH 87/232] DistTag: fix formatting for the newly-added section --- diff --git a/guidelines/modules/ROOT/pages/DistTag.adoc b/guidelines/modules/ROOT/pages/DistTag.adoc index f83174e..d4b737b 100644 --- a/guidelines/modules/ROOT/pages/DistTag.adoc +++ b/guidelines/modules/ROOT/pages/DistTag.adoc @@ -135,9 +135,13 @@ Without the extra 0, if `+%{rhel}+` is undefined, the `+%if+` conditional will c Fedora 37 onwards, a few helper macros are defined to help packagers write distribution-agnostic spec files: `+%{dist_vendor}+`: The vendor of the distribution. For Fedora, this is `+Fedora+`. + `+%{dist_name}+`: The name of the distribution. For Fedora, this is `+Fedora Linux+`. + `+%{dist_home_url}+`: The URL of the homepage of the distribution. For Fedora, this is `+https://fedoraproject.org/+` + `+%{dist_bug_report_url}+`: The URL for reporting bugs. For Fedora, this is `+https://bugzilla.redhat.com/+` + `+%{dist_debuginfod_url}+`: The URL where the debuginfod server runs (if any). This is used in elfutils.spec. For Fedora, this is `+https://debuginfod.fedoraproject.org/+`. From 53c99ecb46a86871a78df7aa8cb28ddad467a626 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 11 2023 21:23:40 +0000 Subject: [PATCH 88/232] Fix list mangled in the wiki conversion. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index b004ae3..06aeaea 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2134,10 +2134,10 @@ 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) +* 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 From e491bb89176800f1d01ec1b7c127626c1ee683db Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 22 2023 16:47:19 +0000 Subject: [PATCH 89/232] Remove trailing whitespace. --- diff --git a/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc b/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc index 0e84625..02d7753 100644 --- a/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc +++ b/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc @@ -2,22 +2,22 @@ == Fedora Licensing -The goal of the Fedora Project is to work with the Linux community to create a complete, +The goal of the Fedora Project is to work with the Linux community to create a complete, general purpose operating system exclusively from free and open source software. -All software in Fedora must be under licenses that have been determined to +All software in Fedora must be under licenses that have been determined to be https://docs.fedoraproject.org/en-US/legal/license-approval/[allowed for Fedora]. This criteria is based on the licenses approved by the https://www.gnu.org/philosophy/license-list.html#GPLCompatibleLicenses[Free Software Foundation], https://opensource.org/licenses/[OSI] and consultation with Red Hat Legal. -For more details on the criteria for allowed and not-allowed licenses, processes related to licensing, -or other guidance related to Fedora licensing, +For more details on the criteria for allowed and not-allowed licenses, processes related to licensing, +or other guidance related to Fedora licensing, see xref:legal::index.adoc[Licensing in Fedora]. -The information here provides guidance on how to add license text in `+%license+` -and how to populate the `+License:+` field of +The information here provides guidance on how to add license text in `+%license+` +and how to populate the `+License:+` field of spec files for Fedora packages. == License Text @@ -69,7 +69,7 @@ However, this is not always possible to achieve. == License: field Every Fedora package must contain a `+License:+` entry. -Maintainers should be aware that the contents of the `+License:+` field are understood to not be legally +Maintainers should be aware that the contents of the `+License:+` field are understood to not be legally binding (only the source code itself is), but maintainers must make every possible effort to be accurate when filling the `+License:+` field. @@ -79,23 +79,18 @@ This policy and examples can be found at xref:legal::license-field.adoc[License: === Valid License Short Names -The `+License:+` field for new packages as of July 2022 must be filled with the appropriate SPDX license identifier or +The `+License:+` field for new packages as of July 2022 must be filled with the appropriate SPDX license identifier or expression from the list of xref:legal::allowed-licenses.adoc[allowed licenses] for Fedora. Note that some licenses may be allowed for only certain types of material, e.g., fonts, content, or documentation. -The https://spdx.org/licenses/[SPDX License List] provides identifiers for each individual license -or exception based on a set of matching guidelines. -SPDX license expressions cover situations where multiple licenses apply to a package, where there is a choice -of a license, and where licenses are coupled with exceptions or additional permissions. +The https://spdx.org/licenses/[SPDX License List] provides identifiers for each individual license +or exception based on a set of matching guidelines. +SPDX license expressions cover situations where multiple licenses apply to a package, where there is a choice +of a license, and where licenses are coupled with exceptions or additional permissions. -xref:legal::license-field.adoc[License: field in Spec file] contains examples +xref:legal::license-field.adoc[License: field in Spec file] contains examples and further explanations for using SPDX expressions in the `License:` field. -For more information on what to do if you find a license that is not on the Fedora list, -does not have a corresponding SPDX license identifier or expression, or other process questions, +For more information on what to do if you find a license that is not on the Fedora list, +does not have a corresponding SPDX license identifier or expression, or other process questions, see xref:legal::license-review-process.adoc[License Review Process]. - - - - - From 5266d159dacfeb2d634ab94c4a18789050684be7 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 22 2023 16:47:19 +0000 Subject: [PATCH 90/232] Semantic line breaks. --- diff --git a/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc b/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc index 02d7753..251d71c 100644 --- a/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc +++ b/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc @@ -2,95 +2,160 @@ == Fedora Licensing -The goal of the Fedora Project is to work with the Linux community to create a complete, -general purpose operating system exclusively from free and open source software. - -All software in Fedora must be under licenses that have been determined to -be https://docs.fedoraproject.org/en-US/legal/license-approval/[allowed for Fedora]. +The goal of the Fedora Project is +to work with the Linux community to create a complete, +general purpose operating system +exclusively from free and open source software. + +All software in Fedora must be under licenses +that have been determined to be +https://docs.fedoraproject.org/en-US/legal/license-approval/[allowed for Fedora]. This criteria is based on the licenses approved by the https://www.gnu.org/philosophy/license-list.html#GPLCompatibleLicenses[Free Software Foundation], https://opensource.org/licenses/[OSI] and consultation with Red Hat Legal. -For more details on the criteria for allowed and not-allowed licenses, processes related to licensing, +For more details on the criteria for allowed +and not-allowed licenses, processes related to licensing, or other guidance related to Fedora licensing, see xref:legal::index.adoc[Licensing in Fedora]. -The information here provides guidance on how to add license text in `+%license+` +The information here provides guidance +on how to add license text in `+%license+` and how to populate the `+License:+` field of spec files for Fedora packages. == License Text -If the source package includes the text of the license(s) in its own file, then that file, containing the text of the license(s) for the package must be included in `+%license+`. -If the source package does not include the text of the license(s), the packager should contact upstream and encourage them to correct this mistake. - -In cases where the upstream has chosen a license that requires that a copy of the license text be distributed along with the binaries and/or source code, -but does not provide a copy of the license text (in the source tree, or in some rare cases, anywhere), +If the source package includes the text of the license(s) in its own file, +then that file, +containing the text of the license(s) for the package +must be included in `+%license+`. +If the source package does not include the text of the license(s), +the packager should contact upstream +and encourage them to correct this mistake. + +In cases where the upstream has chosen a license that requires +that a copy of the license text be distributed +along with the binaries and/or source code, +but does not provide a copy of the license text +(in the source tree, or in some rare cases, anywhere), the packager should do their best to point out this confusion to upstream. -This sometimes occurs when an upstream project's only reference to a license is in a README (where they simply say "licensed under the FOO license"), on their website, +This sometimes occurs when an upstream project's only reference to a license +is in a README +(where they simply say "licensed under the FOO license"), +on their website, or when they simply do not check a copy of the license into their Source tree. -Packagers should point out to upstream that by not including a proper full license text, -they are making it difficult or impossible for anyone to comply with their desired license terms. - -However, in situations where upstream is unresponsive, unable, or unwilling to provide proper full license text as part of the source code, -and the indicated license requires that the full license text be included, Fedora Packagers must either: - -* Include a copy of what they believe the license text is intended to be, as part of the Fedora package in `+%license+`, in order to remain in compliance. -It is worth noting that this may place some additional risk on the packager, however, -Fedora believes that this risk is minimized by the fact that if the upstream disagrees with what we have distributed as the full license text, -they can easily remedy this by making full license text available in the source code. -Packagers who choose to do this should ensure that they have exhausted all attempts to work with upstream to include the license text as part of the source code, -or at least, to confirm the full license text explicitly with the upstream, as this minimizes the risk on the packager. -Packagers may also take copies of license texts from reliable and canonical sources -(such as the original license text from the license steward, Fedora licenses page, the FSF licenses page, or the OSI license list), whenever possible. +Packagers should point out to upstream +that by not including a proper full license text, +they are making it difficult or impossible +for anyone to comply with their desired license terms. + +However, in situations where upstream is unresponsive, unable, or unwilling +to provide proper full license text as part of the source code, +and the indicated license requires that the full license text be included, +Fedora Packagers must either: + +* Include a copy of what they believe the license text is intended to be, +as part of the Fedora package in `+%license+`, +in order to remain in compliance. +It is worth noting that this may place some additional risk on the packager, +however, Fedora believes that this risk is minimized +by the fact that if the upstream disagrees +with what we have distributed as the full license text, +they can easily remedy this by making full license text available +in the source code. +Packagers who choose to do this should ensure +that they have exhausted all attempts to work with upstream +to include the license text as part of the source code, +or at least, to confirm the full license text +explicitly with the upstream, +as this minimizes the risk on the packager. +Packagers may also take copies of license texts +from reliable and canonical sources +(such as the original license text from the license steward, +Fedora licenses page, +the FSF licenses page, +or the OSI license list), +whenever possible. * Choose not to package that software for Fedora. -It is important to reiterate that in situations where the indicated license does not imply a requirement that the license be distributed along with the source/binaries, -Fedora packagers are NOT required to manually include the full license text when it is absent from the source code, -but are still encouraged to point out this issue to upstream and encourage them to remedy it. +It is important to reiterate +that in situations where the indicated license does not imply a requirement +that the license be distributed along with the source/binaries, +Fedora packagers are NOT required to manually include the full license text +when it is absent from the source code, +but are still encouraged to point out this issue to upstream +and encourage them to remedy it. [#subpackage-licensing] === Subpackage Licensing -If a subpackage is dependent (either implicitly or explicitly) upon a base package (where a base package is defined as a resulting binary package from the -same source RPM which contains the appropriate license texts as %license), it is not necessary for that subpackage to also include those license texts as %license. - -However, if a subpackage is independent of any base package (it does not require it, either implicitly or explicitly), it must include copies of any license texts -(as present in the source) which are applicable to the files contained within the subpackage. +If a subpackage is dependent +(either implicitly or explicitly) +upon a base package +(where a base package is defined as a resulting binary package +from the same source RPM +which contains the appropriate license texts as %license), +it is not necessary for that subpackage +to also include those license texts as %license. + +However, if a subpackage is independent of any base package +(it does not require it, either implicitly or explicitly), +it must include copies of any license texts +(as present in the source) +which are applicable to the files contained within the subpackage. === License Clarification -In cases where the licensing is unclear, it may be necessary to contact the copyright holders to confirm the licensing of code or content. -In those situations, it is _always_ preferred to ask upstream to resolve the licensing confusion by documenting the licensing and releasing an updated tarball. +In cases where the licensing is unclear, +it may be necessary to contact the copyright holders +to confirm the licensing of code or content. +In those situations, +it is _always_ preferred to ask upstream to resolve the licensing confusion +by documenting the licensing and releasing an updated tarball. However, this is not always possible to achieve. == License: field Every Fedora package must contain a `+License:+` entry. -Maintainers should be aware that the contents of the `+License:+` field are understood to not be legally -binding (only the source code itself is), -but maintainers must make every possible effort to be accurate when filling the `+License:+` field. +Maintainers should be aware that the contents +of the `+License:+` field are understood to not be legally binding +(only the source code itself is), +but maintainers must make every possible effort +to be accurate when filling the `+License:+` field. -The `License:` field refers to the licenses of the contents of the *_binary_* rpm. +The `License:` field refers +to the licenses of the contents of the *_binary_* rpm. -This policy and examples can be found at xref:legal::license-field.adoc[License: field in spec file]. +This policy and examples can be found at +xref:legal::license-field.adoc[License: field in spec file]. === Valid License Short Names -The `+License:+` field for new packages as of July 2022 must be filled with the appropriate SPDX license identifier or -expression from the list of xref:legal::allowed-licenses.adoc[allowed licenses] for Fedora. -Note that some licenses may be allowed for only certain types of material, e.g., fonts, content, or documentation. +The `+License:+` field for new packages as of July 2022 +must be filled with the appropriate SPDX license identifier +or expression from the list of +xref:legal::allowed-licenses.adoc[allowed licenses] for Fedora. +Note that some licenses may be allowed +for only certain types of material, +e.g., fonts, content, or documentation. -The https://spdx.org/licenses/[SPDX License List] provides identifiers for each individual license +The https://spdx.org/licenses/[SPDX License List] +provides identifiers for each individual license or exception based on a set of matching guidelines. -SPDX license expressions cover situations where multiple licenses apply to a package, where there is a choice -of a license, and where licenses are coupled with exceptions or additional permissions. - -xref:legal::license-field.adoc[License: field in Spec file] contains examples -and further explanations for using SPDX expressions in the `License:` field. - -For more information on what to do if you find a license that is not on the Fedora list, -does not have a corresponding SPDX license identifier or expression, or other process questions, +SPDX license expressions cover situations +where multiple licenses apply to a package, +where there is a choice of a license, +and where licenses are coupled with exceptions or additional permissions. + +xref:legal::license-field.adoc[License: field in Spec file] +contains examples and further explanations +for using SPDX expressions in the `License:` field. + +For more information on what to do +if you find a license that is not on the Fedora list, +does not have a corresponding SPDX license identifier or expression, +or other process questions, see xref:legal::license-review-process.adoc[License Review Process]. From e474ab89845c510847f547ba7fa79a209809be34 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 22 2023 16:47:19 +0000 Subject: [PATCH 91/232] Fix some non-monspaced strings. --- diff --git a/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc b/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc index 251d71c..eb0bb58 100644 --- a/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc +++ b/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc @@ -97,9 +97,9 @@ If a subpackage is dependent upon a base package (where a base package is defined as a resulting binary package from the same source RPM -which contains the appropriate license texts as %license), +which contains the appropriate license texts as `+%license+`), it is not necessary for that subpackage -to also include those license texts as %license. +to also include those license texts as `+%license+`. However, if a subpackage is independent of any base package (it does not require it, either implicitly or explicitly), From 1a789264558eee21cae8fb4d1a0232974e47b50d Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 22 2023 16:47:19 +0000 Subject: [PATCH 92/232] Implement clarifications from #1223 Fixes #1223 --- diff --git a/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc b/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc index eb0bb58..42400ff 100644 --- a/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc +++ b/guidelines/modules/ROOT/pages/LicensingGuidelines.adoc @@ -30,7 +30,25 @@ spec files for Fedora packages. If the source package includes the text of the license(s) in its own file, then that file, containing the text of the license(s) for the package -must be included in `+%license+`. +must be included in the `+%files+` list +flagged with the `+%license+` directive. + +Note that the path so flagged can be either relative or absolute. +For relative paths, RPM will automatically copy them +from the source directory into a subdirectory of +`+%_defaultlicensedir+` (`+/usr/share/licenses+`). +For absolute paths, RPM will simply tag the file in the final package +as being a license file. + +Note also that it is acceptable for license files to be so flagged +in a list which is generated programmatically +and included using `+%files -f+`. +This tagging is often done automatically by macros +and not directly visible to the packager. +What is important is not the visible presence of the `+%license+` directive +but instead that all relevant license files included in a package appear +when using `+rpm -q --licensefiles+`. + If the source package does not include the text of the license(s), the packager should contact upstream and encourage them to correct this mistake. From 3bea10d3e10de43185eaafa7af5804fed6b0b548 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 24 2023 17:35:46 +0000 Subject: [PATCH 93/232] Fix list formatting It seems that somehow the space after the asterisks was not an ASCII space and this threw off the formatting. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 06aeaea..2c1de7a 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2134,10 +2134,10 @@ 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) +* 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 From 3207b29c1fb2f08f09fe70f085a61518aad073d4 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Aug 24 2023 17:40:41 +0000 Subject: [PATCH 94/232] Properly format some RPM macros. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 2c1de7a..3638c6a 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -2129,7 +2129,8 @@ RPM macro files MUST NOT be marked as `+%config+`. == Scripting Inside of Specfiles 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 +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: From 4e02b92e3d3d11afea3e13317260b894caf56cbc Mon Sep 17 00:00:00 2001 From: Benson Muite Date: Sep 07 2023 16:15:05 +0000 Subject: [PATCH 95/232] Add Lua Add Lua to navigation list --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index 49bfab1..a773e7d 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -51,6 +51,7 @@ *** xref:java-packaging-howto::index.adoc[Java Packaging HOWTO] ** xref:JavaScript.adoc[JavaScript] ** xref:Lisp.adoc[Lisp] +** xref:Lua.adoc[Lua] ** xref:Mono.adoc[Mono] ** xref:Node.js.adoc[Node.js] ** xref:OCaml.adoc[OCaml] From 807c2ea1c7a5a68d213bc1253a7a8753c0225999 Mon Sep 17 00:00:00 2001 From: Benson Muite Date: Sep 07 2023 16:15:13 +0000 Subject: [PATCH 96/232] Initial version Lua packaging guidelines Adapted from https://fedoraproject.org/wiki/PackagingDrafts/Lua Please enter the commit message for your changes. Lines starting --- diff --git a/guidelines/modules/ROOT/pages/Lua.adoc b/guidelines/modules/ROOT/pages/Lua.adoc new file mode 100644 index 0000000..a1c71dc --- /dev/null +++ b/guidelines/modules/ROOT/pages/Lua.adoc @@ -0,0 +1,118 @@ += Lua Packaging Guidelines +:toc: + +== What is Lua? + +As described on the https://www.lua.org/[Lua website], Lua is + +"Lua is a powerful, efficient, lightweight, embeddable scripting language. +It supports procedural programming, object-oriented programming, functional +programming, data-driven programming, and data description." + +To learn Lua, read https://www.lua.org/pil/contents.html[Programming in Lua]. + +== Spec Template for a Lua Package + +Many Lua packages use http://luarocks.org/[Lua-rocks] for packaging. It is helpful +to examine the `+.rockspec+` specification as a guide in writing your spec file. +Some packages require compilation of C programs, but others may be pure Lua. Both +will have very similar install locations. + +... +Summary: Lua integration with libev +Name: lua-ev +License: MIT + +Version: 1.5 +Release: 2%{?dist} + +URL: https://github.com/brimworks/lua-ev +Source0: %{url}/archive/v%{version}/%{name}-%{version}.tar.gz + +BuildRequires: cmake +BuildRequires: gcc +BuildRequires: libev-devel +BuildRequires: lua-devel + +%description +Event loop programming with Lua. + +%prep +%autosetup -n %{name}-%{version} + +%build +%cmake -DINSTALL_CMOD=%{lua_libdir} +%cmake_build + +%install +%cmake_install + +%check +#packaged tests do not work directly +#Use example program as a smoke test +LUA_CPATH=%{buildroot}%{lua_libdir}/?.so \ +lua example.lua +LUA_CPATH=%{buildroot}%{lua_libdir}/?.so \ +lua -e 'ev = require "ev"; print(ev.version())' + +%files +%license README +%doc example.lua +%{lua_libdir}/ev.so + +%changelog +* Thu Dec 08 2022 Benson Muite - 1.5-1 +- Use README as license + +* Sat Nov 19 2022 Benson Muite - 1.5-2 +- Fix install location based on review +- Add further smoke test + +* Wed Nov 16 2022 Benson Muite - 1.5-1 +- Initial release +... + +== Naming + +Lua add-on packages generally follow the naming scheme of `+lua-modulename` +-- e.g. `+lua-filesystem+`, `+lua-lpeg+`, `+lua-moonscript+`. If the module name +makes it clear that it is an add-on for Lua, though, the module name +itself is sufficient. e.g. `+lutok+`. + +Use your judgement -- e.g. the second `+l+` in `+lua-lpeg+` already stands for Lua, +but it might not be seen as unambiguous enough. + +== Macros + +Starting with Fedora 24, the following macros for packaging lua extensions are provided +by the `+lua-devel+` package: + +[%header,cols=2*] +|=== +| Macro | Description +| `+%lua_version+` | version of system installed lua +| `+%lua_libdir+` | installation directory for compiled modules +| `+%lua_pkgdir+` | installation directory for arch-independent modules +| `+%lua_requires+` | declares the needed runtime dependencies for the binary package +|=== + +For EPEL, define the following macros at the top of your spec file: + +... +%{!?lua_version: %global lua_version %{lua: print(string.sub(_VERSION, 5))}} +# for compiled modules +%{!?lua_libdir: %global lua_libdir %{_libdir}/lua/%{lua_version}} +# for arch-independent modules +%{!?lua_pkgdir: %global lua_pkgdir %{_datadir}/lua/%{lua_version}} +... + +To make the package pull the correct runtime dependencies, declare them like this: + +... +%if 0%{?fedora} >= 16 || 0%{?rhel} >= 7 +Requires: lua(abi) = %{lua_version} +%else +Requires: lua >= %{lua_version} +Requires: lua < %{lua: os.setlocale('C'); print(string.sub(_VERSION, 5) + 0.1)} +%endif +... From 6b0aa6aea0182ccbf31f77bb5dac5757d194c8f8 Mon Sep 17 00:00:00 2001 From: Benson Muite Date: Sep 07 2023 16:15:19 +0000 Subject: [PATCH 97/232] Requires lua(abi) no longer needed Pointed out in review --- diff --git a/guidelines/modules/ROOT/pages/Lua.adoc b/guidelines/modules/ROOT/pages/Lua.adoc index a1c71dc..dbbb61e 100644 --- a/guidelines/modules/ROOT/pages/Lua.adoc +++ b/guidelines/modules/ROOT/pages/Lua.adoc @@ -109,10 +109,6 @@ For EPEL, define the following macros at the top of your spec file: To make the package pull the correct runtime dependencies, declare them like this: ... -%if 0%{?fedora} >= 16 || 0%{?rhel} >= 7 -Requires: lua(abi) = %{lua_version} -%else Requires: lua >= %{lua_version} Requires: lua < %{lua: os.setlocale('C'); print(string.sub(_VERSION, 5) + 0.1)} -%endif ... From ac2d5d3775a8b38e7297bb8619bd13481e9881e7 Mon Sep 17 00:00:00 2001 From: Fabio Valentini Date: Sep 07 2023 16:17:05 +0000 Subject: [PATCH 98/232] Lua: AsciiDoc syntax fixups --- diff --git a/guidelines/modules/ROOT/pages/Lua.adoc b/guidelines/modules/ROOT/pages/Lua.adoc index dbbb61e..941362a 100644 --- a/guidelines/modules/ROOT/pages/Lua.adoc +++ b/guidelines/modules/ROOT/pages/Lua.adoc @@ -18,7 +18,7 @@ to examine the `+.rockspec+` specification as a guide in writing your spec file. Some packages require compilation of C programs, but others may be pure Lua. Both will have very similar install locations. -... +.... Summary: Lua integration with libev Name: lua-ev License: MIT @@ -70,11 +70,11 @@ lua -e 'ev = require "ev"; print(ev.version())' * Wed Nov 16 2022 Benson Muite - 1.5-1 - Initial release -... +.... == Naming -Lua add-on packages generally follow the naming scheme of `+lua-modulename` +Lua add-on packages generally follow the naming scheme of `+lua-modulename+` -- e.g. `+lua-filesystem+`, `+lua-lpeg+`, `+lua-moonscript+`. If the module name makes it clear that it is an add-on for Lua, though, the module name itself is sufficient. e.g. `+lutok+`. @@ -84,8 +84,8 @@ but it might not be seen as unambiguous enough. == Macros -Starting with Fedora 24, the following macros for packaging lua extensions are provided -by the `+lua-devel+` package: +The following macros for packaging lua extensions are provided by the +`+lua-devel+` package: [%header,cols=2*] |=== @@ -98,17 +98,17 @@ by the `+lua-devel+` package: For EPEL, define the following macros at the top of your spec file: -... +.... %{!?lua_version: %global lua_version %{lua: print(string.sub(_VERSION, 5))}} # for compiled modules %{!?lua_libdir: %global lua_libdir %{_libdir}/lua/%{lua_version}} # for arch-independent modules %{!?lua_pkgdir: %global lua_pkgdir %{_datadir}/lua/%{lua_version}} -... +.... To make the package pull the correct runtime dependencies, declare them like this: -... +.... Requires: lua >= %{lua_version} Requires: lua < %{lua: os.setlocale('C'); print(string.sub(_VERSION, 5) + 0.1)} -... +.... From cd7def807ec54de5f66806c22d8281a0d66530a9 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Sep 12 2023 15:06:17 +0000 Subject: [PATCH 99/232] systemd: describe %systemd_postun_with_reload and user variants Those were added based on discussion on fedora-devel [1]. Systemd implementation in [2]. The new macros are available in f39+ (systemd >= 254.1-8). I'll do a backport for f38/f37 once this patch for the packaging guidelines is accepted. [1] https://lists.fedoraproject.org/archives/list/devel@lists.fedoraproject.org/message/IJSUGIEJNYZZRE53FF4YFUEBRHRAVIXR/ [2] https://github.com/systemd/systemd/pull/28521 --- diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc index 902bffb..3a7493a 100644 --- a/guidelines/modules/ROOT/pages/Scriptlets.adoc +++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc @@ -412,10 +412,19 @@ BuildRequires: systemd-rpm-macros Some services do not support being restarted (e.g. D-Bus and various storage daemons). If your service should not be restarted upon upgrade, +but should be reloaded instead, then use the following `+%postun+` scriptlet instead of the one shown above: .... %postun +%systemd_postun_with_reload apache-httpd.service +.... + +If your service should not be restarted or reloaded, +then use the following `+%postun+` scriptlet instead: + +.... +%postun %systemd_postun apache-httpd.service .... @@ -441,8 +450,17 @@ BuildRequires: systemd-rpm-macros %preun %systemd_user_preun %{name}.service + +%postun +%systemd_user_postun_with_restart %{name}.service +%systemd_user_postun_with_reload %{name}.service +%systemd_user_postun %{name}.service .... +Macros `+%systemd_user_postun_with_restart+` and `+%systemd_user_postun_with_reload+` +iterate over the running user manager instances +and request the restart and reload operations for the specified units in each one. + ===== Dependencies on the systemd package If package scriptlets call other systemd tools, for example `systemd-tmpfiles`, From 545c0808bafdb20be32a224594ef91e835cebcc7 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Sep 12 2023 15:06:17 +0000 Subject: [PATCH 100/232] systemd: recommend using just one macro invocation --- diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc index 3a7493a..9f9cfde 100644 --- a/guidelines/modules/ROOT/pages/Scriptlets.adoc +++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc @@ -428,6 +428,9 @@ then use the following `+%postun+` scriptlet instead: %systemd_postun apache-httpd.service .... +Those macros accept multiple unit name arguments. +It is better to use a single invocation to reduce the number of calls. + If your package includes one or more systemd units that need to be enabled by default on package installation, they MUST be covered by the xref:DefaultServices.adoc[Fedora preset policy]. From a21071b51f7ecc56130f08cb77d1d84903a5ad96 Mon Sep 17 00:00:00 2001 From: Carl George Date: Sep 21 2023 20:32:45 +0000 Subject: [PATCH 101/232] Fix formatting in the "Requiring Base Package" section This section has some incorrect formatting and duplicate phrasing. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 3638c6a..cc030c2 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -1422,14 +1422,19 @@ not installed in a user runtime, e.g. gcc or gdb. 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}. +When a subpackage requires the base package, +it *MUST* do so using a fully versioned arch-specific +(for non-noarch packages) dependency: + +[source, rpm-spec] +---- +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}, +do not normally need to explicitly depend on their base packages 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 @@ -1437,15 +1442,6 @@ 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: - -[source, rpm-spec] ----- -Requires: %{name}%{?_isa} = %{version}-%{release} ----- - == Shared Libraries Whenever possible (and feasible), From b3c6bd15401e493cb05cbdf743f4c139030a84a4 Mon Sep 17 00:00:00 2001 From: Florian Weimer Date: Sep 29 2023 08:54:11 +0000 Subject: [PATCH 102/232] RPMMacros: Fix package name typo The package is called redhat-rpm-config, not redhat-rpm-macros. --- diff --git a/guidelines/modules/ROOT/pages/RPMMacros.adoc b/guidelines/modules/ROOT/pages/RPMMacros.adoc index d5e78a1..5c2549c 100644 --- a/guidelines/modules/ROOT/pages/RPMMacros.adoc +++ b/guidelines/modules/ROOT/pages/RPMMacros.adoc @@ -123,7 +123,7 @@ The `+%{optflags}+` macro contains flags that determine `CFLAGS`, `CXXFLAGS`, `FFLAGS`, etc. -- the `+%{__global_cflags}+` macro evaluates to the same string. The current definitions of these values -can be found in the `redhat-rpm-macros` package, in the {build-flags}. +can be found in the `redhat-rpm-config` package, in the {build-flags}. .... $ rpm --eval "%{optflags}" From f05cf4d31c88bf48869b190dc570e86f31883030 Mon Sep 17 00:00:00 2001 From: Fabio Valentini Date: Oct 11 2023 23:22:48 +0000 Subject: [PATCH 103/232] Rewrite Rust Packaging Guidelines (and drop outdated example specs) --- diff --git a/guidelines/modules/ROOT/examples/rust-ripgrep.spec b/guidelines/modules/ROOT/examples/rust-ripgrep.spec deleted file mode 100644 index ab20cff..0000000 --- a/guidelines/modules/ROOT/examples/rust-ripgrep.spec +++ /dev/null @@ -1,82 +0,0 @@ -# Generated by rust2rpm 15 -%bcond_without check -%global __cargo_skip_build 0 - -%global crate ripgrep - -Name: rust-%{crate} -Version: 12.1.1 -Release: 1%{?dist} -Summary: Line oriented search tool using Rust's regex library - -License: Unlicense OR MIT -URL: https://crates.io/crates/ripgrep -Source: %{crates_source} -# Initial patched metadata -# * No simd -# * No jemalloc -Patch: ripgrep-fix-metadata.diff - -BuildRequires: rust-packaging - -%global _description %{expand: -Line-oriented search tool that recursively searches your current directory for -a regex pattern while respecting your gitignore rules. ripgrep has first class -support on Windows, macOS and Linux.} - -%description %{_description} - -%package -n %{crate} -Summary: %{summary} -# * Apache-2.0-or-later or BSL-1.0 -# * Apache-2.0-or-later or MIT -# * MIT -# * MIT or Apache-2.0-or-later -# * Unlicense or MIT -License: MIT and (BSL-1.0 OR Apache-2.0-or-later) - -%description -n %{crate} %{_description} - -%files -n %{crate} -%license LICENSE-MIT UNLICENSE COPYING -%doc README.md CHANGELOG.md -%{_bindir}/rg -%{_mandir}/man1/rg.1* -%dir %{_datadir}/bash-completion -%dir %{_datadir}/bash-completion/completions -%{_datadir}/bash-completion/completions/rg.bash -%dir %{_datadir}/fish -%dir %{_datadir}/fish/vendor_completions.d -%{_datadir}/fish/vendor_completions.d/rg.fish -%dir %{_datadir}/zsh -%dir %{_datadir}/zsh/site-functions -%{_datadir}/zsh/site-functions/_rg - -%prep -%autosetup -n %{crate}-%{version_no_tilde} -p1 -%cargo_prep - -%generate_buildrequires -%cargo_generate_buildrequires -a -echo '/usr/bin/asciidoctor' - -%build -%cargo_build -a - -%install -%cargo_install -a -install -Dpm0644 -t %{buildroot}%{_mandir}/man1 \ - target/release/build/%{crate}-*/out/rg.1 -install -Dpm0644 -t %{buildroot}%{_datadir}/bash-completion/completions \ - target/release/build/%{crate}-*/out/rg.bash -install -Dpm0644 -t %{buildroot}%{_datadir}/fish/vendor_completions.d \ - target/release/build/%{crate}-*/out/rg.fish -install -Dpm0644 -t %{buildroot}%{_datadir}/zsh/site-functions \ - complete/_rg - -%if %{with check} -%check -%cargo_test -a -%endif - -%changelog diff --git a/guidelines/modules/ROOT/examples/rust-serde.spec b/guidelines/modules/ROOT/examples/rust-serde.spec deleted file mode 100644 index 9f7e445..0000000 --- a/guidelines/modules/ROOT/examples/rust-serde.spec +++ /dev/null @@ -1,145 +0,0 @@ -# Generated by rust2rpm 15 -# * RUSTC_BOOTSTRAP breaks tests -%bcond_with check -%global debug_package %{nil} - -%global crate serde - -Name: rust-%{crate} -Version: 1.0.116 -Release: 1%{?dist} -Summary: Generic serialization/deserialization framework - -# Upstream license specification: MIT OR Apache-2.0 -License: MIT OR Apache-2.0-or-later -URL: https://crates.io/crates/serde -Source: %{crates_source} - -%if %{__cargo_skip_build} -BuildArch: noarch -%endif - -BuildRequires: rust-packaging - -%global _description %{expand: -Generic serialization/deserialization framework.} - -%description %{_description} - -%package devel -Summary: %{summary} -BuildArch: noarch - -%description devel %{_description} - -This package contains library source intended for building other packages -which use "%{crate}" crate. - -%files devel -%license LICENSE-MIT LICENSE-APACHE -%doc README.md crates-io.md -%{cargo_registry}/%{crate}-%{version_no_tilde}/ - -%package -n %{name}+default-devel -Summary: %{summary} -BuildArch: noarch - -%description -n %{name}+default-devel %{_description} - -This package contains library source intended for building other packages -which use "default" feature of "%{crate}" crate. - -%files -n %{name}+default-devel -%ghost %{cargo_registry}/%{crate}-%{version_no_tilde}/Cargo.toml - -%package -n %{name}+alloc-devel -Summary: %{summary} -BuildArch: noarch - -%description -n %{name}+alloc-devel %{_description} - -This package contains library source intended for building other packages -which use "alloc" feature of "%{crate}" crate. - -%files -n %{name}+alloc-devel -%ghost %{cargo_registry}/%{crate}-%{version_no_tilde}/Cargo.toml - -%package -n %{name}+derive-devel -Summary: %{summary} -BuildArch: noarch - -%description -n %{name}+derive-devel %{_description} - -This package contains library source intended for building other packages -which use "derive" feature of "%{crate}" crate. - -%files -n %{name}+derive-devel -%ghost %{cargo_registry}/%{crate}-%{version_no_tilde}/Cargo.toml - -%package -n %{name}+rc-devel -Summary: %{summary} -BuildArch: noarch - -%description -n %{name}+rc-devel %{_description} - -This package contains library source intended for building other packages -which use "rc" feature of "%{crate}" crate. - -%files -n %{name}+rc-devel -%ghost %{cargo_registry}/%{crate}-%{version_no_tilde}/Cargo.toml - -%package -n %{name}+serde_derive-devel -Summary: %{summary} -BuildArch: noarch - -%description -n %{name}+serde_derive-devel %{_description} - -This package contains library source intended for building other packages -which use "serde_derive" feature of "%{crate}" crate. - -%files -n %{name}+serde_derive-devel -%ghost %{cargo_registry}/%{crate}-%{version_no_tilde}/Cargo.toml - -%package -n %{name}+std-devel -Summary: %{summary} -BuildArch: noarch - -%description -n %{name}+std-devel %{_description} - -This package contains library source intended for building other packages -which use "std" feature of "%{crate}" crate. - -%files -n %{name}+std-devel -%ghost %{cargo_registry}/%{crate}-%{version_no_tilde}/Cargo.toml - -%package -n %{name}+unstable-devel -Summary: %{summary} -BuildArch: noarch - -%description -n %{name}+unstable-devel %{_description} - -This package contains library source intended for building other packages -which use "unstable" feature of "%{crate}" crate. - -%files -n %{name}+unstable-devel -%ghost %{cargo_registry}/%{crate}-%{version_no_tilde}/Cargo.toml - -%prep -%autosetup -n %{crate}-%{version_no_tilde} -p1 -%cargo_prep - -%generate_buildrequires -%cargo_generate_buildrequires - -%build -%cargo_build - -%install -%cargo_install - -%if %{with check} -%check -%cargo_test -%endif - -%changelog diff --git a/guidelines/modules/ROOT/examples/rust-yubibomb.spec b/guidelines/modules/ROOT/examples/rust-yubibomb.spec deleted file mode 100644 index cdd5476..0000000 --- a/guidelines/modules/ROOT/examples/rust-yubibomb.spec +++ /dev/null @@ -1,85 +0,0 @@ -# Generated by rust2rpm 13 -%bcond_without check - -%global crate yubibomb - -Name: rust-%{crate} -Version: 0.2.1 -Release: 1%{?dist} -Summary: Rust command line tool that prints out a 6-digit random number - -License: GPL-3.0-only -URL: https://crates.io/crates/yubibomb -Source: %{crates_source} - -%if %{__cargo_skip_build} -BuildArch: noarch -%endif - -BuildRequires: rust-packaging - -%global _description %{expand: -Don't you love when you accidentally tap your Yubikey when you have your IRC -client in focus and you send 987947 into Freenode? Want to be able to have that -experience without having to reach all the way over to your laptop's USB port? -Now you can!.} - -%description %{_description} - -%if ! %{__cargo_skip_build} -%package -n %{crate} -Summary: %{summary} - -%description -n %{crate} %{_description} - -%files -n %{crate} -%license LICENSE -%doc README.md -%{_bindir}/yubibomb -%endif - -%package devel -Summary: %{summary} -BuildArch: noarch - -%description devel %{_description} - -This package contains library source intended for building other packages -which use "%{crate}" crate. - -%files devel -%license LICENSE -%doc README.md -%{cargo_registry}/%{crate}-%{version_no_tilde}/ - -%package -n %{name}+default-devel -Summary: %{summary} -BuildArch: noarch - -%description -n %{name}+default-devel %{_description} - -This package contains library source intended for building other packages -which use "default" feature of "%{crate}" crate. - -%files -n %{name}+default-devel -%ghost %{cargo_registry}/%{crate}-%{version_no_tilde}/Cargo.toml - -%prep -%autosetup -n %{crate}-%{version_no_tilde} -p1 -%cargo_prep - -%generate_buildrequires -%cargo_generate_buildrequires - -%build -%cargo_build - -%install -%cargo_install - -%if %{with check} -%check -%cargo_test -%endif - -%changelog diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc index db66eff..09ee8a0 100644 --- a/guidelines/modules/ROOT/pages/Rust.adoc +++ b/guidelines/modules/ROOT/pages/Rust.adoc @@ -1,374 +1,870 @@ = Rust Packaging Guidelines -:last-reviewed: 2022-08-23 -== rust2rpm - -Note that the https://pagure.io/fedora-rust/rust2rpm[*rust2rpm*] tool -(packaged as `python3-rust2rpm` for Fedora) -automates most of the steps that are necessary for creating `+.spec+` files for Rust crates. - -It is advisable to try `+rust2rpm -s $crate+` first, -and to only modify its output for your needs, -before attempting to write a `+.spec+` file by hand. -Most of the time, `+rust2rpm+` output can be used almost without modifications. - -However, there are a few common situations -in which manual edits of the generated `+.spec+` file -or patches for upstream `+Cargo.toml+` files (with `+rust2rpm -p+`) -are required, for example: - -* trimming a generated `+Summary+` tag that is too long -* dropping non-linux platform-specific dependencies (automated by rust2rpm v22+) -* dropping features that are only supported by nightly builds of the Rust compiler -* dropping unstable features that require manually overriding compiler flags -* dropping *unused* optional features with missing dependencies - (can be automated by using a `+rust2rpm.conf+` configuration file) - -== Package Sources - -Only library crates that are published on crates.io MAY be packaged for Fedora, -since this enforces a certain standard of how crates are packaged and built, -ensures that all the crate's dependencies are available from crates.io as well, -and that there are no package name collisions -due to the unique crate names in the crates.io namespace. - -Crates that contain only an application but no library interface -MAY be packaged even if they are not published on crates.io, -because those packages are leaves -and cannot be depended on by other Rust crates. - -Complex projects with multiple components (i.e. bindings for other languages), -which cannot be packaged from sources that are published on crates.io alone, -MAY include subpackages for their Rust library interface -(`+rust-$crate-devel+`, `+rust-$crate+feature-devel+`, etc.) -ONLY if this crate is also published on crates.io under the same name. - -== Package Naming - -=== Library crates - -Source packages for Rust crates which contain a library with a public API -MUST be named `rust-$crate`. - -=== Mixed library / application crates - -Source packages for Rust crates -which contain both a library with a public API *and* an application -MUST be named `rust-$crate` -(i.e. follow the rules for library crates). - -NOTE: The convention set by `rust2rpm` for the name of the subpackage - that contains the application binary (or binaries) - is to use the name of the crate itself. - However, in some cases, - the crate name does not match the name of the built application(s), - and in this case the subpackage name SHOULD be adjusted - to match expectations. - -=== Application-only crates - -Packages for application-only crates that are published on crates.io -MUST NOT drop the `+rust-+` prefix from their source package names, -because a crate can start to include a public library API at any time, -in which case the "Mixed library / application crates" rules would apply, -and the package would need to be renamed to include the `+rust-+` prefix. - -Application-only Rust projects which are not packaged from crates.io -must follow the general xref:Naming.adoc[Naming Guidelines] -(i.e. drop the `+rust-+` prefix from the source package name) -so that they cannot introduce potential source package name collisions -with crates from the crates.io namespace. - -NOTE: `rust2rpm` does not support generating `.spec` files - for packages without a `+rust-+` name prefix yet. - In this case, `.spec` files written by `rust2rpm` - will need to be manually edited after each update. - -== Package sources - -The primary Source for library crates -- that MUST be published on crates.io -- -MUST be specified as `+%{crates_source}+`, -which uses the `+%{crate}+` and `+%{version}+` macros to calculate the download URL. - -Application crates do not have to be published on crates.io, -so only the general Guidelines for Sources apply. - -In the case that crates published to crates.io are missing files -(`.desktop` files for GUI applications, manual pages, default configuration files, etc.), -they MAY be included from the upstream sources, -but the packager SHOULD query upstream to include those missing files in their published crates. - -== Package Dependencies - -All Rust packages MUST include `+BuildRequires: rust-packaging >= 21+`. - -However, if the package is for a Rust crate -whose `+Cargo.toml+` metadata uses syntax for feature dependencies -which was added with Rust 1.60, -i.e. *namespaced dependencies* (`+"dep:foo"+`) -or *weak dependency features* (`+"foo/bar"+`), -it MUST include `+BuildRequires: cargo-rpm-macros >= 24+` instead, -since support for this syntax was only added -as part of a complete rewrite of `+rust-packaging+` -that was shipped as `+cargo-rpm-macros+` version 24. - -=== Bundled Dependencies - -NOTE: As stated in the general xref:index.adoc#bundling[Packaging Guidelines], - packages MUST be built against system libraries, if that is possible. - For Rust, this means that packages MUST NOT use dependencies from a "vendor tarball" - (e.g. created by running `+cargo vendor+`), - but package all library dependencies separately. - -However, two common reasons that can make building a package -against system libraries (crates) basically impossible are -if a crate applies downstream patches on top of its dependencies, -or if it depends on "internal" crates that are not published on crates.io. -In these circumstances, packagers MAY use bundled dependencies, -but - if possible - SHOULD work with upstream to, for example, -make their downstream patches unnecessary, or publish internal crates. - -If bundled dependencies are used to build a binary package, -the subpackage that will contain the compiled binary -MUST have `+Provides: bundled(crate(foo)) = version+` for each bundled crate -and the packager MUST keep this list of crates and their versions up-to-date -every time the package or its bundled dependencies are updated. - -=== Automatic Dependency Generation - -The RPM packaging machinery for Rust crates -automatically generates Requires and Provides -based on cargo metadata in `+%{cargo_registry}/*/Cargo.toml+` files. - -The Provides generator creates: - -* `crate($name) = $version` for base package (`rust-$name-devel`) -* `crate($name/$feature) = $version` for feature subpackages (`rust-$name+$feature-devel`) - -The Provides / Requires generator relies on empty subpackages with special names -for encoding the dependency information of optional features. -These subpackages MUST be named `+rust-%{crate}+$FEATURE-devel+` -for all features that are present in `Cargo.toml` after patching this file in `+%prep+`. - -NOTE: These feature subpackage definitions are automatically correctly generated - when using `+rust2rpm+` (if necessary, with the `-p` flag to apply any initial changes). - -The dependency generator then creates `Requires` for all features that a crate depends on. -For example, a dependency on `syn` with the `visit` and `extra-traits` features - -.... -syn = { version = "0.15", features = ["visit", "extra-traits"] } -.... - -will be encoded as - -.... -Requires: (crate(syn/default) >= 0.15.0 with crate(syn/default) < 0.16.0) -Requires: (crate(syn/extra-traits) >= 0.15.0 with crate(syn/extra-traits) < 0.16.0) -Requires: (crate(syn/visit) >= 0.15.0 with crate(syn/visit) < 0.16.0) -.... - -where the `default` feature of `syn` is also included, -because the `default-features=false` option was not specified. - -=== BuildRequires +:last-reviewed: 2023-10-12 + +https://www.rust-lang.org[Rust] is a strongly and statically typed, +compiled programming language +that supports concepts from both imperative and functional programming. + +Because there is not yet a stable Rust ABI, +and because conditional compilation is a widely used feature in the Rust ecosystem, +Rust libraries ("crates") can not be distributed in compiled form, +and are instead distributed as source code. + +This document covers how to handle Rust code in packages, +specific to the different ways in which projects can be set up: + +* link:#_rust_crates[Rust "crates"]: + packages that are individually published on https://crates.io[crates.io], + the official package registry for Rust + (primarily libraries, but also "single-crate" applications) +* Rust link:#_rust_applications_non_crates_io_crates[applications that are single crates but not published on crates.io] +* Rust projects that are organized as link:#_rust_applications_cargo_workspace_projects[cargo "workspaces"]: + usually larger projects with "internal" crates, + which are often not separately published on https://crates.io[crates.io] +* link:#_python_projects[Python projects] with a "native" component implemented in Rust: + usually built with https://github.com/PyO3/setuptools-rust[setuptools_rust] or https://github.com/PyO3/maturin[maturin] +* link:_mixed_rust_cc_projects[mixed Rust / C/C++ projects] where parts of the project are implemented in Rust: + either built by wrapping cargo, + or by utilizing https://mesonbuild.com/Rust.html[meson]’s limited support + for directly building Rust code + +For the first three of these cases, +the https://pagure.io/fedora-rust/rust2rpm[rust2rpm] tool can be used +to generate spec files from cargo / crate metadata. +It is designed to produce spec files +that are in line with the (Rust) Packaging Guidelines. + +There are also guidelines for link:#_building_shared_libraries_with_cargo_c[packaging shared libraries] +that are implemented in Rust +(usually built and installed with https://crates.io/crates/cargo-c[cargo-c]). + +== Generic rules + +This section covers rules that apply to _all_ packages that ship Rust code. + +=== Compiler flags + +Similarly to other language ecosystems in Fedora, +there is a standardized set of compiler flags +that *MUST* be passed to the Rust compiler. + +The defaults for Rust are defined in the `%build_rustflags` macro +from the `rust-srpm-macros` package. +It is part of the default buildroot on Fedora 39+, +where the `%set_build_flags` macro automatically sets the `$RUSTFLAGS` environment variable +based on this macro. + +For compatibility with older releases, +this environment variable can be set manually at the start of `%build` and `%check` +in package’s spec files: + +[source,shell] +---- +export RUSTFLAGS="%build_rustflags" +---- -Rust packages SHOULD use automatic generation of `BuildRequires` -by including this scriptlet between `+%prep+` and `+%build+`: +This is not necessary for packages that use the `%cargo_prep`, `%cargo_build`, and `%cargo_test` macros, +which configure `cargo` to use the default `%build_rustflags` directly. + +=== Mandatory `BuildRequires` + +The RPM macros that provide basic functionality +for building Rust code are included in `rust-rpm-macros`, +which is part of the default buildroot in Fedora, +as it is a dependency of `redhat-rpm-config`. +When building for ELN or EPEL8, this is not the case, +and packages need to use `BuildRequires: rust-toolset`. + +Packages that build Rust code with cargo – directly or indirectly – +or which call any of the `%cargo_*` macros, +*MUST* add `BuildRequires: cargo-rpm-macros >= 24`, +which provides the implementations of all `%cargo_*` macros. +This package is not part of the default buildroot, +since it pulls in additional dependencies +(i.e. a Python interpreter). + +For backwards compatibility, +packages *MAY* instead depend on earlier versions of the `%cargo_*` macros, +which were provided in the `rust-packaging` package, +if they do not depend on any of the features or macros +that are only available with newer versions. +When generating a spec file for a crate with https://pagure.io/fedora-rust/rust2rpm[rust2rpm], +it will automatically detect usage of these features, +and include the necessary `BuildRequires` +for the RPM macro package automatically. + +=== License tags + +Similar to other languages that produce statically linked binaries, +Rust executables (and shared libraries) contain code +that originates in other packages +(i.e. packages for other Rust crates), +which in turn are covered by different license terms. + +This needs to be taken into account +by maintaining a separate `License` tag +for the subpackage that contains these binaries. +More information about `License` tags is available from the link:[Fedora Legal docs]. + +The `cargo-rpm-macros` package provides two RPM macros +that help with filling the `License` tag correctly: + +- `%cargo_license_summary` + +This macro determines and prints a summary +of all the licenses of the Rust crates +that end up statically linked into final binaries +(properly excluding build-only or test-only dependencies). +This summary can then be copied from the build log +into the spec file as a comment. +The actual contents of the `License` tag can then be obtained +by constructing a conjunction of these individial licenses (with SPDX `AND` operators). + +- `%cargo_license` + +This macro determines and prints a complete breakdown of all Rust crates +that end up statically linked into final binaries +(according to the same logic as in the `%cargo_license_summary` macro), +their versions, _and_ their individual license expressions. +Generating this list dynamically at build-time +ensures that its contents always match the actual dependencies. + +Both macros accept the same arguments +as all other `%cargo_*` macros (`-a`, `-n`, `-f`), +and for their output to match the actual binaries, +the same flags need to be passed to them and `%cargo_build`. + +=== Vendored dependencies + +https://docs.fedoraproject.org/en-US/packaging-guidelines/#bundling[In general], +packages *SHOULD NOT* use bundled crate dependencies, +whenever possible. + +Whenever vendored / bundled crate dependencies _are_ used +(no matter which mechanism is used for the purpose), +all bundled crate dependencies *MUST* be declared +with virtual `Provides` in the format `Provides: bundled(crate($crate)) = $version` +in the subpackage that contains the Rust component. +For example, these virtual `Provides` are used to determine +the impact of security vulnerabilities on packages +that use vendored Rust dependencies. + +Building exclusively from vendored dependencies +by using a tarball that was generated by running `cargo vendor` +*SHOULD* only be a last resort. +However, there are also two _rare_ situations +in which bundling at least _some_ Rust crates is likely unavoidable. + +==== Replacing git dependencies + +One of the types of dependencies cargo supports are git snapshots, +which are usually used to reference either a specific commit, +or a reference to a downstream fork of a crate. + +The project *SHOULD* be patched to use a version of this crate +that is available on https://crates.io[crates.io] instead, +if that is possible. +If it turns out that depending on a git snapshot is no longer necessary, +this patch *SHOULD* be submitted to the upstream project. + +If the dependency is not published on https://crates.io[crates.io], +or if the versions published there are not a suitable replacement, +a git snapshot of the crate can be bundled. +This can be achieved by creating and supplying a tarball +with the git snapshot as a separate source, +unpacking the tarball in `%prep`, +and patching `Cargo.toml` to replace the git-based dependency +with a path-based dependency. + +==== Replacing patched crate sources + +Another way in which cargo supports specifying modified dependencies is +by "patching" a crate source, +specifying an alternative source for specific crates – +which will likely be either git references or path-based dependencies +that are present to override a crate +that is published on https://crates.io[crates.io] with a (modified) local copy, +or a git repository that points to a (modified) fork of the crate. + +These replacements *SHOULD* be dropped +in favor of using only published versions of crates. +If that is not possible, +they must be replaced by path-based dependencies, +similar to the process described for link:#_replacing_git_dependencies[git-type dependencies]. + +==== Using vendor tarballs + +Official support for building with vendored dependencies +was added in version 25 of cargo-rpm-macros and rust2rpm. + +* The `%cargo_prep` macro accepts a `-v $VENDOR` argument, + where `$VENDOR` is the path to the directory + that contains the vendored crate dependencies. + When this argument is passed, + the generated cargo configuration is set up + for building against dependencies in this directory + instead of dependencies from the system-wide registry. +* The `%cargo_generate_buildrequires` macro *MUST NOT* be called + when using vendored dependencies. +* The `%cargo_vendor_manifest` macro generates a manifest (`cargo-vendor.txt`) + that lists the names and versions of all crates in the vendor tarball. + This macro *MUST* be called (for example, in the `%build` scriptlet), + and the generated file *MUST* be added as a `%license` file + in the appropriate package’s list of `%files`. + An RPM generator parses this file + and generates appropriate virtual `Provides` for all bundled crates, + as is required for any bundled dependencies. + +Typically, the `%prep` scriptlet will look like this +when using vendored dependencies +(assuming `Source1` is the vendor tarball, +and it contains a top-level `vendor` directory): + +[source,rpm] +---- +%prep +%autosetup -%{crate}-%{version} -p1 -a1 +%cargo_prep -v vendor +---- -.... -%generate_buildrequires -%cargo_generate_buildrequires -.... +The necessary spec file adaptations +and the generation of the vendor tarball itself +happen automatically when running rust2rpm in "vendor" mode. -This will automatically generate the necessary `BuildRequires` based on the `Cargo.toml` file. -This step runs *after* `+%prep+`, so any modification of `Cargo.toml` -(for example, after applying patches to remove dependencies or to modify versions of dependencies) -will be taken into account. +== rust2rpm -If using `+%cargo_generate_buildrequires+` is not possible, -`BuildRequires` MUST be specified manually and kept up-to-date with each package update: +The recommended way to write spec files for Rust projects +is to use https://pagure.io/fedora-rust/rust2rpm[rust2rpm], +and apply any necessary modifications on top of the generated spec file. + +There are a few common situations +in which automatically generated spec files +need manual changes: + +* invalid `Summary` / `%description`: + The heuristics for generating the `Summary` or `%description` for the package + from the crate metadata can fail to produce valid values + (i.e. `Summary` tag that is too long). + In this case, the `Summary` needs to be shortened manually. + This can also be overridden + in the package-specific rust2rpm configuration file. +* unwanted dependencies / subpackages: + Some crates provide non-default / optional features + that are either unnecessary + (i.e. only applicable to non-Linux systems), + or have additional dependencies + that are not packaged for Fedora. + These features and unavailable optional dependencies *MUST* + be removed from crate metadata – otherwise, + the package will either fail to build, + or produce subpackages with broken dependencies. +* nightly-only / unstable features: + Some crates provide features + that are only available on a nightly version of the Rust compiler, + or features that are unstable and require an opt-in + by passing environment variables. + Features like these *SHOULD* be removed from crate metadata, + since they either cannot work + (Fedora ships only the stable Rust toolchain) + or are not feasible to support. +* unwanted / unnecessary files ("bloat"): + Some projects include files + that are not required for the crate to function properly + (files for CI settings, development / helper scripts, etc.). + Files like these *SHOULD* be prevented from being installed + (by adding / modifying the `package.include` + or `package.exclude` settings in the crate metadata). + It is recommended to submit changes like this to the upstream project. +* incompatible compiler flags: + Some crates include custom settings for the `release` profile + that are incompatible with RPM packaging. + These settings *MUST* be removed from the `release` profile + by patching `Cargo.toml`. + +Crates that provide Rust bindings for C libraries +usually require some additional changes (if possible): + +* linking against system libraries: + This often requires making some dependencies non-optional and / or + modifying `build.rs` scripts to unconditionally link against system libraries + instead of building and statically linking a bundled copy of the library. +* regenerating Rust bindings (and tests for them) at build-time: + This too often requires making the `bindgen` dependency non-optional and / or + modifying `build.rs` to cause regeneration of Rust bindings at build-time. + +Note that patching `Cargo.toml` files +(especially changing the set of optional dependencies and features) +*MUST* be done by running `rust2rpm -p`, +since changes like these affect spec file generation +(i.e. the list of generated subpackages), +which is only correctly taken into account +if the patch is created _before_ generation of the spec file. + +== Rust crates + +A large part of the process of packaging Rust crates +can (and _should_) be automated by using https://pagure.io/fedora-rust/rust2rpm[rust2rpm]. +It is designed to generate spec files that are compliant +with both the general and the Rust Packaging Guidelines. + +Additionally, due to some properties of packages for Rust crates +(i.e. subpackages that correspond to crate features / optional dependencies), +it is necessary to re-run https://pagure.io/fedora-rust/rust2rpm[rust2rpm] +for every new version of a crate +to ensure that generated feature subpackages +stays in sync with crate metadata. + +=== Package naming + +The canonical source of Rust crates is https://crates.io[crates.io]. + +Rust crates that are published on https://crates.io[crates.io] +*MUST* be packaged with `rust-$crate` as the name of the source package +(where `$crate` is the name of the project on https://crates.io[crates.io]). +Packages for Rust crates that are generated with https://pagure.io/fedora-rust/rust2rpm[rust2rpm] +follow to this pattern. + +On the other hand, +projects from other sources *MUST NOT* use the `rust-` prefix for source package names, +and *MUST* follow the general Naming Guidelines instead. +They also *MUST NOT* have any virtual `Provides` for Rust crates +(i.e. `Provides: crate(%{crate}) = %{version}`). + +When generating a package for a Rust crate +that also (or exclusively) contains an application, +the convention followed by https://pagure.io/fedora-rust/rust2rpm[rust2rpm] is +to generate a subpackage with a name that matches the crate’s name +(i.e. the `rust-$crate` source package will have a `$crate` subpackage). +If this name does not match expectations, +it is recommended to either change the name of this subpackage, +or to add virtual `Provides` for the expected name. + +=== Package versioning + +Projects that are built with cargo and / or published on https://crates.io[crates.io] +follow Semantic Versioning (with small cargo-specific tweaks). +Since SemVer strings can contain characters that are invalid in RPM version strings, +they *MUST* be translated to be RPM-compatible. + +For example, pre-releases are denoted by a `-
` suffix in SemVer,
+but the `-` character is invalid in RPM Versions.
+This can be solved by replacing `-` with the `~` character,
+which denotes pre-releases in RPM version strings.
+This translation happens automatically for the `Version` tag
+when generating a spec file with https://pagure.io/fedora-rust/rust2rpm[rust2rpm],
+and the "upstream" version is stored in a separate macro
+that can be used to refer to the "original" version string.
+
+Additionally, some Rust crates carry extra "build" metadata in their versions
+(a `+` suffix).
+This format is primarily used to carry information
+about the version of a bundled C library.
+This `+` suffix *MUST* be removed from crate metadata with a patch,
+since it can interfere with RPM dependency / version resolution.
+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).
+
+If the sources published on https://crates.io[crates.io]
+do not contain all files that are necessary for creating the package
+(for example, missing `.desktop` file or man pages),
+the upstream sources can be used as an _additional_ source,
+but they *MUST NOT* be used for building the crate itself.
+It is recommended to file an issue with the upstream project
+about including these additional files in published crates.
+
+If a crate is also part of a larger project
+and it is not feasible to package the Rust crate separately,
+the Rust crate *MAY* be packaged as `rust-$crate` from different sources
+(i.e. an upstream tarball) _if and only if_ the crate is also published on https://crates.io[crates.io]
+under the same name and with matching versions.
+In this case, the subpackage(s) corresponding to Rust crates
+*MUST* have correct virtual `Provides` for the Rust crate.
+
+=== Crate license
+
+Most tooling support for determining licenses
+requires accurate metadata about licenses in crate metadata,
+including the `%cargo_license*` macros,
+and other third-party tools like `cargo-license` and `cargo-deny`.
+
+For this reason, the license metadata for all Rust crates packaged for Fedora
+*MUST* match the license tag of the Fedora package itself.
+Any crates that set `package.license-file` in their metadata
+(which is reserved for non-standard / non-SPDX licenses)
+*MUST* be patched to set `package.license` in their metadata instead
+in cases where this is _not_ appropriate
+and an accurate SPDX expression can be provided.
+Patches like this *SHOULD* be submitted upstream.
+
+=== RPM macros
+
+The process of building and installing Rust crates
+is almost entirely automated with several RPM macros:
+
+* `%cargo_prep`:
+  This macro *MUST* be called in the `%prep` scriptlet
+  after sources have been unpacked.
+  It sets up the build environment for cargo
+  and injects a cargo configuration file,
+  which sets the default compiler flags
+  and configures the local crate registry
+  as a replacement for https://crates.io[crates.io].
+* `%cargo_generate_buildrequires`:
+  This macro *MUST* be called in the `%generate_buildrequires` scriptlet,
+  except when building with vendored dependencies.
+  This is the mechanism that automatically generates depepdencies on other Rust crates
+  based on the metadata in `Cargo.toml`.
+* `%cargo_build`:
+  This macro *MUST* be called in the `%build` scriptlet.
+  It runs `cargo build` with the appropriate command line arguments.
+  Calling this macro *MAY* be skipped
+  if the crate is not supported on the current CPU architecture.
+* `%cargo_install`:
+  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}/`).
+  For crates that provide `bin` targets,
+  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
+  with manual installation steps.
+* `%cargo_test`:
+  This macro *MUST* be called in the `%check` scriptlet.
+  It runs `cargo test` with the appropriate command line arguments.
+  Calling this macro *MAY* be skipped
+  if the crate is not supported on the current CPU architecture
+  or if tests are disabled in general.
+* `%cargo_license` / `%cargo_license_summary`:
+  These macros *MUST* be called in the `%build` scriptlet after `%cargo_build`
+  when building crates that include binary targets.
+  They can be used to print the list of the licenses
+  of the crates that are statically linked into any built executable
+  or shared library (see link:#_license_tags[License tags]).
+
+All packages for Rust crates *MUST* set
+either `%bcond_without check` or `%bcond_with check`.
+The value of this macro affects the behaviour of `%cargo_generate_buildrequires`.
+
+All `%cargo_*` macros (except `%cargo_prep`)
+accept a set of optional flags / arguments
+that can be used to control the feature flags that are passed to cargo
+(usually to enable optional / non-default features):
+
+* `-a`:
+  Causes the `--all-features` flag to be passed to cargo,
+  and the `%cargo_generate_buildrequires` macro
+  to resolve dependencies with all optional features enabled.
+* `-n`:
+  Causes the `--no-default-features` flags to be passed to cargo,
+  and the `%cargo_generate_buildrequires` macro
+  to resolve dependencies with all default and optional features disabled.
+* `-f foo,bar`:
+  Causes the `--features foo,bar` argument to be passed to cargo,
+  and the `%cargo_generate_buildrequires` macro
+  to resolve dependencies with the additional features `foo` and `bar` enabled.
+  This argument accepts a comma-separated list of feature names
+  (or names of optional dependencies).
+
+The `-a` and `-n` flags are mutually exclusive
+and cannot be passed together.
+The `-a` flag and `-f` arguments are also incompatible,
+since passing `-a` already enables all features.
+However, using the `-n` flag and specifically enabling _some_ features
+with the `-f` argument is valid.
+
+There are some common situations
+in which passing these flags or arguments is necessary:
+
+* It can be necessary to enable additional features and / or optional dependencies
+  to build and run the test suite of a crate.
+  In this case, the required features *MUST* be enabled
+  by passing the corresponding flags to all `%cargo_*` macros,
+  unless the required optional dependencies are not packaged yet.
+* Some applications support additional / non-default features
+  by passing feature flags.
+  If it is desirable to build applications with these features enabled,
+  the required features need to be enabled
+  by passing the corresponding flags to all `%cargo_*` macros
+  (including `%cargo_license` and `%cargo_license_summary`).
+
+Note that the `-n` flag should only be used in exceptional circumstances,
+and *MUST NOT* be used to avoid missing dependencies
+that are part of the `"default"` feature set of a crate.
+
+=== Dynamically generated `BuildRequires` for crate dependencies
+
+With Semantic Versioning (_"SemVer"_) being
+the only supported versioning scheme for Rust crates,
+dependencies on Rust libraries are almost exclusively specified as
+_"this version or any newer version that is API-compatible with it"_,
+i.e. a range of supported versions.
+
+These ranges of supported versions
+need to be correctly translated into RPM dependencies,
+otherwise a wrong version of a dependency might get pulled in for builds,
+causing unhelpful error messages about missing dependencies.
+
+Since dependencies of Rust projects often change with every new release,
+and keeping a list of `BuildRequires` up-to-date manually is tedious and error-prone,
+packages for projects that build Rust code with cargo
+*MUST* use dynamically generated `BuildRequires`
+by calling the `%cargo_generate_buildrequires` macro
+in the `%generate_buildrequires` scriptlet.
+
+For example, a dependency on `serde = "1.0.100"`
+specified in a project's `Cargo.toml` metadata
+(a dependency on the crate named "serde",
+with version "1.0.100" or any version API-compatible with "1.0.100",
+with default features enabled)
+would cause a dependency like this to be generated for RPM:
 
 ....
-[dependencies]
-atty = "0.2.2"
-[build-dependencies]
-clap = "2.24.1"
+BuildRequires:  (crate(serde/default) >= 1.0.100 with crate(serde/default) < 2.0.0~)
 ....
 
-should become
+Refer to the section about link:#_rpm_macros[RPM macros]
+for how to pass feature flags to this macro.
+
+Issues with the `%cargo_generate_buildrequires` macro
+that prevent it from being used for a package
+should be reported against https://pagure.io/fedora-rust/cargo2rpm[cargo2rpm],
+the tool that provides the functionality of this macro.
+
+=== Subpackages for crate features
+
+Optional features / dependencies of Rust crates are translated into RPM subpackages
+to support resolving dependencies for features and optional dependencies of crates.
+The list of crate "features"
+(including any implicitly defined features for optional dependencies)
+*MUST* be kept in sync with the list of subpackages,
+i.e. for every feature `$foo` of the crate `$crate`,
+there must be a subpackage with name `rust-$crate+$foo-devel`,
+and vice-versa.
+This is required for RPM generators for `Provides` and `Requires`
+for these optional features / dependencies to work correctly.
+
+If optional features that are _not_ part of the default feature set
+are unused and would pull in additional (possibly unavailable) dependencies,
+the package *MAY* omit subpackages for these specific feature names.
+However, care needs to be taken
+that the features corresponding to the ommitted subpackages
+are not "reachable" via subpackages that have _not_ been omitted,
+since this would result in packages with unsatisfiable dependencies.
+Disabling optional features sometimes cannot be handled correctly
+simply by omitting subpackages for specific features.
+In these cases, the crate metadata in `Cargo.toml`
+needs to be patched accordinly instead.
+
+Beware that the "default" feature is always implicitly defined by cargo,
+even if the crate metadata does not contain a `[features]` table
+or an explicitly defined "default" feature,
+so the subpackage for the "default" feature
+will be present in all packages for Rust crates with a library interface.
+
+=== RPM generators for `Provides` and `Requires`
+
+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}`).
+
+It is recommended to verify
+that the generated `Provides` and `Requires` are sane – for example,
+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}`
+* the `rust-$crate+$feature-devel` subpackages
+  *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:
+
+* the main `rust-$crate-devel` subpackage
+  *MUST* require the virtual `Provides` for all non-optional crate dependencies
+* the `rust-$crate+$feature-devel` subpackages
+  *MUST* require the virtual `Provides` for the optional crate dependencies
+  and features that are listed as the feature’s dependencies in crate metadata
+
+=== Packaging multiple versions
+
+In most circumstances,
+the latest version of a crate *SHOULD* be packaged,
+and – if possible – packagers *SHOULD* port crates
+to use the latest available version of their dependencies,
+and submit these patches to upstream
+to limit divergence between the upstream project and the Fedora package.
+
+However, there are two common scenarios
+in which it is often necessary to provide packages
+for multiple versions of a library crate simultaneously:
+
+* It is not feasible to port a crate
+  to the version of a crate dependency in Fedora
+  due to large API changes between the required and the packaged version.
+* The number of packages affected
+  by a required SemVer-incompatible library update is very large.
+
+In these cases, a "compat package" can be created for the older version
+(i.e. usually the current version),
+and the suffix-less package can be updated to the newer version.
+https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
+supports automatically creating "compat packages"
+with names that are compliant with the
+https://docs.fedoraproject.org/en-US/packaging-guidelines/Naming/#multiple[Naming Guidelines for this case]
+_and_ compatible with the restrictions of Semantic Versioning
+by using the `rust2rpm --compat` flag.
+
+All "compat packages" for Rust crates
+*MUST* follow the guidelines for Rust crates,
+and two additional rules apply when creating them:
+
+* For crates that also includes an executable,
+  only the package for the _latest_ version can include this executable,
+  and it *MUST NOT* be built and included in any older versions,
+  to prevent both the name of the executable under `/usr/bin`
+  and the name of the subpackage would conflict
+  between the old and the new version of the package.
+* The packager *SHOULD* check
+  whether running tests in the old version of the crate
+  would cause additional, potentially undesirable dependencies,
+  for example, older versions of other dependencies
+  that would require creating additional "compat packages" –
+  in this case, tests *SHOULD* be disabled
+  (i.e. by flipping the `check` bcond).
+
+=== The `check` bcond
+
+The behaviour of some RPM macros
+depends on the presence and value of the `_with_check` macro,
+i.e. if `%bcond_without check` or `%bcond_with check`
+are used in the spec file – notably,
+the `%cargo_generate_buildrequires` macro only includes `dev-dependencies`
+(i.e. dependencies that are only used
+for compiling and / or running a project’s test suite with cargo)
+if the `check` bconf is enabled.
+
+Additionally, packages for Rust crates or workspace projects
+that are generated by https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
+use the value of this macro to determine if the `%check` scriptlet is run.
+
+Packages *MUST* set this bcond
+to avoid unexpected behaviour of the `%cargo_*` macros,
+by either explicitly _enabling_ or _disabling_ tests.
+
+=== Running tests
+
+Rust crates can have three different kinds of tests in their test suites:
+
+* _"unit tests"_:
+  These tests are included
+  alongside library / application source code in the `src/` directory,
+  and can reference private APIs
+  (similar to "glass-box" tests).
+* _"integration tests"_:
+  These tests are usually separate files under the `tests/` directory,
+  and they can only rely on public API of the tested crate
+  (similar to "black-box" tests).
+* _"doctests"_:
+  These tests are automatically extracted
+  from code blocks in Markdown documentation,
+  which is often used as a mechanism
+  to ensure that code snippets in documentation for public methods
+  are correct and continue to compile.
+
+By default, running `cargo test` (i.e. by calling the `%cargo_test` macro),
+all three kinds of tests are run.
+They can also be invoked separately
+(for example, because parts of the test suite or large data files are
+not included in published sources)
+by passing through filtering arguments
+to the underlying `cargo test` command:
+
+* `%cargo_test -- --lib`: only run _"unit tests"_ for the library interface
+* `%cargo_test -- --bin`: only run _"unit tests"_ for binaries
+* `%cargo_test -- --doc`: only run _"doctests"_
+* `%cargo_test -- --tests`: only run _"integration tests"_
+
+This can be combined with additional flags
+to skip tests with specific names
+(or that contain a specific string in their name)
+by passing the `--skip` argument through to the test harness
+(can be specified multiple times):
 
 ....
-BuildRequires:  (crate(atty/default) >= 0.2.2 with crate(atty/default) < 0.3.0)
-BuildRequires:  (crate(clap/default) >= 2.24.1 with crate(clap/default) < 3.0.0)
+%cargo_test -- --lib -- --skip foo::bar::tests::test1
 ....
 
-== Crate Versions
-
-* Packagers SHOULD package the latest version of a crate.
-* Packagers SHOULD patch crates to use the latest version of their dependencies,
-  to reduce the downstream maintenance burden and the need for compat packages.
-* When introducing patches to bump the version of dependencies,
-  packagers SHOULD forward these patches to the upstream project
-  to keep the divergence between downstream and upstream small over time.
-
-CAUTION:    Some crates are published with additional information
-            encoded into their version string.
-            For example, Rust bindings for native libraries
-            might add a `+x.y.z`-style suffix to indicate
-            which version of the native library is required or supported.
-            Suffixes like these MUST be removed from the crate's `Cargo.toml` file
-            and dropped from the package Version,
-            because they might introduce dependency resolution problems
-            when this suffix leaks into RPM `Provides` metadata.
-
-=== Compatibility packages for older crate versions
-
-If it is not possible to port a crate to the version of a dependency that is available in Rawhide,
-a compatibility ("compat") package for the *older* version of a crate can be introduced.
-No package reviews for such compatibility packages are necessary,
-but they must follow the xref:Naming.adoc#multiple[Naming Guidelines] for compatibility packages.
-
-For example, the latest `rust-nix` package might ship the latest version of `nix`,
-but some packages still require the older `0.14.1` version of the crate --
-in this case, the compatibility package would be called `rust-nix0.14`.
-
-NOTE: Compatibility packages for older versions of library crates
-      are always parallel-installable with each other,
-      since all files in them are namespaced by both the crate's name *and* version.
+By default, cargo uses substring matching
+to match `--skip` arguments and actual names of tests,
+which can be turned off by using the `--exact` flag.
 
-However, compatibility packages for older crate versions MUST NOT ship application binaries.
-Neither the names of the subpackages that contain those binaries,
-nor the binaries themselves, are namespaced by the crate version.
-The package for the _older_ version MUST be adapted to remove its binary subpackage,
-so it only contains `-devel` subpackage(s) but no `+%{crate}+` subpackage,
-which would conflict with the corresponding package from the newer version of the crate.
+If any tests are skipped or disabled,
+the package *SHOULD* include comments
+that explain why this is the case,
+and include links to upstream issues, if available.
 
-NOTE: When introducing a compatibility package, the packager SHOULD check
-      if keeping the test suite enabled causes additional unwanted dependencies,
-      for example, on other compatibility packages, or on old versions of other packages.
-      If that is the case, the test suite SHOULD be disabled to lower the overall maintenance burden.
+== Rust applications (non-crates.io crates)
+
+Most rules that apply to Rust crates
+that are published in https://crates.io[crates.io]
+also apply to Rust projects that _are_ built with cargo
+but _not_ published on https://crates.io[crates.io].
 
-== License for binary packages
+https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
+has basic support for generating spec files for this type of package
+by running `rust2rpm path/to/Cargo.toml` in unpacked upstream sources.
 
-See xref:legal::license-field.adoc#_rust_packages[License: field in Spec file] guidance specific to Rust.
- 
+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}`.
 
-== Miscellaneous
+=== Package naming
 
-Packagers MUST run `+%cargo_prep+` after unpacking the crate's sources in `+%prep+`,
-which sets up configuration for cargo (compilation flags, location of system crates, etc.).
+Rust applications that are "crates"
+but which are not published on https://crates.io[crates.io]
+*MUST* be named according to the generic
+https://docs.fedoraproject.org/en-US/packaging-guidelines/Naming/[Naming Guidelines],
+i.e. they *MUST NOT* use a `rust-` prefix for the source package name.
 
-=== Excluding unnecessary files
+=== Package sources
 
-* Packagers SHOULD exclude files which are not used by anything (things like `appveyor.yml` and CI scripts).
-* Packagers SHOULD use the https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields-optional[exclude field in Cargo.toml] instead of using `+%exclude+` in `+%files+`
-* Packagers SHOULD forward such patches to upstream
+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.
 
-Example:
+== Rust applications (cargo workspace projects)
 
-[source,diff]
-----
---- csv-1.0.1/Cargo.toml	1970-01-01T01:00:00+01:00
-+++ csv-1.0.1/Cargo.toml	2018-09-25T07:14:47.639840+02:00
-@@ -22,6 +22,7 @@
- categories = ["encoding", "parser-implementations"]
- license = "Unlicense/MIT"
- repository = "https://github.com/BurntSushi/rust-csv"
-+exclude = ["/.travis.yml", "/appveyor.yml", "/ci/*", "/scripts/*"]
- [profile.bench]
- debug = true
- 
-----
+Some Rust projects are organized as "cargo workspaces",
+which are collections of Rust crates
+that are often considered "internal implementation details".
+In most cases, these "internal" crates
+are not published individually on https://crates.io[crates.io].
 
-=== Nightly features and dependencies for other platforms
+Projects that use this setup
+can be handled similarly to Rust projects
+that are organized as a single crate
+but not published on https://crates.io[crates.io].
 
-Packagers MUST NOT package crates which do not work on Fedora, this includes:
+https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
+has basic support for generating spec files for this type of package
+by running `rust2rpm path/to/Cargo.toml` in unpacked upstream sources,
+(where `./Cargo.toml` must be the path to the "workspace root",
+i.e. the `Cargo.toml` file that contains the `[workspace]` table).
 
-* crates depending on nightly-only features of the Rust compiler
-* crates with (non-Linux) platform-specific dependencies
+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 any subpackages that have virtual provides for `crate(...) = %{version}`.
+
+=== Package naming
 
-If such features and/or platform-specific dependencies are optional and can be removed,
-the `Cargo.toml` file MUST be patched to remove them, for example:
+Rust projects that are organized as "cargo workspaces"
+*MUST* be named according to the generic
+https://docs.fedoraproject.org/en-US/packaging-guidelines/Naming/[Naming Guidelines],
+i.e. they *MUST NOT* use a `rust-` prefix for the source package name.
 
-[source,diff]
-----
---- memmap-0.7.0/Cargo.toml	1970-01-01T00:00:00+00:00
-+++ memmap-0.7.0/Cargo.toml	2019-03-18T19:59:43.683403+00:00
-@@ -23,9 +23,6 @@
- version = "0.3"
- [target."cfg(unix)".dependencies.libc]
- version = "0.2"
--[target."cfg(windows)".dependencies.winapi]
--version = "0.3"
--features = ["basetsd", "handleapi", "memoryapi", "minwindef", "std", "sysinfoapi"]
- [badges.appveyor]
- repository = "danburkert/mmap"
- 
-----
+=== Package sources
 
-NOTE: The patch to remove platform-specific dependencies for non-linux platforms
-      is automatically generated by rust2rpm versions 22 and later.
-      Additionally, a configuration file for rust2rpm (`+rust2rpm.conf+`)
-      can be added to the package's dist-git repository
-      to disable generation of subpackages for specific features,
-      (for example, nightly-only features).
+The generic guidelines for
+https://docs.fedoraproject.org/en-US/packaging-guidelines/SourceURL/[referencing sources]
+apply.
 
-== Update process
+=== RPM macros
 
-Source-only Rust packages were granted a general exception to the
-https://docs.fedoraproject.org/en-US/fesco/Updates_Policy/[Updates policy],
-so they can be freely updated in release branches in addition to rawhide
-(announced in the corresponding FESCo ticket:
-https://pagure.io/fesco/issue/2474[F34 System-Wide Change: Rust Crate Packages For Release Branches]).
+All `%cargo_*` macros have support for cargo workspaces
+as of `cargo-rpm-macros >= 24`.
+Any unexpected results that occur when using these macros for projects
+that are set up as a cargo workspace
+should be reported against https://pagure.io/fedora-rust/cargo2rpm[cargo2rpm].
 
-If possible, packages for Rust library crates SHOULD be updated
-to the same version across all currently supported branches of Fedora.
-Exceptions for this rule might be:
+Note that currently, any `-a` and `-n` flags or `-f` arguments
+that are passed to `%cargo_generate_buildrequires`
+are applied to _all_ workspace members during dependency resolution.
 
-* system dependencies are too old on older branches (for example, `+libgit2+`)
-* pushing API-incompatible versions would result in broken packages on stable
-  branches (for example, packages for the `+gtk-rs+` project crates)
+== Python projects
 
-== Examples
+Python packages that use https://github.com/PyO3/setuptools-rust[setuptools_rust]
+or https://github.com/PyO3/maturin[maturin]
+to build a "native" Python extension
+also need to apply the link:#_generic_rules[generic rules] for  Rust packages
+in addition to following the
+https://docs.fedoraproject.org/en-US/packaging-guidelines/Python/[Python Packaging Guidelines].
 
-=== Library crate
+Both https://github.com/PyO3/setuptools-rust[setuptools_rust]
+and https://github.com/PyO3/maturin[maturin]
+build the native Python extension by calling cargo internally,
+so the basic setup for projects that build with cargo
+is required for packages like this as well.
 
-Rust library crates are packaged as source-only packages
-because Rust does not (yet) support shared libraries
-due to the lack of a stabilized ABI for Rust.
+This includes calling `%cargo_prep` in `%prep`
+to set up the build environment for cargo,
+and using `%cargo_generate_buildrequires` to dynamically generate
+the appropriate `BuildRequires` for Rust crate dependencies.
 
-The source code is shipped in a `-devel` subpackage,
-with separate subpackages for all features specified in `Cargo.toml`,
-which encode the dependency information for all features and dependencies.
+Additionally, `%cargo_license` and / or `%cargo_license_summary`
+*MUST* be used to determine the licenses
+that apply to the statically linked Python extension.
+
+The packager also *MUST* ensure
+that the default link:#_compiler_flags[compiler flags] are passed to rustc.
 
-.rust-serde.spec
-[source]
-----
-include::{examplesdir}/rust-serde.spec[]
-----
+== Mixed Rust / C/C++ projects
+
+Handling of projects that include both C/C++ and Rust code
+depends on how building the Rust code is integrated
+into the project’s build system.
+
+Independent of the specific setup,
+the correct link:#_compiler_flags[compiler flags] *MUST* be passed to rustc,
+and the License tag of the package that contains the Rust component
+*MUST* take the licenses of statically linked crates into account.
 
-=== Binary crate
+=== Building with cargo internally
+
+Projects with build systems that call cargo internally to build Rust components
+*MUST* follow the same guidelines
+as other projects that build Rust code with cargo.
 
-Rust applications are compiled to statically linked binaries,
-which are put into a subpackage that matches the name of the crate (without `rust-` prefix),
-e.g. the `rust-ripgrep` source package produces a `ripgrep` binary package,
-which contains the `ripgrep` binary.
+Packages *MUST* ensure that the cargo calls
+that are internal to the project’s build system
+do not pass flags or arguments that are incompatible
+with either the default link:#_compiler_flags[compiler flags] or cargo options
+that are set in the `%cargo_build` macro or configured by `%cargo_prep`.
 
-.rust-ripgrep.spec
-[source]
-----
-include::{examplesdir}/rust-ripgrep.spec[]
-----
+=== Building with meson directly
+
+Upcoming versions of https://mesonbuild.com/Rust.html[meson]
+will have support for building crate dependencies
+by reading `Cargo.toml` files directly,
+with meson supporting a similar mechanism
+for overriding https://crates.io[crates.io] sources with a local registry.
 
-=== Library + Binary
+== Building shared libraries with cargo-c
+
+While it is not currently possible
+to build Rust crates as shared libraries,
+Rust projects can define a C-compatible public API
+so that they can be built as standard shared libraries with a C ABI.
+
+In most cases, libraries like this are built with
+https://crates.io/crates/cargo-c[cargo-c],
+which provides convenient wrappers (`cargo-cbuild` and `cargo-cinstall`)
+for both building and installing shared libraries
+(including support for generating and installing header files
+and and pkg-config files).
 
-Some crates ship both a compiled binary and a reusable library component,
-in this case,
-both the `-devel` subpackage(s) *and* the subpackage containing the binary are built.
+The `cargo-c` package includes RPM macros for this functionality
+(`%cargo_cbuild` and `%cargo_cinstall`),
+which accept the same arguments as their cargo counterparts.
 
-.rust-yubibomb.spec
-[source]
-----
-include::{examplesdir}/rust-yubibomb.spec[]
-----

From fcdd45f96cf99d6b6b3bac6d6847b7f47c32ca78 Mon Sep 17 00:00:00 2001
From: Akira TAGOH 
Date: Oct 13 2023 07:44:53 +0000
Subject: [PATCH 104/232] Add an evidence for font package naming


There was some evidence how we should follow for the font package naming
but it was dropped by 20983f3643f60e4c9ac769bc11189491042aae4a and
the reference became a dead link since then.
This isn't good thing because we are missing the reason why fonts-rpm-macros
behave like that.  We still need an evidence in our policy.

---

diff --git a/guidelines/modules/ROOT/pages/Naming.adoc b/guidelines/modules/ROOT/pages/Naming.adoc
index 09cbfb7..c077fe5 100644
--- a/guidelines/modules/ROOT/pages/Naming.adoc
+++ b/guidelines/modules/ROOT/pages/Naming.adoc
@@ -210,7 +210,21 @@ Large can refer to either size or quantity of files.
 Packages containing fonts must be named
 `+[foundryname-]projectname[-fontfamilyname]-fonts+`,
 in lowercase.
-For a full explanation, see xref:FontsPolicy.adoc#_naming[Packaging/FontsPolicy#Naming].
+
+=== Clarifications
+
+1.  For Fedora purposes a “foundry” is an entity that publishes a set of fonts with consistent font QA rules. Thus a generic hosting service such as http://www.sf.net[Sourceforge] is not a foundry, but the http://openfontlibrary.org/[Open Font Library] is.
+2.  It is good practice to contract _foundryname-_ in a short prefix.
+3.  The _foundryname-_ prefix can optionally be skipped:
+* for entities that never released more than one font family, or
+* when the font project and the publishing entity are one and the same.
+4.  If _projectname_ or _foundryname_ are repeated in _fontfamilyname_, they can be dropped from _fontfamilyname_.
+5.  When _foundryname_, _projectname_ or _fontfamilyname_ contain the _font_ or _fonts_ affix, this affix should be dropped from themfootnote:[To avoid _foofont-fonts_ packages.].
+6.  _-fontfamilyname_ should not be included in the srpm name of a package that includes several different font families.
+7.  If any element of the naming contains spaces, they should be replaced by “-”.
+8.  The use of the _-fonts_ suffix is not dependant on the actual number of font files in the package.
+
+When in doubt, ask the https://fedoraproject.org/wiki/Fonts_SIG_mailing_lists[mailing list] for clarification.
 
 == Addon Packages
 

From a48e1f08c9d059d3aa93e771211e8706d071c336 Mon Sep 17 00:00:00 2001
From: Carl George 
Date: Nov 09 2023 02:45:46 +0000
Subject: [PATCH 105/232] Fix broken internal reference


Fixes #1317

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index cc030c2..7bb1c33 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -183,7 +183,7 @@ associated with that library or service.
 
 Packages SHOULD be installable independently whenever this is technically feasible,
 but they MUST specify dependencies of correct type on other packages if necessary,
-see <> below.
+see <> below.
 
 Desktop applications MUST NOT depend on other desktop applications
 unless strictly required.

From 7c1c5760d9eb23f4f7a3e6f6d184799fa84b4bde Mon Sep 17 00:00:00 2001
From: Osama Albahrani 
Date: Nov 30 2023 04:10:45 +0000
Subject: [PATCH 106/232] Rust.adoc: fix mixed Rust / C/C++ hyperlink


Note: there is also `link:[Fedora Legal docs]` which does not seem to redirect
---

diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc
index 09ee8a0..9a88e40 100644
--- a/guidelines/modules/ROOT/pages/Rust.adoc
+++ b/guidelines/modules/ROOT/pages/Rust.adoc
@@ -24,7 +24,7 @@ specific to the different ways in which projects can be set up:
   which are often not separately published on https://crates.io[crates.io]
 * link:#_python_projects[Python projects] with a "native" component implemented in Rust:
   usually built with https://github.com/PyO3/setuptools-rust[setuptools_rust] or https://github.com/PyO3/maturin[maturin]
-* link:_mixed_rust_cc_projects[mixed Rust / C/C++ projects] where parts of the project are implemented in Rust:
+* link:#_mixed_rust_cc_projects[mixed Rust / C/C++ projects] where parts of the project are implemented in Rust:
   either built by wrapping cargo,
   or by utilizing https://mesonbuild.com/Rust.html[meson]’s limited support
   for directly building Rust code

From 8ee8319f86af93a057ad6ad73c9b1addf8df5574 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Dec 01 2023 15:47:22 +0000
Subject: [PATCH 107/232] Change filepath dependency policy to "MUST NOT"


See https://pagure.io/fesco/issue/3097.

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 7bb1c33..32d8296 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -845,8 +845,8 @@ Packages MAY include such dependencies for paths inside one of the following dir
 * `+/etc+`
 
 They also MAY depend on paths listed in an explicit `Provides:`.
-They SHOULD NOT include dependencies on other paths
-as that requires additional repository metadata to be downloaded.
+They MUST NOT include dependencies on other paths,
+as that would require downloading of additional repository metadata to be enabled.
 
 Please also note that it is not uncommon
 for multiple packages to provide the same directory.

From 2690fcaed6974ab828e1f67e6b1eb269a3c455c7 Mon Sep 17 00:00:00 2001
From: Timothée Ravier 
Date: Dec 18 2023 11:21:37 +0000
Subject: [PATCH 108/232] UsersAndGroups: Add qemu & kvm from libvirt


See: https://src.fedoraproject.org/rpms/libvirt
See: https://src.fedoraproject.org/rpms/libvirt/pull-request/22

---

diff --git a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
index 1788136..7bc9fb4 100644
--- a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
+++ b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
@@ -261,6 +261,7 @@ tss,59,https://src.fedoraproject.org/rpms/tpm2-tss[tpm2-tss],
 tcpdump,72,https://src.fedoraproject.org/rpms/tcpdump[tcpdump],
 sshd,74,https://src.fedoraproject.org/rpms/openssh[openssh-server],
 dbus,81,https://src.fedoraproject.org/rpms/dbus[dbus-daemon],
+qemu,107,https://src.fedoraproject.org/rpms/libvirt[libvirt],
 ceph,167,https://src.fedoraproject.org/rpms/ceph[ceph-common],
 nobody,65534,https://src.fedoraproject.org/rpms/setup[setup],
 ,===
@@ -290,6 +291,7 @@ postgres,26,https://src.fedoraproject.org/rpms/postgresql[postgresql],
 rpc,32,https://src.fedoraproject.org/rpms/rpcbind[rpcbind],
 tape,33,https://src.fedoraproject.org/rpms/setup[setup],
 utempter,35,https://src.fedoraproject.org/rpms/libutempter[libutempter],
+kvm,36,https://src.fedoraproject.org/rpms/libvirt[libvirt],
 video,39,https://src.fedoraproject.org/rpms/setup[setup],
 gdm,42,https://src.fedoraproject.org/rpms/gdm[gdm],
 ftp,50,https://src.fedoraproject.org/rpms/setup[setup],
@@ -300,6 +302,7 @@ tcpdump,72,https://src.fedoraproject.org/rpms/tcpdump[tcpdump],
 sshd,74,https://src.fedoraproject.org/rpms/openssh[openssh-server],
 dbus,81,https://src.fedoraproject.org/rpms/dbus[dbus-daemon],
 users,100,https://src.fedoraproject.org/rpms/setup[setup],
+qemu,107,https://src.fedoraproject.org/rpms/libvirt[libvirt],
 mock,135,https://src.fedoraproject.org/rpms/mock[mock],
 ceph,167,https://src.fedoraproject.org/rpms/ceph[ceph-common],
 nobody,65534,https://src.fedoraproject.org/rpms/setup[setup],

From 45ab676e8b56021f1a66e1764c1aca875f930ea8 Mon Sep 17 00:00:00 2001
From: Carl George 
Date: Dec 21 2023 05:17:30 +0000
Subject: [PATCH 109/232] Fix rendering of langpacks supplements instructions


Fixes #1318

---

diff --git a/guidelines/modules/ROOT/pages/Langpacks.adoc b/guidelines/modules/ROOT/pages/Langpacks.adoc
index f5e3840..a3abafb 100644
--- a/guidelines/modules/ROOT/pages/Langpacks.adoc
+++ b/guidelines/modules/ROOT/pages/Langpacks.adoc
@@ -6,7 +6,7 @@ Subpackages that exist solely to contain additional language translations or con
 
 The langpack ecosystem does not need any procedural logic in the form of plugins. Instead it takes advantage of the weak and rich dependency features provided by RPM. The necessary dependencies are computed by the package manager (DNF or PackageKit) so it is essential to include the following `+Supplements:+` tag relation in the langpack package definition in the spec file:
 
-`+Supplements: (%{name} = %{version}-%{release} and langpacks-+``+)+`
+`+Supplements: (%{name} = %{version}-%{release} and langpacks-)+`
 
 == Example
 

From f3a0fc8e856e39817df9d958ea3c8c7031dec8c2 Mon Sep 17 00:00:00 2001
From: Steve Cossette 
Date: Jan 03 2024 02:03:36 +0000
Subject: [PATCH 110/232] KDE-specific Packaging Directives


---

diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc
index a773e7d..c75834e 100644
--- a/guidelines/modules/ROOT/nav.adoc
+++ b/guidelines/modules/ROOT/nav.adoc
@@ -12,6 +12,7 @@
 * xref:Directory_Replacement.adoc[Directory Replacement]
 * xref:DistTag.adoc[Dist Tag]
 * xref:Initial_Service_Setup.adoc[Initial Service Setup]
+* xref:KDEPackaging.adoc[KDE Packaging Guidelines]
 * xref:Langpacks.adoc[Language Packs]
 * xref:LicensingGuidelines.adoc[Licensing]
 * xref:manual-changelog.adoc[Manual Changelog]
diff --git a/guidelines/modules/ROOT/pages/KDEPackaging.adoc b/guidelines/modules/ROOT/pages/KDEPackaging.adoc
new file mode 100644
index 0000000..c593a74
--- /dev/null
+++ b/guidelines/modules/ROOT/pages/KDEPackaging.adoc
@@ -0,0 +1,65 @@
+= KDE Packaging
+
+:last-reviewed: 2024-01-02
+
+This document outlines the best practices for packaging software using the KDE frameworks, for use in Fedora.
+
+== Build Dependencies
+
+If using cmake, the following BuildRequires are a *MUST*:
+
+[source, rpm-spec]
+----
+BuildRequires: cmake
+BuildRequires: gcc-c++
+BuildRequires: kf6-rpm-macros
+----
+
+`kf6-rpm-macros` needs to be changed to `kf5-rpm-macros` if building for Plasma 5 instead of Plasma 6.
+
+== Available Macros
+
+The following macros are used in the building of KDE packages. Note that the version of macros (i.e. `%cmake_kf5` and `%cmake_kf6`) can be changed depending on which version of Plasma you are building for.
+
+`+%cmake_kf6+`::
+Not unlike `+%cmake+`, this macro defines CFLAGS, LDFLAGS, etc. and calls `+%__cmake+`
+with appropriate parameters
+(`+-DCMAKE_INSTALL_PREFIX:PATH=/usr+` and such), but with additional KDE-specific flags and parameters.
+You can pass `+-Doption=value+` to this macro
+in order to set options for the buildsystem.
+
+`+%stable_kf6+`::
+Used in the package's source links, if the package is released on the official KDE download server. Outputs either `stable` or `unstable` depending on the version of the package.
+
+Here's an example of how it would look like:
+----
+Source0: http://download.kde.org/%{stable_kf6}/release-service/%{version}/src/%{name}-%{version}.tar.xz
+----
+
+`+%find_lang_kf6+`::
+This macro is sometimes used instead of `+%find_lang+` in packages using language files ending in `_qt.qm`.
+
+[#kde-file-macros]
+== Macros for paths set and used by build systems
+
+The following table lists macros which are widely used in fedora `.spec` files. Those macros are provided by the `kf5-rpm-macros` (For Plasma 5) and `kf6-rpm-macros` (For Plasma 6) packages.
+
+For Plasma 5, the following macros can simply have their version number changed to reflect the Plasma 5 version (For example, `+%{_kf6_datadir}+` would become `+%{_kf5_datadir}+`).
+
+[cols="20%m,30%m,50%",options="header"]
+|=================================
+| macro                | definition                  | comment
+| +%{_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_sysconfdir}+ | +%{_sysconfdir}+            | default: `/etc`
+| +%{_kf6_mandir}+     | +%{_kf6_datadir}+/man       | default: `/usr/share/man`
+| +%{_kf6_qmldir}+     | +%{_kf6_archdatadir}+/qml   | default: `/usr/lib64/qt6/qml`
+|=================================

From 69aa652d9afee2b79dc2a7ad243e55339358d26b Mon Sep 17 00:00:00 2001
From: Steve Cossette 
Date: Jan 03 2024 02:33:23 +0000
Subject: [PATCH 111/232] Updated CMake.adoc to point to KDEPackaging.adoc


Updated the already existing directives to point to the new KDE Packaging directives document
---

diff --git a/guidelines/modules/ROOT/pages/CMake.adoc b/guidelines/modules/ROOT/pages/CMake.adoc
index 1acccb4..a1da833 100644
--- a/guidelines/modules/ROOT/pages/CMake.adoc
+++ b/guidelines/modules/ROOT/pages/CMake.adoc
@@ -37,8 +37,8 @@ Runs the tests that are defined with `+add_test()+`
 in project (using `+%__ctest+`).
 
 When packaging KDE software,
-you most likely would replace `+%cmake+` with `+%cmake_kf5+`
-that defines multiple KDE-related variables (shipped in `+kf5+` package).
+you most likely would replace `+%cmake+` with either `+%cmake_kf5+`
+or `+%cmake_kf6+`. For more information, see xref:KDEPackaging.adoc[KDE Packaging Guidelines].
 
 It is rarely necessary (but permissible) to use or alter these:
 

From 0f8c9260a6a94f4c061e42016e9a18c2885f770c Mon Sep 17 00:00:00 2001
From: Frank Dana (FeRD) 
Date: Jan 05 2024 14:22:57 +0000
Subject: [PATCH 112/232] Guidelines/Python: Fix bad xref


---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 888f42b..9733b13 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1209,7 +1209,7 @@ The following is a viable spec file
 for a Python library called `+Pello+`
 that follows packaging best practices.
 
-Note that the project name `+Pello+` <>
+Note that the project name `+Pello+` <>
 to the lowercase `+pello+`.
 The example spec shows where each variant is typically used.
 

From f9a8ca36f2017454e47c34e3afb36ab02287ffbb Mon Sep 17 00:00:00 2001
From: Benjamin A. Beasley 
Date: Feb 16 2024 13:40:39 +0000
Subject: [PATCH 113/232] Document the -l/-L options to %pyproject_save_files


Copy essential commentary and recommendations from the README.md of
pyproject-rpm-macros.

---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 9733b13..fea839a 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1264,7 +1264,7 @@ Recommends:     python3-pello+color
 %pyproject_install
 
 # Here, "pello" is the name of the importable module.
-%pyproject_save_files pello
+%pyproject_save_files -l pello
 
 
 %check
@@ -1522,6 +1522,17 @@ To prevent Shell from expanding the globs, put them in `+''+`,
 e.g. `+%pyproject_save_files '*pytest'+`.
 As mentioned in the <> section,
 expressions like `+%pyproject_save_files '*'+` are not acceptable.
++
+The macro has these options:
++
+** `+-l+`: Declare that a missing license should terminate the build.
+Packagers are encouraged to use this flag
+when the `%license file` is not manually listed in `%files`
+to avoid accidentally losing the file in a future version.
+** `+-L+`: Explicitly disable the check for a missing license file.
+When the `%license` file is manually listed in `%files`,
+packagers can use this flag to ensure future compatibility
+in case the `-l` behavior eventually becomes a default.
 
 [#pyproject_files]
 * `+%{pyproject_files}+`

From b81f792a4e6287e875521b16bb285d5ffa7ccdc9 Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Feb 27 2024 09:41:41 +0000
Subject: [PATCH 114/232] Document explicitly that %tox requires %pyproject_buildrequires -t/-e


See https://bugzilla.redhat.com/2266228

---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index fea839a..741d464 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1049,7 +1049,7 @@ to test that installed modules are importable.
 A popular testing tool, and one which is well integrated in Fedora,
 is `+tox+`.
 Upstream, it is commonly used to test against multiple Python versions.
-In a Fedora package, BuildRequire test dependencies
+In a Fedora package, BuildRequire test dependencies via `+%pyproject_buildrequires -t+` or `+-e+`
 (see _Test dependencies_ below)
 and run `+tox+` with:
 
@@ -1551,6 +1551,9 @@ Path of the file written by `+%pyproject_save_files+`, to be used as:
 +
 Run tests using `+tox+`.
 +
+This macro needs BuildRequires generated by the `+-t+` or `+-e+` option of
+<>.
++
 Different environments may be specified with `+-e+`, for example:
 +
 [source,spec]

From 44113dd4b3fbb287ed2a44b5efe71ec5194247c9 Mon Sep 17 00:00:00 2001
From: Fabio Valentini 
Date: Mar 14 2024 15:36:08 +0000
Subject: [PATCH 115/232] Rust: replace occurrences of stray unicode characters


- non-breaking spaces
- en-dashes
- typographic single quotes

Note sure how they ended up there in the first place.

---

diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc
index 9a88e40..cf141d5 100644
--- a/guidelines/modules/ROOT/pages/Rust.adoc
+++ b/guidelines/modules/ROOT/pages/Rust.adoc
@@ -1,6 +1,6 @@
 = Rust Packaging Guidelines
 
-:last-reviewed: 2023-10-12
+:last-reviewed: 2024-03-14
 
 https://www.rust-lang.org[Rust] is a strongly and statically typed,
 compiled programming language
@@ -26,7 +26,7 @@ specific to the different ways in which projects can be set up:
   usually built with https://github.com/PyO3/setuptools-rust[setuptools_rust] or https://github.com/PyO3/maturin[maturin]
 * link:#_mixed_rust_cc_projects[mixed Rust / C/C++ projects] where parts of the project are implemented in Rust:
   either built by wrapping cargo,
-  or by utilizing https://mesonbuild.com/Rust.html[meson]’s limited support
+  or by utilizing https://mesonbuild.com/Rust.html[meson]'s limited support
   for directly building Rust code
 
 For the first three of these cases,
@@ -57,7 +57,7 @@ based on this macro.
 
 For compatibility with older releases,
 this environment variable can be set manually at the start of `%build` and `%check`
-in package’s spec files:
+in package's spec files:
 
 [source,shell]
 ----
@@ -76,13 +76,13 @@ as it is a dependency of `redhat-rpm-config`.
 When building for ELN or EPEL8, this is not the case,
 and packages need to use `BuildRequires: rust-toolset`.
 
-Packages that build Rust code with cargo – directly or indirectly –
+Packages that build Rust code with cargo - directly or indirectly -
 or which call any of the `%cargo_*` macros,
 *MUST* add `BuildRequires:  cargo-rpm-macros >= 24`,
 which provides the implementations of all `%cargo_*` macros.
 This package is not part of the default buildroot,
 since it pulls in additional dependencies
-(i.e. a Python interpreter).
+(i.e. a Python interpreter).
 
 For backwards compatibility,
 packages *MAY* instead depend on earlier versions of the `%cargo_*` macros,
@@ -99,7 +99,7 @@ for the RPM macro package automatically.
 Similar to other languages that produce statically linked binaries,
 Rust executables (and shared libraries) contain code
 that originates in other packages
-(i.e. packages for other Rust crates),
+(i.e. packages for other Rust crates),
 which in turn are covered by different license terms.
 
 This needs to be taken into account
@@ -181,7 +181,7 @@ with a path-based dependency.
 
 Another way in which cargo supports specifying modified dependencies is
 by "patching" a crate source,
-specifying an alternative source for specific crates –
+specifying an alternative source for specific crates -
 which will likely be either git references or path-based dependencies
 that are present to override a crate
 that is published on https://crates.io[crates.io] with a (modified) local copy,
@@ -211,7 +211,7 @@ was added in version 25 of cargo-rpm-macros and rust2rpm.
   that lists the names and versions of all crates in the vendor tarball.
   This macro *MUST* be called (for example, in the `%build` scriptlet),
   and the generated file *MUST* be added as a `%license` file
-  in the appropriate package’s list of `%files`.
+  in the appropriate package's list of `%files`.
   An RPM generator parses this file
   and generates appropriate virtual `Provides` for all bundled crates,
   as is required for any bundled dependencies.
@@ -245,18 +245,18 @@ need manual changes:
 * invalid `Summary` / `%description`:
   The heuristics for generating the `Summary` or `%description` for the package
   from the crate metadata can fail to produce valid values
-  (i.e. `Summary` tag that is too long).
+  (i.e. `Summary` tag that is too long).
   In this case, the `Summary` needs to be shortened manually.
   This can also be overridden
   in the package-specific rust2rpm configuration file.
 * unwanted dependencies / subpackages:
   Some crates provide non-default / optional features
   that are either unnecessary
-  (i.e. only applicable to non-Linux systems),
+  (i.e. only applicable to non-Linux systems),
   or have additional dependencies
   that are not packaged for Fedora.
   These features and unavailable optional dependencies *MUST*
-  be removed from crate metadata – otherwise,
+  be removed from crate metadata - otherwise,
   the package will either fail to build,
   or produce subpackages with broken dependencies.
 * nightly-only / unstable features:
@@ -297,7 +297,7 @@ Note that patching `Cargo.toml` files
 (especially changing the set of optional dependencies and features)
 *MUST* be done by running `rust2rpm -p`,
 since changes like these affect spec file generation
-(i.e. the list of generated subpackages),
+(i.e. the list of generated subpackages),
 which is only correctly taken into account
 if the patch is created _before_ generation of the spec file.
 
@@ -309,7 +309,7 @@ It is designed to generate spec files that are compliant
 with both the general and the Rust Packaging Guidelines.
 
 Additionally, due to some properties of packages for Rust crates
-(i.e. subpackages that correspond to crate features / optional dependencies),
+(i.e. subpackages that correspond to crate features / optional dependencies),
 it is necessary to re-run https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
 for every new version of a crate
 to ensure that generated feature subpackages
@@ -329,13 +329,13 @@ On the other hand,
 projects from other sources *MUST NOT* use the `rust-` prefix for source package names,
 and *MUST* follow the general Naming Guidelines instead.
 They also *MUST NOT* have any virtual `Provides` for Rust crates
-(i.e. `Provides: crate(%{crate}) = %{version}`).
+(i.e. `Provides: crate(%{crate}) = %{version}`).
 
 When generating a package for a Rust crate
 that also (or exclusively) contains an application,
 the convention followed by https://pagure.io/fedora-rust/rust2rpm[rust2rpm] is
-to generate a subpackage with a name that matches the crate’s name
-(i.e. the `rust-$crate` source package will have a `$crate` subpackage).
+to generate a subpackage with a name that matches the crate's name
+(i.e. the `rust-$crate` source package will have a `$crate` subpackage).
 If this name does not match expectations,
 it is recommended to either change the name of this subpackage,
 or to add virtual `Provides` for the expected name.
@@ -367,7 +367,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
@@ -380,7 +380,7 @@ about including these additional files in published crates.
 If a crate is also part of a larger project
 and it is not feasible to package the Rust crate separately,
 the Rust crate *MAY* be packaged as `rust-$crate` from different sources
-(i.e. an upstream tarball) _if and only if_ the crate is also published on https://crates.io[crates.io]
+(i.e. an upstream tarball) _if and only if_ the crate is also published on https://crates.io[crates.io]
 under the same name and with matching versions.
 In this case, the subpackage(s) corresponding to Rust crates
 *MUST* have correct virtual `Provides` for the Rust crate.
@@ -429,7 +429,7 @@ is almost entirely automated with several RPM macros:
   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}/`).
+  (i.e. `%{buildroot}/%{cargo_registry}/%{crate}-%{version}/`).
   For crates that provide `bin` targets,
   it installs all built executables into `%{buildroot}/%{_bindir}`.
   If any built executables need to be installed in a different location,
@@ -453,7 +453,7 @@ All packages for Rust crates *MUST* set
 either `%bcond_without check` or `%bcond_with check`.
 The value of this macro affects the behaviour of `%cargo_generate_buildrequires`.
 
-All `%cargo_*` macros (except `%cargo_prep`)
+All `%cargo_*` macros (except `%cargo_prep` and `%cargo_vendor_manifest`)
 accept a set of optional flags / arguments
 that can be used to control the feature flags that are passed to cargo
 (usually to enable optional / non-default features):
@@ -505,7 +505,7 @@ With Semantic Versioning (_"SemVer"_) being
 the only supported versioning scheme for Rust crates,
 dependencies on Rust libraries are almost exclusively specified as
 _"this version or any newer version that is API-compatible with it"_,
-i.e. a range of supported versions.
+i.e. a range of supported versions.
 
 These ranges of supported versions
 need to be correctly translated into RPM dependencies,
@@ -545,7 +545,7 @@ to support resolving dependencies for features and optional dependencies of crat
 The list of crate "features"
 (including any implicitly defined features for optional dependencies)
 *MUST* be kept in sync with the list of subpackages,
-i.e. for every feature `$foo` of the crate `$crate`,
+i.e. for every feature `$foo` of the crate `$crate`,
 there must be a subpackage with name `rust-$crate+$foo-devel`,
 and vice-versa.
 This is required for RPM generators for `Provides` and `Requires`
@@ -574,10 +574,10 @@ 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,
+that the generated `Provides` and `Requires` are sane - for example,
 the following `Provides` and `Requires`
 must be present to ensure correct inter-subpackage dependencies:
 
@@ -585,7 +585,7 @@ must be present to ensure correct inter-subpackage dependencies:
   *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`)
+  and require `crate($crate) = %{version}` (i.e. `rust-$crate-devel`)
 
 Additionally, dependencies on external Rust crates must be as expected:
 
@@ -593,13 +593,13 @@ Additionally, dependencies on external Rust crates must be as expected:
   *MUST* require the virtual `Provides` for all non-optional crate dependencies
 * the `rust-$crate+$feature-devel` subpackages
   *MUST* require the virtual `Provides` for the optional crate dependencies
-  and features that are listed as the feature’s dependencies in crate metadata
+  and features that are listed as the feature's dependencies in crate metadata
 
 === Packaging multiple versions
 
 In most circumstances,
 the latest version of a crate *SHOULD* be packaged,
-and – if possible – packagers *SHOULD* port crates
+and - if possible - packagers *SHOULD* port crates
 to use the latest available version of their dependencies,
 and submit these patches to upstream
 to limit divergence between the upstream project and the Fedora package.
@@ -615,7 +615,7 @@ for multiple versions of a library crate simultaneously:
   by a required SemVer-incompatible library update is very large.
 
 In these cases, a "compat package" can be created for the older version
-(i.e. usually the current version),
+(i.e. usually the current version),
 and the suffix-less package can be updated to the newer version.
 https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
 supports automatically creating "compat packages"
@@ -638,19 +638,19 @@ and two additional rules apply when creating them:
   whether running tests in the old version of the crate
   would cause additional, potentially undesirable dependencies,
   for example, older versions of other dependencies
-  that would require creating additional "compat packages" –
+  that would require creating additional "compat packages" -
   in this case, tests *SHOULD* be disabled
-  (i.e. by flipping the `check` bcond).
+  (i.e. by flipping the `check` bcond).
 
 === The `check` bcond
 
 The behaviour of some RPM macros
 depends on the presence and value of the `_with_check` macro,
-i.e. if `%bcond_without check` or `%bcond_with check`
-are used in the spec file – notably,
+i.e. if `%bcond_without check` or `%bcond_with check`
+are used in the spec file - notably,
 the `%cargo_generate_buildrequires` macro only includes `dev-dependencies`
-(i.e. dependencies that are only used
-for compiling and / or running a project’s test suite with cargo)
+(i.e. dependencies that are only used
+for compiling and / or running a project's test suite with cargo)
 if the `check` bconf is enabled.
 
 Additionally, packages for Rust crates or workspace projects
@@ -681,7 +681,7 @@ Rust crates can have three different kinds of tests in their test suites:
   to ensure that code snippets in documentation for public methods
   are correct and continue to compile.
 
-By default, running `cargo test` (i.e. by calling the `%cargo_test` macro),
+By default, running `cargo test` (i.e. by calling the `%cargo_test` macro),
 all three kinds of tests are run.
 They can also be invoked separately
 (for example, because parts of the test suite or large data files are
@@ -725,7 +725,7 @@ has basic support for generating spec files for this type of package
 by running `rust2rpm path/to/Cargo.toml` in unpacked upstream sources.
 
 Packages that fall into this category *MUST NOT* ship crate sources in `%{cargo_registry}`,
-i.e. they cannot ship `-devel` subpackages
+i.e. they cannot ship `-devel` subpackages
 that contain crate sources or have subpackages
 that have virtual provides for `crate(...) = %{version}`.
 
@@ -735,7 +735,7 @@ Rust applications that are "crates"
 but which are not published on https://crates.io[crates.io]
 *MUST* be named according to the generic
 https://docs.fedoraproject.org/en-US/packaging-guidelines/Naming/[Naming Guidelines],
-i.e. they *MUST NOT* use a `rust-` prefix for the source package name.
+i.e. they *MUST NOT* use a `rust-` prefix for the source package name.
 
 === Package sources
 
@@ -760,11 +760,11 @@ https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
 has basic support for generating spec files for this type of package
 by running `rust2rpm path/to/Cargo.toml` in unpacked upstream sources,
 (where `./Cargo.toml` must be the path to the "workspace root",
-i.e. the `Cargo.toml` file that contains the `[workspace]` table).
+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}`,
-i.e. they cannot ship `-devel` subpackages that contain crate sources
+i.e. they cannot ship `-devel` subpackages that contain crate sources
 or have any subpackages that have virtual provides for `crate(...) = %{version}`.
 
 === Package naming
@@ -772,7 +772,7 @@ or have any subpackages that have virtual provides for `crate(...) = %{version}`
 Rust projects that are organized as "cargo workspaces"
 *MUST* be named according to the generic
 https://docs.fedoraproject.org/en-US/packaging-guidelines/Naming/[Naming Guidelines],
-i.e. they *MUST NOT* use a `rust-` prefix for the source package name.
+i.e. they *MUST NOT* use a `rust-` prefix for the source package name.
 
 === Package sources
 
@@ -823,7 +823,7 @@ that the default link:#_compiler_flags[compiler flags] are passed to rustc.
 
 Handling of projects that include both C/C++ and Rust code
 depends on how building the Rust code is integrated
-into the project’s build system.
+into the project's build system.
 
 Independent of the specific setup,
 the correct link:#_compiler_flags[compiler flags] *MUST* be passed to rustc,
@@ -837,7 +837,7 @@ Projects with build systems that call cargo internally to build Rust components
 as other projects that build Rust code with cargo.
 
 Packages *MUST* ensure that the cargo calls
-that are internal to the project’s build system
+that are internal to the project's build system
 do not pass flags or arguments that are incompatible
 with either the default link:#_compiler_flags[compiler flags] or cargo options
 that are set in the `%cargo_build` macro or configured by `%cargo_prep`.

From 1ba36bca91d79123f146ea0ac54e570975a888a1 Mon Sep 17 00:00:00 2001
From: Fabio Valentini 
Date: Mar 14 2024 15:38:11 +0000
Subject: [PATCH 116/232] Rust: document that the same feature flags must be passed everywhere


---

diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc
index cf141d5..8047681 100644
--- a/guidelines/modules/ROOT/pages/Rust.adoc
+++ b/guidelines/modules/ROOT/pages/Rust.adoc
@@ -496,9 +496,21 @@ in which passing these flags or arguments is necessary:
   (including `%cargo_license` and `%cargo_license_summary`).
 
 Note that the `-n` flag should only be used in exceptional circumstances,
+for example when enabling a different backend than the one enabled by default,
 and *MUST NOT* be used to avoid missing dependencies
 that are part of the `"default"` feature set of a crate.
 
+When passing any of the `-a` or `-n` flags or an `-f` argument
+to a `%cargo_build` and / or `%cargo_install` macro,
+the same flags MUST also be passed
+to `%cargo_license` and `%cargo_license_summary` (if present).
+Otherwise, the list of generated licenses and the generated license summary
+will not match what is used when the application or library is compiled.
+
+It is recommended to set these flags in a `rust2rpm.toml` config file
+which causes the flags to be injected into generated spec files automatically,
+whereever necessary.
+
 === Dynamically generated `BuildRequires` for crate dependencies
 
 With Semantic Versioning (_"SemVer"_) being

From afb868b0ef88f5fad63bd4a131fcdcb59dbf2ec4 Mon Sep 17 00:00:00 2001
From: Jens Petersen 
Date: Mar 26 2024 16:41:20 +0000
Subject: [PATCH 117/232] Haskell: document shared libraries E: unused-direct-shlib-dependency


Haskell shared libraries currently cause many `unused-direct-shlib-dependency` rpmlint errors
---

diff --git a/guidelines/modules/ROOT/pages/Haskell.adoc b/guidelines/modules/ROOT/pages/Haskell.adoc
index 6fcd400..fbe3c60 100644
--- a/guidelines/modules/ROOT/pages/Haskell.adoc
+++ b/guidelines/modules/ROOT/pages/Haskell.adoc
@@ -279,6 +279,8 @@ Since GHC assumes static versions of libraries are installed they need to be in 
 
 Executables in Bin and BinLib packages should be statically linked for portability.
 
+Due to how GHC links shared libraries using `+--no-as-needed+` they generate a lot of rpmlint `+E: undefined-non-weak-symbol+` errors, this is unfortunately currently expected (see these https://gitlab.haskell.org/ghc/ghc/-/issues/17157[upstream] https://gitlab.haskell.org/ghc/ghc/-/issues/23216[issues]).
+
 == RPM Macros
 
 The templates all have buildrequires for ghc-rpm-macros, which provides https://src.fedoraproject.org/rpms/ghc-rpm-macros/blob/master/f/macros.ghc[macros.ghc] to assist with packaging Haskell Cabal packages.

From 33ed5ac5c91387fa50acac06ae3a93e67d777eb0 Mon Sep 17 00:00:00 2001
From: Jerry James 
Date: Mar 27 2024 17:31:28 +0000
Subject: [PATCH 118/232] Update GAP Guidelines


- Add gap-rpm-macros to list of base packages
- Remove overly prescriptive Architecture section

---

diff --git a/guidelines/modules/ROOT/pages/GAP.adoc b/guidelines/modules/ROOT/pages/GAP.adoc
index 13a6fd2..08deeb4 100644
--- a/guidelines/modules/ROOT/pages/GAP.adoc
+++ b/guidelines/modules/ROOT/pages/GAP.adoc
@@ -5,7 +5,7 @@ Throughout this document, we use the word _add-on_ to substitute for GAP upstrea
 
 == Naming
 
-The main GAP package and its attendant libraries and help system are in packages named gap, gap-libs, gap-core, gap-online-help, gap-devel, gap-vim, and libgap.
+The main GAP package and its attendant libraries and help system are in packages named gap, gap-libs, gap-core, gap-online-help, gap-rpm-macros, gap-devel, gap-vim, and libgap.
 To distinguish add-on packages from these core packages, add-ons MUST have names of the form gap-pkg-foo.
 For example, the FGA add-on is named gap-pkg-fga.
 
@@ -99,19 +99,6 @@ Since GAP documentation MUST be installed under `+%{gap_libdir}/pkg+` or `+%{gap
 However, the documentation SHOULD still be marked as such so that documentation-free installs work as expected.
 Most add-ons SHOULD include `+%docdir+` declarations in the `+%files+` section of the spec file; e.g., `+%docdir %{gap_libdir}/pkg/%{pkgname}/doc+` and `+%docdir %{gap_libdir}/pkg/%{pkgname}/htm+`.
 
-== Architecture
-
-Fedora now encourages packagers to https://fedoraproject.org/wiki/Changes/EncourageI686LeafRemoval[not build packages for i686].
-For that reason, noarch GAP add-ons MUST include these tags:
-....
-BuildArch:      noarch
-ExclusiveArch:  %{gap_arches} noarch
-....
-Architecture-specific GAP add-ons MUST instead include this tag:
-....
-ExclusiveArch:  %{gap_arches}
-....
-
 == Other RPM macros
 
 Other RPM macros that may be useful for GAP add-on spec files include the following:

From a173e935a10a1f90c27430f32a80748f55f3a3ad Mon Sep 17 00:00:00 2001
From: James Antill 
Date: Mar 28 2024 16:28:46 +0000
Subject: [PATCH 119/232] Merge #1342 `Rust: small updates and clarifications`


---

diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc
index 9a88e40..8047681 100644
--- a/guidelines/modules/ROOT/pages/Rust.adoc
+++ b/guidelines/modules/ROOT/pages/Rust.adoc
@@ -1,6 +1,6 @@
 = Rust Packaging Guidelines
 
-:last-reviewed: 2023-10-12
+:last-reviewed: 2024-03-14
 
 https://www.rust-lang.org[Rust] is a strongly and statically typed,
 compiled programming language
@@ -26,7 +26,7 @@ specific to the different ways in which projects can be set up:
   usually built with https://github.com/PyO3/setuptools-rust[setuptools_rust] or https://github.com/PyO3/maturin[maturin]
 * link:#_mixed_rust_cc_projects[mixed Rust / C/C++ projects] where parts of the project are implemented in Rust:
   either built by wrapping cargo,
-  or by utilizing https://mesonbuild.com/Rust.html[meson]’s limited support
+  or by utilizing https://mesonbuild.com/Rust.html[meson]'s limited support
   for directly building Rust code
 
 For the first three of these cases,
@@ -57,7 +57,7 @@ based on this macro.
 
 For compatibility with older releases,
 this environment variable can be set manually at the start of `%build` and `%check`
-in package’s spec files:
+in package's spec files:
 
 [source,shell]
 ----
@@ -76,13 +76,13 @@ as it is a dependency of `redhat-rpm-config`.
 When building for ELN or EPEL8, this is not the case,
 and packages need to use `BuildRequires: rust-toolset`.
 
-Packages that build Rust code with cargo – directly or indirectly –
+Packages that build Rust code with cargo - directly or indirectly -
 or which call any of the `%cargo_*` macros,
 *MUST* add `BuildRequires:  cargo-rpm-macros >= 24`,
 which provides the implementations of all `%cargo_*` macros.
 This package is not part of the default buildroot,
 since it pulls in additional dependencies
-(i.e. a Python interpreter).
+(i.e. a Python interpreter).
 
 For backwards compatibility,
 packages *MAY* instead depend on earlier versions of the `%cargo_*` macros,
@@ -99,7 +99,7 @@ for the RPM macro package automatically.
 Similar to other languages that produce statically linked binaries,
 Rust executables (and shared libraries) contain code
 that originates in other packages
-(i.e. packages for other Rust crates),
+(i.e. packages for other Rust crates),
 which in turn are covered by different license terms.
 
 This needs to be taken into account
@@ -181,7 +181,7 @@ with a path-based dependency.
 
 Another way in which cargo supports specifying modified dependencies is
 by "patching" a crate source,
-specifying an alternative source for specific crates –
+specifying an alternative source for specific crates -
 which will likely be either git references or path-based dependencies
 that are present to override a crate
 that is published on https://crates.io[crates.io] with a (modified) local copy,
@@ -211,7 +211,7 @@ was added in version 25 of cargo-rpm-macros and rust2rpm.
   that lists the names and versions of all crates in the vendor tarball.
   This macro *MUST* be called (for example, in the `%build` scriptlet),
   and the generated file *MUST* be added as a `%license` file
-  in the appropriate package’s list of `%files`.
+  in the appropriate package's list of `%files`.
   An RPM generator parses this file
   and generates appropriate virtual `Provides` for all bundled crates,
   as is required for any bundled dependencies.
@@ -245,18 +245,18 @@ need manual changes:
 * invalid `Summary` / `%description`:
   The heuristics for generating the `Summary` or `%description` for the package
   from the crate metadata can fail to produce valid values
-  (i.e. `Summary` tag that is too long).
+  (i.e. `Summary` tag that is too long).
   In this case, the `Summary` needs to be shortened manually.
   This can also be overridden
   in the package-specific rust2rpm configuration file.
 * unwanted dependencies / subpackages:
   Some crates provide non-default / optional features
   that are either unnecessary
-  (i.e. only applicable to non-Linux systems),
+  (i.e. only applicable to non-Linux systems),
   or have additional dependencies
   that are not packaged for Fedora.
   These features and unavailable optional dependencies *MUST*
-  be removed from crate metadata – otherwise,
+  be removed from crate metadata - otherwise,
   the package will either fail to build,
   or produce subpackages with broken dependencies.
 * nightly-only / unstable features:
@@ -297,7 +297,7 @@ Note that patching `Cargo.toml` files
 (especially changing the set of optional dependencies and features)
 *MUST* be done by running `rust2rpm -p`,
 since changes like these affect spec file generation
-(i.e. the list of generated subpackages),
+(i.e. the list of generated subpackages),
 which is only correctly taken into account
 if the patch is created _before_ generation of the spec file.
 
@@ -309,7 +309,7 @@ It is designed to generate spec files that are compliant
 with both the general and the Rust Packaging Guidelines.
 
 Additionally, due to some properties of packages for Rust crates
-(i.e. subpackages that correspond to crate features / optional dependencies),
+(i.e. subpackages that correspond to crate features / optional dependencies),
 it is necessary to re-run https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
 for every new version of a crate
 to ensure that generated feature subpackages
@@ -329,13 +329,13 @@ On the other hand,
 projects from other sources *MUST NOT* use the `rust-` prefix for source package names,
 and *MUST* follow the general Naming Guidelines instead.
 They also *MUST NOT* have any virtual `Provides` for Rust crates
-(i.e. `Provides: crate(%{crate}) = %{version}`).
+(i.e. `Provides: crate(%{crate}) = %{version}`).
 
 When generating a package for a Rust crate
 that also (or exclusively) contains an application,
 the convention followed by https://pagure.io/fedora-rust/rust2rpm[rust2rpm] is
-to generate a subpackage with a name that matches the crate’s name
-(i.e. the `rust-$crate` source package will have a `$crate` subpackage).
+to generate a subpackage with a name that matches the crate's name
+(i.e. the `rust-$crate` source package will have a `$crate` subpackage).
 If this name does not match expectations,
 it is recommended to either change the name of this subpackage,
 or to add virtual `Provides` for the expected name.
@@ -367,7 +367,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
@@ -380,7 +380,7 @@ about including these additional files in published crates.
 If a crate is also part of a larger project
 and it is not feasible to package the Rust crate separately,
 the Rust crate *MAY* be packaged as `rust-$crate` from different sources
-(i.e. an upstream tarball) _if and only if_ the crate is also published on https://crates.io[crates.io]
+(i.e. an upstream tarball) _if and only if_ the crate is also published on https://crates.io[crates.io]
 under the same name and with matching versions.
 In this case, the subpackage(s) corresponding to Rust crates
 *MUST* have correct virtual `Provides` for the Rust crate.
@@ -429,7 +429,7 @@ is almost entirely automated with several RPM macros:
   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}/`).
+  (i.e. `%{buildroot}/%{cargo_registry}/%{crate}-%{version}/`).
   For crates that provide `bin` targets,
   it installs all built executables into `%{buildroot}/%{_bindir}`.
   If any built executables need to be installed in a different location,
@@ -453,7 +453,7 @@ All packages for Rust crates *MUST* set
 either `%bcond_without check` or `%bcond_with check`.
 The value of this macro affects the behaviour of `%cargo_generate_buildrequires`.
 
-All `%cargo_*` macros (except `%cargo_prep`)
+All `%cargo_*` macros (except `%cargo_prep` and `%cargo_vendor_manifest`)
 accept a set of optional flags / arguments
 that can be used to control the feature flags that are passed to cargo
 (usually to enable optional / non-default features):
@@ -496,16 +496,28 @@ in which passing these flags or arguments is necessary:
   (including `%cargo_license` and `%cargo_license_summary`).
 
 Note that the `-n` flag should only be used in exceptional circumstances,
+for example when enabling a different backend than the one enabled by default,
 and *MUST NOT* be used to avoid missing dependencies
 that are part of the `"default"` feature set of a crate.
 
+When passing any of the `-a` or `-n` flags or an `-f` argument
+to a `%cargo_build` and / or `%cargo_install` macro,
+the same flags MUST also be passed
+to `%cargo_license` and `%cargo_license_summary` (if present).
+Otherwise, the list of generated licenses and the generated license summary
+will not match what is used when the application or library is compiled.
+
+It is recommended to set these flags in a `rust2rpm.toml` config file
+which causes the flags to be injected into generated spec files automatically,
+whereever necessary.
+
 === Dynamically generated `BuildRequires` for crate dependencies
 
 With Semantic Versioning (_"SemVer"_) being
 the only supported versioning scheme for Rust crates,
 dependencies on Rust libraries are almost exclusively specified as
 _"this version or any newer version that is API-compatible with it"_,
-i.e. a range of supported versions.
+i.e. a range of supported versions.
 
 These ranges of supported versions
 need to be correctly translated into RPM dependencies,
@@ -545,7 +557,7 @@ to support resolving dependencies for features and optional dependencies of crat
 The list of crate "features"
 (including any implicitly defined features for optional dependencies)
 *MUST* be kept in sync with the list of subpackages,
-i.e. for every feature `$foo` of the crate `$crate`,
+i.e. for every feature `$foo` of the crate `$crate`,
 there must be a subpackage with name `rust-$crate+$foo-devel`,
 and vice-versa.
 This is required for RPM generators for `Provides` and `Requires`
@@ -574,10 +586,10 @@ 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,
+that the generated `Provides` and `Requires` are sane - for example,
 the following `Provides` and `Requires`
 must be present to ensure correct inter-subpackage dependencies:
 
@@ -585,7 +597,7 @@ must be present to ensure correct inter-subpackage dependencies:
   *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`)
+  and require `crate($crate) = %{version}` (i.e. `rust-$crate-devel`)
 
 Additionally, dependencies on external Rust crates must be as expected:
 
@@ -593,13 +605,13 @@ Additionally, dependencies on external Rust crates must be as expected:
   *MUST* require the virtual `Provides` for all non-optional crate dependencies
 * the `rust-$crate+$feature-devel` subpackages
   *MUST* require the virtual `Provides` for the optional crate dependencies
-  and features that are listed as the feature’s dependencies in crate metadata
+  and features that are listed as the feature's dependencies in crate metadata
 
 === Packaging multiple versions
 
 In most circumstances,
 the latest version of a crate *SHOULD* be packaged,
-and – if possible – packagers *SHOULD* port crates
+and - if possible - packagers *SHOULD* port crates
 to use the latest available version of their dependencies,
 and submit these patches to upstream
 to limit divergence between the upstream project and the Fedora package.
@@ -615,7 +627,7 @@ for multiple versions of a library crate simultaneously:
   by a required SemVer-incompatible library update is very large.
 
 In these cases, a "compat package" can be created for the older version
-(i.e. usually the current version),
+(i.e. usually the current version),
 and the suffix-less package can be updated to the newer version.
 https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
 supports automatically creating "compat packages"
@@ -638,19 +650,19 @@ and two additional rules apply when creating them:
   whether running tests in the old version of the crate
   would cause additional, potentially undesirable dependencies,
   for example, older versions of other dependencies
-  that would require creating additional "compat packages" –
+  that would require creating additional "compat packages" -
   in this case, tests *SHOULD* be disabled
-  (i.e. by flipping the `check` bcond).
+  (i.e. by flipping the `check` bcond).
 
 === The `check` bcond
 
 The behaviour of some RPM macros
 depends on the presence and value of the `_with_check` macro,
-i.e. if `%bcond_without check` or `%bcond_with check`
-are used in the spec file – notably,
+i.e. if `%bcond_without check` or `%bcond_with check`
+are used in the spec file - notably,
 the `%cargo_generate_buildrequires` macro only includes `dev-dependencies`
-(i.e. dependencies that are only used
-for compiling and / or running a project’s test suite with cargo)
+(i.e. dependencies that are only used
+for compiling and / or running a project's test suite with cargo)
 if the `check` bconf is enabled.
 
 Additionally, packages for Rust crates or workspace projects
@@ -681,7 +693,7 @@ Rust crates can have three different kinds of tests in their test suites:
   to ensure that code snippets in documentation for public methods
   are correct and continue to compile.
 
-By default, running `cargo test` (i.e. by calling the `%cargo_test` macro),
+By default, running `cargo test` (i.e. by calling the `%cargo_test` macro),
 all three kinds of tests are run.
 They can also be invoked separately
 (for example, because parts of the test suite or large data files are
@@ -725,7 +737,7 @@ has basic support for generating spec files for this type of package
 by running `rust2rpm path/to/Cargo.toml` in unpacked upstream sources.
 
 Packages that fall into this category *MUST NOT* ship crate sources in `%{cargo_registry}`,
-i.e. they cannot ship `-devel` subpackages
+i.e. they cannot ship `-devel` subpackages
 that contain crate sources or have subpackages
 that have virtual provides for `crate(...) = %{version}`.
 
@@ -735,7 +747,7 @@ Rust applications that are "crates"
 but which are not published on https://crates.io[crates.io]
 *MUST* be named according to the generic
 https://docs.fedoraproject.org/en-US/packaging-guidelines/Naming/[Naming Guidelines],
-i.e. they *MUST NOT* use a `rust-` prefix for the source package name.
+i.e. they *MUST NOT* use a `rust-` prefix for the source package name.
 
 === Package sources
 
@@ -760,11 +772,11 @@ https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
 has basic support for generating spec files for this type of package
 by running `rust2rpm path/to/Cargo.toml` in unpacked upstream sources,
 (where `./Cargo.toml` must be the path to the "workspace root",
-i.e. the `Cargo.toml` file that contains the `[workspace]` table).
+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}`,
-i.e. they cannot ship `-devel` subpackages that contain crate sources
+i.e. they cannot ship `-devel` subpackages that contain crate sources
 or have any subpackages that have virtual provides for `crate(...) = %{version}`.
 
 === Package naming
@@ -772,7 +784,7 @@ or have any subpackages that have virtual provides for `crate(...) = %{version}`
 Rust projects that are organized as "cargo workspaces"
 *MUST* be named according to the generic
 https://docs.fedoraproject.org/en-US/packaging-guidelines/Naming/[Naming Guidelines],
-i.e. they *MUST NOT* use a `rust-` prefix for the source package name.
+i.e. they *MUST NOT* use a `rust-` prefix for the source package name.
 
 === Package sources
 
@@ -823,7 +835,7 @@ that the default link:#_compiler_flags[compiler flags] are passed to rustc.
 
 Handling of projects that include both C/C++ and Rust code
 depends on how building the Rust code is integrated
-into the project’s build system.
+into the project's build system.
 
 Independent of the specific setup,
 the correct link:#_compiler_flags[compiler flags] *MUST* be passed to rustc,
@@ -837,7 +849,7 @@ Projects with build systems that call cargo internally to build Rust components
 as other projects that build Rust code with cargo.
 
 Packages *MUST* ensure that the cargo calls
-that are internal to the project’s build system
+that are internal to the project's build system
 do not pass flags or arguments that are incompatible
 with either the default link:#_compiler_flags[compiler flags] or cargo options
 that are set in the `%cargo_build` macro or configured by `%cargo_prep`.

From cae78bbbce5837bb2663af728667f3e3363808c5 Mon Sep 17 00:00:00 2001
From: Jason Tibbitts 
Date: Mar 28 2024 16:59:23 +0000
Subject: [PATCH 120/232] Move specs to examples directory


Extract the sample spec files, place them in the examples directory and
include them from the main document.

---

diff --git a/guidelines/modules/ROOT/examples/haskell-binary-library.spec b/guidelines/modules/ROOT/examples/haskell-binary-library.spec
new file mode 100644
index 0000000..de7a496
--- /dev/null
+++ b/guidelines/modules/ROOT/examples/haskell-binary-library.spec
@@ -0,0 +1,81 @@
+%global pkg_name @PACKAGE@
+
+Name:           %{pkg_name}
+Version:        @VERSION@
+Release:        1%{?dist}
+Summary:        @SUMMARY@
+
+License:        @LICENSE@
+URL:            https://hackage.haskell.org/package/%{name}
+Source:         https://hackage.haskell.org/package/%{name}-%{version}/%{name}-%{version}.tar.gz
+
+BuildRequires:  ghc-Cabal-devel
+BuildRequires:  ghc-rpm-macros
+BuildRequires:  ghc-base-prof
+
+%description
+@DESCRIPTION@
+
+
+%package -n ghc-%{name}
+Summary:        Haskell %{name} library
+
+%description -n ghc-%{name}
+This package contains the Haskell %{name} library.
+
+
+%package -n ghc-%{name}-devel
+Summary:        Haskell %{name} library development files
+Requires:       ghc-compiler = %{ghc_version}
+Requires:       ghc-%{name} = %{version}-%{release}
+
+%description -n ghc-%{name}-devel
+This package provides the Haskell %{pkg_name} library development files.
+
+
+%package -n ghc-%{name}-doc
+Summary:        Haskell %{pkg_name} library documentation
+BuildArch:      noarch
+
+%description -n ghc-%{name}-doc
+This package provides the Haskell %{pkg_name} library documentation.
+
+
+%package -n ghc-%{name}-prof
+Summary:        Haskell %{pkg_name} profiling library
+Requires:       ghc-%{name}-devel%{?_isa} = %{version}-%{release}
+Supplements:    (ghc-%{name}-devel and ghc-prof)
+
+%description -n ghc-%{name}-prof
+This package provides the Haskell %{pkg_name} profiling library.
+
+
+%prep
+%setup -q
+
+
+%build
+%ghc_lib_build
+
+
+%install
+%ghc_lib_install
+
+
+%files
+%license LICENSE
+%{_bindir}/%{name}
+
+
+%files -n ghc-%{name} -f ghc-%{name}.files
+%license LICENSE
+
+
+%files -n ghc-%{name}-devel -f ghc-%{name}-devel.files
+
+
+%files -n ghc-%{name}-doc -f ghc-%{name}-doc.files
+%license LICENSE
+
+
+%files -n ghc-%{name}-prof -f ghc-%{name}-prof.files
diff --git a/guidelines/modules/ROOT/examples/haskell-binary-only.spec b/guidelines/modules/ROOT/examples/haskell-binary-only.spec
new file mode 100644
index 0000000..28b0421
--- /dev/null
+++ b/guidelines/modules/ROOT/examples/haskell-binary-only.spec
@@ -0,0 +1,32 @@
+Name:           @PACKAGE@
+Version:        @VERSION@
+Release:        1%{?dist}
+Summary:        @SUMMARY@
+
+License:        @LICENSE@
+URL:            https://hackage.haskell.org/package/%{name}
+Source:         https://hackage.haskell.org/package/%{name}-%{version}/%{name}-%{version}.tar.gz
+
+BuildRequires:  ghc-Cabal-devel
+BuildRequires:  ghc-rpm-macros
+BuildRequires:  ghc-base-static
+
+%description
+@DESCRIPTION@
+
+
+%prep
+%setup -q
+
+
+%build
+%ghc_bin_build
+
+
+%install
+%ghc_bin_install
+
+
+%files
+%license LICENSE
+%{_bindir}/%{name}
diff --git a/guidelines/modules/ROOT/examples/haskell-library-only.spec b/guidelines/modules/ROOT/examples/haskell-library-only.spec
new file mode 100644
index 0000000..f8c3f7b
--- /dev/null
+++ b/guidelines/modules/ROOT/examples/haskell-library-only.spec
@@ -0,0 +1,70 @@
+%global pkg_name @PACKAGE@
+
+Name:           ghc-%{pkg_name}
+Version:        @VERSION@
+Release:        1%{?dist}
+Summary:        @SUMMARY@
+
+License:        @LICENSE@
+URL:            https://hackage.haskell.org/package/%{pkg_name}
+Source:         https://hackage.haskell.org/package/%{pkg_name}-%{version}/%{pkg_name}-%{version}.tar.gz
+
+BuildRequires:  ghc-Cabal-devel
+BuildRequires:  ghc-rpm-macros
+BuildRequires:  ghc-base-prof
+
+%description
+@DESCRIPTION@
+
+%package devel
+Summary:        Haskell %{pkg_name} library development files
+Provides:       %{name}-static = %{version}-%{release}
+Provides:       %{name}-static%{?_isa} = %{version}-%{release}
+Requires:       ghc-compiler = %{ghc_version}
+Requires:       %{name}%{?_isa} = %{version}-%{release}
+
+%description devel
+This package provides the Haskell %{pkg_name} library development files.
+
+
+%package doc
+Summary:        Haskell %{pkg_name} library documentation
+BuildArch:      noarch
+
+%description doc
+This package provides the Haskell %{pkg_name} library documentation.
+
+
+%package prof
+Summary:        Haskell %{pkg_name} profiling library
+Requires:       %{name}-devel%{?_isa} = %{version}-%{release}
+Supplements:    (%{name}-devel and ghc-prof)
+
+%description prof
+This package provides the Haskell %{pkg_name} profiling library.
+
+
+%prep
+%setup -q -n %{pkg_name}-%{version}
+
+
+%build
+%ghc_lib_build
+
+
+%install
+%ghc_lib_install
+
+
+%files -f %{name}.files
+%license LICENSE
+
+
+%files devel -f %{name}-devel.files
+
+
+%files doc -f %{name}-doc.files
+%license LICENSE
+
+
+%files prof -f %{name}-prof.files
diff --git a/guidelines/modules/ROOT/pages/Haskell.adoc b/guidelines/modules/ROOT/pages/Haskell.adoc
index fbe3c60..02c4f10 100644
--- a/guidelines/modules/ROOT/pages/Haskell.adoc
+++ b/guidelines/modules/ROOT/pages/Haskell.adoc
@@ -17,203 +17,24 @@ There are three types of Haskell Cabal packages: library (Lib), binary only (Bin
 
 === Library Only
 
-....
-%global pkg_name @PACKAGE@
-
-Name:           ghc-%{pkg_name}
-Version:        @VERSION@
-Release:        1%{?dist}
-Summary:        @SUMMARY@
-
-License:        @LICENSE@
-URL:            https://hackage.haskell.org/package/%{pkg_name}
-Source:         https://hackage.haskell.org/package/%{pkg_name}-%{version}/%{pkg_name}-%{version}.tar.gz
-
-BuildRequires:  ghc-Cabal-devel
-BuildRequires:  ghc-rpm-macros
-BuildRequires:  ghc-base-prof
-
-%description
-@DESCRIPTION@
-
-%package devel
-Summary:        Haskell %{pkg_name} library development files
-Provides:       %{name}-static = %{version}-%{release}
-Provides:       %{name}-static%{?_isa} = %{version}-%{release}
-Requires:       ghc-compiler = %{ghc_version}
-Requires:       %{name}%{?_isa} = %{version}-%{release}
-
-%description devel
-This package provides the Haskell %{pkg_name} library development files.
-
-
-%package doc
-Summary:        Haskell %{pkg_name} library documentation
-BuildArch:      noarch
-
-%description doc
-This package provides the Haskell %{pkg_name} library documentation.
-
-
-%package prof
-Summary:        Haskell %{pkg_name} profiling library
-Requires:       %{name}-devel%{?_isa} = %{version}-%{release}
-Supplements:    (%{name}-devel and ghc-prof)
-
-%description prof
-This package provides the Haskell %{pkg_name} profiling library.
-
-
-%prep
-%setup -q -n %{pkg_name}-%{version}
-
-
-%build
-%ghc_lib_build
-
-
-%install
-%ghc_lib_install
-
-
-%files -f %{name}.files
-%license LICENSE
-
-
-%files devel -f %{name}-devel.files
-
-
-%files doc -f %{name}-doc.files
-%license LICENSE
-
-
-%files prof -f %{name}-prof.files
-....
+[source,RPMspec]
+----
+include::{examplesdir}/haskell-library-only.spec[]
+----
 
 === Binary Only
 
-....
-Name:           @PACKAGE@
-Version:        @VERSION@
-Release:        1%{?dist}
-Summary:        @SUMMARY@
-
-License:        @LICENSE@
-URL:            https://hackage.haskell.org/package/%{name}
-Source:         https://hackage.haskell.org/package/%{name}-%{version}/%{name}-%{version}.tar.gz
-
-BuildRequires:  ghc-Cabal-devel
-BuildRequires:  ghc-rpm-macros
-BuildRequires:  ghc-base-static
-
-%description
-@DESCRIPTION@
-
-
-%prep
-%setup -q
-
-
-%build
-%ghc_bin_build
-
-
-%install
-%ghc_bin_install
-
-
-%files
-%license LICENSE
-%{_bindir}/%{name}
-....
-
+[source,RPMspec]
+----
+include::{examplesdir}/haskell-binary-only.spec[]
+----
 
 === BinLib
 
-....
-%global pkg_name @PACKAGE@
-
-Name:           %{pkg_name}
-Version:        @VERSION@
-Release:        1%{?dist}
-Summary:        @SUMMARY@
-
-License:        @LICENSE@
-URL:            https://hackage.haskell.org/package/%{name}
-Source:         https://hackage.haskell.org/package/%{name}-%{version}/%{name}-%{version}.tar.gz
-
-BuildRequires:  ghc-Cabal-devel
-BuildRequires:  ghc-rpm-macros
-BuildRequires:  ghc-base-prof
-
-%description
-@DESCRIPTION@
-
-
-%package -n ghc-%{name}
-Summary:        Haskell %{name} library
-
-%description -n ghc-%{name}
-This package contains the Haskell %{name} library.
-
-
-%package -n ghc-%{name}-devel
-Summary:        Haskell %{name} library development files
-Requires:       ghc-compiler = %{ghc_version}
-Requires:       ghc-%{name} = %{version}-%{release}
-
-%description -n ghc-%{name}-devel
-This package provides the Haskell %{pkg_name} library development files.
-
-
-%package -n ghc-%{name}-doc
-Summary:        Haskell %{pkg_name} library documentation
-BuildArch:      noarch
-
-%description -n ghc-%{name}-doc
-This package provides the Haskell %{pkg_name} library documentation.
-
-
-%package -n ghc-%{name}-prof
-Summary:        Haskell %{pkg_name} profiling library
-Requires:       ghc-%{name}-devel%{?_isa} = %{version}-%{release}
-Supplements:    (ghc-%{name}-devel and ghc-prof)
-
-%description -n ghc-%{name}-prof
-This package provides the Haskell %{pkg_name} profiling library.
-
-
-%prep
-%setup -q
-
-
-%build
-%ghc_lib_build
-
-
-%install
-%ghc_lib_install
-
-
-%files
-%license LICENSE
-%{_bindir}/%{name}
-
-
-%files -n ghc-%{name} -f ghc-%{name}.files
-%license LICENSE
-
-
-%files -n ghc-%{name}-devel -f ghc-%{name}-devel.files
-
-
-%files -n ghc-%{name}-doc -f ghc-%{name}-doc.files
-%license LICENSE
-
-
-%files -n ghc-%{name}-prof -f ghc-%{name}-prof.files
-....
-
+[source,RPMspec]
+----
+include::{examplesdir}/haskell-binary-library.spec[]
+----
 
 == Package Naming
 

From 2752edbbb41b731ab8dc1842d48cb7cd14f9aeab Mon Sep 17 00:00:00 2001
From: Jason Tibbitts 
Date: Mar 28 2024 16:59:23 +0000
Subject: [PATCH 121/232] Semantic linebreaks.


Add semantic linebreaks throughout the document.

---

diff --git a/guidelines/modules/ROOT/pages/Haskell.adoc b/guidelines/modules/ROOT/pages/Haskell.adoc
index 02c4f10..5795ac3 100644
--- a/guidelines/modules/ROOT/pages/Haskell.adoc
+++ b/guidelines/modules/ROOT/pages/Haskell.adoc
@@ -1,19 +1,41 @@
 = Haskell Packaging Guidelines
 
-This page documents the guidelines and conventions for packaging Haskell projects in Fedora.
-
-https://haskell.org/ghc[GHC] (Glasgow Haskell Compiler) is the current mainstream Haskell compiler.
-Most Haskell packages are released on https://hackage.haskell.org[Hackage] and use the https://www.haskell.org/cabal/[Cabal] package system. So the current guidelines largely focus on packaging for GHC using Cabal.
+This page documents the guidelines and conventions
+for packaging Haskell projects in Fedora.
+
+https://haskell.org/ghc[GHC] (Glasgow Haskell Compiler)
+is the current mainstream Haskell compiler.
+Most Haskell packages are released on
+https://hackage.haskell.org[Hackage]
+and use the
+https://www.haskell.org/cabal/[Cabal]
+package system.
+So the current guidelines largely focus
+on packaging for GHC using Cabal.
 
 == Spec file templates
 
-Spec files in line with these templates are generated automatically by the https://src.fedoraproject.org/rpms/cabal-rpm[cabal-rpm] packaging tool
-which also adds dependencies listed in the package's `+.cabal+` configuration file.
-Most packages should then build, though for some packages it may be necessary to specify some additional BuildRequires and/or Requires, and to check non-Haskell devel dependencies.
-
-Standardizing the packaging helps to lower the maintenance burden across Fedora's Haskell packages.
-
-There are three types of Haskell Cabal packages: library (Lib), binary only (Bin), and binary with library (BinLib):
+Spec files in line with these templates
+are generated automatically by the
+https://src.fedoraproject.org/rpms/cabal-rpm[cabal-rpm]
+packaging tool
+which also adds dependencies
+listed in the package's
+`+.cabal+` configuration file.
+Most packages should then build,
+though for some packages it may be necessary
+to specify some additional BuildRequires
+and/or Requires,
+and to check non-Haskell devel dependencies.
+
+Standardizing the packaging
+helps to lower the maintenance burden
+across Fedora's Haskell packages.
+
+There are three types of Haskell Cabal packages:
+library (Lib),
+binary only (Bin),
+and binary with library (BinLib):
 
 === Library Only
 
@@ -38,73 +60,169 @@ include::{examplesdir}/haskell-binary-library.spec[]
 
 == Package Naming
 
-Haskell Bin packages should follow the usual Fedora Package Naming Guidelines for base package naming: i.e., follow the upstream name. Examples include projects like `+alex+` and `+cabal-install+`.
-
-The names of Haskell Lib packages, packaged for `+ghc+`, are prefixed by "ghc-". For example the Haskell aeson library package is named `+ghc-aeson+`, and the Haskell X11 library package is named `+ghc-X11+`, etc.
-
-Haskell BinLib packages should be named like a Bin package if the most important part they provide is an executable (eg `+hlint+`, `+ShellCheck+`, and `+pandoc+`), otherwise they should be named and packaged as a Lib package (eg `+ghc-hakyll+` (has a setup executable), `+ghc-vty+` (has demo executables)) if they are actually a library that includes an helper executable or demo or minor utility. In this case typically the executable should live in the devel subpackage (or maybe the library base package if it is used at runtime).
-
-Note that having different Haskell source packages named "ghc-xyz" and "xyz" is not allowed since they would both correspond to the same upstream package named "xyz" on Hackage.
-
-BinLib packages should subpackage their libraries with naming following Lib packages.
-For example the `+pandoc+` BinLib package has library subpackages
+Haskell Bin packages should follow
+the usual Fedora Package Naming Guidelines
+for base package naming:
+i.e., follow the upstream name.
+Examples include projects like `+alex+`
+and `+cabal-install+`.
+
+The names of Haskell Lib packages,
+packaged for `+ghc+`,
+are prefixed by "ghc-".
+For example
+the Haskell aeson library package
+is named `+ghc-aeson+`,
+and the Haskell X11 library package
+is named `+ghc-X11+`, etc.
+
+Haskell BinLib packages
+should be named like a Bin package
+if the most important part they provide
+is an executable
+(eg `+hlint+`,
+`+ShellCheck+`,
+and `+pandoc+`),
+otherwise they should be named and packaged
+as a Lib package
+(eg `+ghc-hakyll+` (has a setup executable),
+`+ghc-vty+` (has demo executables))
+if they are actually a library
+that includes an helper executable
+or demo or minor utility.
+In this case typically
+the executable should live
+in the devel subpackage
+(or maybe the library base package
+if it is used at runtime).
+
+Note that
+having different Haskell source packages
+named "ghc-xyz"
+and "xyz"
+is not allowed
+since they would both correspond
+to the same upstream package
+named "xyz" on Hackage.
+
+BinLib packages
+should subpackage their libraries
+with naming following Lib packages.
+For example
+the `+pandoc+` BinLib package
+has library subpackages
 
 * `+ghc-pandoc+` for the shared library,
 * `+ghc-pandoc-devel+` for devel files and the static library,
 * `+ghc-pandoc-prof+` for the profiling static library,
 * `+ghc-pandoc-doc+` for the library's extracted development documentation.
 
-If a library is packaged for more than one Haskell compiler or interpreter, the base name should instead be prefixed with `+haskell+`, e.g. `+haskell-X11+`. Such a package would then have subpackages for each compiler and/or interpreter it is built for (e.g. `+ghc-X11+`, `+hugs98-X11+`, etc).
-
-Package naming preserves case to follow the upstream naming conventions as closely as possible, including package dependencies.
+If a library is packaged for more than one Haskell compiler
+or interpreter,
+the base name should instead
+be prefixed with `+haskell+`,
+e.g. `+haskell-X11+`.
+Such a package would then have subpackages
+for each compiler and/or interpreter
+it is built for
+(e.g. `+ghc-X11+`,
++hugs98-X11+`,
+etc).
+
+Package naming preserves case
+to follow the upstream naming conventions
+as closely as possible,
+including package dependencies.
 
 == Headers
 
-The macro `+pkg_name+` is used to carry the name of the upstream library package (i.e. without the Fedora "ghc-" prefix).
-It should be defined at the top of Lib and BinLib packages:
+The macro `+pkg_name+`
+is used to carry the name of the upstream library package
+(i.e. without the Fedora "ghc-" prefix).
+It should be defined at the top of Lib
+and BinLib packages:
 
 `+%global pkg_name +`
 
 == Cabal Flags
 
-If needed Cabal flags for build options should be set by changing the package's `+.cabal+` file: this can usually be done with the `+cabal-tweak-flag+` script to avoid having to carry and maintain patches for this.
+If needed
+Cabal flags for build options
+should be set by changing the package's `+.cabal+` file:
+this can usually be done with the `+cabal-tweak-flag+` script
+to avoid having to carry and maintain patches for this.
 
-For example `+cabal-tweak-flag systemlib True+` might enable a flag to use a system library dependency.
+For example
+`+cabal-tweak-flag systemlib True+`
+might enable a flag
+to use a system library dependency.
 
-`+%cabal_configure_options+` can be set to pass other options to Cabal.
+`+%cabal_configure_options+`
+can be set to pass other options to Cabal.
 
-Modifying the `+.cabal+` file flags defaults allows packagers and tools like `+cabal-rpm+` to track actual package dependencies correctly.
+Modifying the `+.cabal+` file flags defaults
+allows packagers and tools like `+cabal-rpm+`
+to track actual package dependencies correctly.
 
 == Dependencies
-The `+cabal-tweak-dep-ver+` script can used to change version bounds of dependencies in the package's .cabal file: `+cabal-tweak-dep-ver deppkg oldbound newbound+`
+The `+cabal-tweak-dep-ver+` script
+can used to change version bounds of dependencies
+in the package's .cabal file:
+`+cabal-tweak-dep-ver deppkg oldbound newbound+`
 
 eg: `+cabal-tweak-dep-ver base '< 4.16' '< 4.17'+`
 
-Similarly `+cabal-tweak-drop-dep+` for dropping a redundant dependency (eg a compatibility dummy package).
+Similarly `+cabal-tweak-drop-dep+`
+for dropping a redundant dependency
+(eg a compatibility dummy package).
 
 eg: `+cabal-tweak-drop-dep mtl-compat+`
 
-Spec file build dependencies are generated by the `+cabal-rpm+` packaging tool.
+Spec file build dependencies
+are generated by the `+cabal-rpm+` packaging tool.
 
-Binary RPM dependencies for Haskell libraries are automatically generated at build-time by the `+ghc-deps.sh+` script.
+Binary RPM dependencies for Haskell libraries
+are automatically generated at build-time
+by the `+ghc-deps.sh+` script.
 
 == Shared and static library linking
 
-GHC uses static libraries for linking by default. Lib and BinLib packages should provide static, shared, and profiling libraries:
+GHC uses static libraries for linking by default.
+Lib and BinLib packages should provide static,
+shared,
+and profiling libraries:
 
 * the shared library lives in the base library package,
-* the static library and interface development files in the -devel subpackage,
-* and the profiling library and profiling interface files in the -prof subpackage.
 
-Since GHC assumes static versions of libraries are installed they need to be in the devel subpackage and it doesn't make sense to subpackage them.
+* the static library and interface development files
+in the -devel subpackage,
 
-Executables in Bin and BinLib packages should be statically linked for portability.
+* and the profiling library
+and profiling interface files
+in the -prof subpackage.
 
-Due to how GHC links shared libraries using `+--no-as-needed+` they generate a lot of rpmlint `+E: undefined-non-weak-symbol+` errors, this is unfortunately currently expected (see these https://gitlab.haskell.org/ghc/ghc/-/issues/17157[upstream] https://gitlab.haskell.org/ghc/ghc/-/issues/23216[issues]).
+Since GHC assumes static versions of libraries are installed
+they need to be in the devel subpackage
+and it doesn't make sense to subpackage them.
+
+Executables in Bin and BinLib packages
+should be statically linked for portability.
+
+Due to how GHC links shared libraries using
+`+--no-as-needed+`
+they generate a lot of rpmlint
+`+E: undefined-non-weak-symbol+` errors,
+this is unfortunately currently expected
+(see these
+https://gitlab.haskell.org/ghc/ghc/-/issues/17157[upstream]
+https://gitlab.haskell.org/ghc/ghc/-/issues/23216[issues]).
 
 == RPM Macros
 
-The templates all have buildrequires for ghc-rpm-macros, which provides https://src.fedoraproject.org/rpms/ghc-rpm-macros/blob/master/f/macros.ghc[macros.ghc] to assist with packaging Haskell Cabal packages.
+The templates all have buildrequires for ghc-rpm-macros,
+which provides
+https://src.fedoraproject.org/rpms/ghc-rpm-macros/blob/master/f/macros.ghc[macros.ghc]
+to assist with packaging Haskell Cabal packages.
 
 ....
 BuildRequires:  ghc-rpm-macros
@@ -117,11 +235,13 @@ The main commonly used macros are:
 * %ghc_bin_install
 * %ghc_lib_install
 
-They are used in the templates and explained in more detail below.
+They are used in the templates
+and explained in more detail below.
 
 == Bin packages
 
-Executables are statically linked to Haskell libraries by default.
+Executables are statically linked
+to Haskell libraries by default.
 
 ....
 %build
@@ -134,7 +254,9 @@ Executables are statically linked to Haskell libraries by default.
 
 `+%ghc_bin_build+` is used to configure and build bin packages. It runs:
 
-* `+%cabal_configure+`: configure the package for building and dynamic linking.
+* `+%cabal_configure+`: configure the package for building
+and dynamic linking.
+
 * `+%cabal build+`: builds the package.
 
 `+%ghc_bin_install+` is used to install bin packages. It runs:
@@ -170,17 +292,38 @@ Both Lib and BinLib have:
 %ghc_lib_install
 ....
 
-`+%ghc_lib_build+` is used to configure, build and generate documentation for Lib and BinLib packages. It runs:
+`+%ghc_lib_build+` is used to configure,
+build
+and generate documentation
+for Lib and BinLib packages.
+It runs:
+
+* `+%cabal_configure --ghc -p+`: configures the package
+for building with ghc
+and profiling.
+Libraries should build profiling versions
+of their static libraries.
 
-* `+%cabal_configure --ghc -p+`: configures the package for building with ghc and profiling. Libraries should build profiling versions of their static libraries.
 * `+%cabal build+`: builds the package.
-* `+%cabal haddock+`: generates HTML library documentation from the source code.
-** If documentation is failing to build for some reason, `+%ghc_lib_build_without_haddock+` can be used instead of `+%ghc_lib_build+` to disable haddock generation.
 
-`+%ghc_lib_install+` is used to install Lib and BinLib packages. It runs:
+* `+%cabal haddock+`: generates HTML library documentationr
+ from the source code.
+
+** If documentation is failing to build for some reason,
+`+%ghc_lib_build_without_haddock+`
+can be used instead of
+`+%ghc_lib_build+`
+to disable haddock generation.
+
+`+%ghc_lib_install+` is used to install Lib and BinLib packages.
+It runs:
+
+* `+%cabal_install+`: installs the package
+without registering it in ghc-pkg.
+
+* `+%cabal_pkg_conf+`: creates ghc-pkg .conf metadata filer
+ for package installation time
 
-* `+%cabal_install+`: installs the package without registering it in ghc-pkg.
-* `+%cabal_pkg_conf+`: creates ghc-pkg .conf metadata file for package installation time
 * `+%ghc_gen_filelists+`: generates rpm filelists.
 
 == Debuginfo
@@ -191,19 +334,33 @@ generated using profiling libraries.
 
 == Directories
 
-GHC libraries are installed under `+%ghclibdir/%{pkg_name}-%{version}+`:
+GHC libraries are installed under
+`+%ghclibdir/%{pkg_name}-%{version}+`:
 
-Library documentation lives under `+%ghclibdocdir/%{pkg_name}-%{version}+`.
+Library documentation lives under
+`+%ghclibdocdir/%{pkg_name}-%{version}+`.
 
 == File lists
 
-Filelists for shared and devel library subpackages are generated through `+%ghc_lib_install+` using the macro `+%ghc_gen_filelists+`.
+Filelists for shared and devel library subpackages
+are generated through
+`+%ghc_lib_install+`
+using the macro
+`+%ghc_gen_filelists+`.
 
-It generates the filelists `+ghc-%{pkg_name}.files+`, `+ghc-%{pkg_name}-devel.files+`, `+ghc-%{pkg_name}-prof.files+`, and `+ghc-%{pkg_name}-doc.files+`.
+It generates the filelists
+`+ghc-%{pkg_name}.files+`,
+`+ghc-%{pkg_name}-devel.files+`,
+`+ghc-%{pkg_name}-prof.files+`,
+and `+ghc-%{pkg_name}-doc.files+`.
 
 == Compiling non-Cabal packages
 
-Packages compiling Haskell code without Cabal, i.e., directly with `+ghc+` or `+ghc --make+`, should use `+-O1+` optimization, like Cabal does by default.
+Packages compiling Haskell code without Cabal,
+i.e., directly with `+ghc+`
+or `+ghc --make+`,
+should use `+-O1+` optimization,
+like Cabal does by default.
 
 == References
 

From a9c71890254c7d87cf356713f738bbbe7e5afef6 Mon Sep 17 00:00:00 2001
From: Jason Tibbitts 
Date: Mar 28 2024 16:59:23 +0000
Subject: [PATCH 122/232] Escape four macros.


There were four macros written in plain text instead of escaped and
monospaced.

---

diff --git a/guidelines/modules/ROOT/pages/Haskell.adoc b/guidelines/modules/ROOT/pages/Haskell.adoc
index 5795ac3..fe43190 100644
--- a/guidelines/modules/ROOT/pages/Haskell.adoc
+++ b/guidelines/modules/ROOT/pages/Haskell.adoc
@@ -230,10 +230,10 @@ BuildRequires:  ghc-rpm-macros
 
 The main commonly used macros are:
 
-* %ghc_bin_build
-* %ghc_lib_build
-* %ghc_bin_install
-* %ghc_lib_install
+* `+%ghc_bin_build+`
+* `+%ghc_lib_build+`
+* `+%ghc_bin_install+`
+* `+%ghc_lib_install+`
 
 They are used in the templates
 and explained in more detail below.

From 0a5966a417957ba248e1e878d336b453c5ac0523 Mon Sep 17 00:00:00 2001
From: Otto Liljalaakso 
Date: Mar 28 2024 17:24:49 +0000
Subject: [PATCH 123/232] Fix formatting in Dependency Types section


1. Add missing backtick
2. Remove whitespace from start of line, which confuses po4a

Fixes #1316

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 32d8296..df15df1 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -789,8 +789,8 @@ If the functionality should be available by default for users,
 `Recommends` SHOULD be used,
 and `Suggests` otherwise.
 Alternatively, the reverse dependencies
-`Supplements` or `Enhances
- may be used in the other package.
+`Supplements` or `Enhances`
+may be used in the other package.
 See xref:WeakDependencies.adoc[Packaging:WeakDependencies]
 for guidelines on using those dependency types.
 

From 2d6315138f419d55a68526a63956db34406b4d9a Mon Sep 17 00:00:00 2001
From: Otto Liljalaakso 
Date: Mar 29 2024 16:44:33 +0000
Subject: [PATCH 124/232] Avoid mentioning X when defining a desktop app


Simply replacing the term "X window" with simple "window" also covers
Wayland, which is already the default in Fedora.

Fixes #1315

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index df15df1..988a295 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -1870,7 +1870,7 @@ and systemd-managed services are xref:Systemd.adoc[here].
 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
+a GUI application is defined as any application which draws a 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],

From 5ea395dac1d08af076b2eafa9885a7cc11cb7db5 Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Apr 03 2024 14:16:38 +0000
Subject: [PATCH 125/232] %{py3_shebang_flags} are added even if already there


This was always that way, we just assumed it wasn't.
Repeated flags are OK.

Reported by @jrohel

---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 741d464..28ce5d8 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1386,8 +1386,7 @@ If a directory is given, all `+.py+` files in it are fixed, recursively.
 (So, if you need to fix shebangs in files not named `+*.py+`,
 you need to list each file separately or use a Shell glob,
 such as `+%{buildroot}%{_libexecdir}/mytool/*+`.)
-Existing flags are preserved and `+%{py3_shebang_flags}+` are added
-(if not there already).
+Existing flags are preserved and `+%{py3_shebang_flags}+` are added.
 +
 For example,
 `+#! /usr/bin/env python+` will be changed to `+#! /usr/bin/python3 -s+`

From 646280d1d86ad686f1a175f9b0ad42bb22c14d9d Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Apr 03 2024 14:16:38 +0000
Subject: [PATCH 126/232] Update the location of the setuptools documentation wrt removing extras


---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 28ce5d8..6253210 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -845,7 +845,7 @@ from either the main package or another extras subpackage.
 
 Note that removing extras is discouraged in
 https://setuptools.readthedocs.io/en/latest/userguide/dependency_management.html#optional-dependencies[setuptools documentation]
-(see the final paragraph of the linked section).
+(see the _Tip_ box near the end of the _Optional dependencies_ section).
 
 ==== Automatic Requires for extras
 

From 380c909c98915b533be3cfed0ca3cee69046fcf1 Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Apr 03 2024 14:16:38 +0000
Subject: [PATCH 127/232] Bump the last-reviewed date in Python


---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 6253210..0bb8aed 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1,5 +1,5 @@
 = Python Packaging Guidelines
-:last-reviewed: 2021-06-04
+:last-reviewed: 2024-04-03
 
 ////
 

From f5037c5ae6f4a1ac36f30e4a50c1a5f953b75736 Mon Sep 17 00:00:00 2001
From: Fabio Valentini 
Date: Apr 03 2024 22:08:43 +0000
Subject: [PATCH 128/232] Rust: clarifications and docs for %cargo_install_{bin,lib} macros


---

diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc
index 8047681..6bbea2c 100644
--- a/guidelines/modules/ROOT/pages/Rust.adoc
+++ b/guidelines/modules/ROOT/pages/Rust.adoc
@@ -1,6 +1,6 @@
 = Rust Packaging Guidelines
 
-:last-reviewed: 2024-03-14
+:last-reviewed: 2024-04-03
 
 https://www.rust-lang.org[Rust] is a strongly and statically typed,
 compiled programming language
@@ -215,6 +215,9 @@ was added in version 25 of cargo-rpm-macros and rust2rpm.
   An RPM generator parses this file
   and generates appropriate virtual `Provides` for all bundled crates,
   as is required for any bundled dependencies.
+*  Packages that build with vendored dependencies
+  *MUST NOT* provide a Rust library interface (i.e. in `-devel` subpackages),
+  because the resulting packages would have broken dependencies.
 
 Typically, the `%prep` scriptlet will look like this
 when using vendored dependencies
@@ -310,7 +313,7 @@ with both the general and the Rust Packaging Guidelines.
 
 Additionally, due to some properties of packages for Rust crates
 (i.e. subpackages that correspond to crate features / optional dependencies),
-it is necessary to re-run https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
+https://pagure.io/fedora-rust/rust2rpm[rust2rpm] *MUST* be re-run
 for every new version of a crate
 to ensure that generated feature subpackages
 stays in sync with crate metadata.
@@ -319,17 +322,54 @@ stays in sync with crate metadata.
 
 The canonical source of Rust crates is https://crates.io[crates.io].
 
-Rust crates that are published on https://crates.io[crates.io]
+==== Crates with Rust library interface
+
+Crates that are published on https://crates.io[crates.io]
+and that are intended to provide a Rust library interface
 *MUST* be packaged with `rust-$crate` as the name of the source package
 (where `$crate` is the name of the project on https://crates.io[crates.io]).
-Packages for Rust crates that are generated with https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
-follow to this pattern.
+This ensures that there are no name collisions
+between Rust crates published on https://crates.io[crates.io]
+and Rust crates packaged for Fedora.
 
-On the other hand,
-projects from other sources *MUST NOT* use the `rust-` prefix for source package names,
+Projects from sources other than https://crates.io[crates.io]
+*MUST NOT* use the `rust-` prefix for source package names,
 and *MUST* follow the general Naming Guidelines instead.
-They also *MUST NOT* have any virtual `Provides` for Rust crates
-(i.e. `Provides: crate(%{crate}) = %{version}`).
+In this case, the guidelines for either
+link:#_rust_applications_non_crates_io_crates[single-crate Rust applications] or
+link:#_rust_applications_cargo_workspace_projects[cargo workspaces] apply.
+
+If a crate is also part of a larger project
+and it is not feasible to package the Rust crate separately,
+the Rust crate *MAY* be packaged from different sources
+(i.e. an upstream tarball) _if and only if_ the crate
+is also published on https://crates.io[crates.io]
+under the same name and with matching versions.
+
+In this case, the subpackage(s) that contain the Rust crate sources
+*MUST* be named `rust-$crate-devel`
+and `rust-$crate+$feature-devel` for all crate features
+and ensure that the virtual `Provides` for the Rust crate are correct.
+The `rust-` prefix is not required for the name of the source package.
+
+==== Crates without Rust library interface
+
+Crates that do not provide a Rust library interface
+(for example, crates that only contain executable targets)
+*MAY* drop the `rust-` prefix for the name of the source package
+or use the "project name" if it is different from the crate name
+_if and only if_ the project will not provide (or need to provide)
+a Rust library interface in the future,
+since this would require renaming the source package to `rust-$crate`.
+In this case, the guidelines for
+link:#_rust_applications_non_crates_io_crates[single-crate Rust applications] apply,
+and the package is not required to use the sources
+that are published on https://crates.io[crates.io].
+
+When building a crate with vendored dependencies
+the `rust-` prefix of the source package name *MAY* be dropped as well --
+since packages cannot provide a Rust library interface in this case --
+_if and only if_ the project will not need to provide a Rust library interface.
 
 When generating a package for a Rust crate
 that also (or exclusively) contains an application,
@@ -377,14 +417,6 @@ but they *MUST NOT* be used for building the crate itself.
 It is recommended to file an issue with the upstream project
 about including these additional files in published crates.
 
-If a crate is also part of a larger project
-and it is not feasible to package the Rust crate separately,
-the Rust crate *MAY* be packaged as `rust-$crate` from different sources
-(i.e. an upstream tarball) _if and only if_ the crate is also published on https://crates.io[crates.io]
-under the same name and with matching versions.
-In this case, the subpackage(s) corresponding to Rust crates
-*MUST* have correct virtual `Provides` for the Rust crate.
-
 === Crate license
 
 Most tooling support for determining licenses
@@ -436,6 +468,10 @@ is almost entirely automated with several RPM macros:
   they can be moved after calling `%cargo_install`,
   or `%cargo_install` can be replaced
   with manual installation steps.
+  To prevent installation of executables by this macro,
+  the `+%cargo_install_bin+` macro can be defined to `0`.
+  To prevent installation of library sources by this macro,
+  the `+%cargo_install_lib+` macro can be defined to `0`.
 * `%cargo_test`:
   This macro *MUST* be called in the `%check` scriptlet.
   It runs `cargo test` with the appropriate command line arguments.
@@ -741,6 +777,12 @@ i.e. they cannot ship `-devel` subpackages
 that contain crate sources or have subpackages
 that have virtual provides for `crate(...) = %{version}`.
 
+To prevent the `+%cargo_install+` macro
+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.
+
 === Package naming
 
 Rust applications that are "crates"

From 99f70da13cfcf57e457639b318a04250aa2c36c9 Mon Sep 17 00:00:00 2001
From: Jason Tibbitts 
Date: Apr 04 2024 16:47:04 +0000
Subject: [PATCH 129/232] Add semantic linebreaks.


Adds semantic linebreaks to the GAP guidelines page.

---

diff --git a/guidelines/modules/ROOT/pages/GAP.adoc b/guidelines/modules/ROOT/pages/GAP.adoc
index 08deeb4..1793add 100644
--- a/guidelines/modules/ROOT/pages/GAP.adoc
+++ b/guidelines/modules/ROOT/pages/GAP.adoc
@@ -1,42 +1,82 @@
 = GAP Packaging Guidelines
 
-This document describes the conventions and customs surrounding the proper packaging of https://www.gap-system.org/[GAP] add-on packages in Fedora.
-Throughout this document, we use the word _add-on_ to substitute for GAP upstream's use of the word _package_, to avoid confusion with RPM packages.
+This document describes the conventions and customs
+surrounding the proper packaging of
+https://www.gap-system.org/[GAP]
+add-on packages in Fedora.
+Throughout this document,
+we use the word _add-on_
+to substitute for GAP upstream's use of the word _package_,
+to avoid confusion with RPM packages.
 
 == Naming
 
-The main GAP package and its attendant libraries and help system are in packages named gap, gap-libs, gap-core, gap-online-help, gap-rpm-macros, gap-devel, gap-vim, and libgap.
-To distinguish add-on packages from these core packages, add-ons MUST have names of the form gap-pkg-foo.
+The main GAP package and its attendant libraries and help system
+are in packages named
+gap, gap-libs, gap-core, gap-online-help,
+gap-rpm-macros, gap-devel, gap-vim, and libgap.
+To distinguish add-on packages from these core packages,
+add-ons MUST have names of the form gap-pkg-foo.
 For example, the FGA add-on is named gap-pkg-fga.
 
 == Add-on Location
 
-Architecture-independent (noarch) packages MUST be installed in `+%{gap_libdir}/pkg/%{pkgname}+`, and architecture-specific packages in `+%{gap_archdir}/pkg/%{pkgname}+`, where `+%{pkgname}+` expands to the GAP name for the add-on.
-
-GAP add-ons are written to be installed simply by unpacking them in an existing GAP directory tree.
-For most add-ons, the only build action necessary is building the documentation.
-However, since the add-on authors assumed this would happen within the GAP tree, add-ons freely use relative paths to access GAP files.
-For example, packages that use TTH to build documentation (see below) commonly invoke `+../../../convert.pl+`.
-The RPM spec file MUST account for this, either by altering the add-on to point to paths under `+%{gap_libdir}+`, or by creating symbolic links to create the appearance that the build is taking place inside the GAP tree.
-If the add-on is altered for the build, the spec file SHOULD arrange for the original (unaltered) files to be installed, so that paths are correct after installation.
-
-GAP add-ons are frequently distributed in tarballs with a top-level directory of the form `addon-version`.
+Architecture-independent (noarch) packages MUST be installed in
+`+%{gap_libdir}/pkg/%{pkgname}+`,
+and architecture-specific packages in
+`+%{gap_archdir}/pkg/%{pkgname}+`,
+where `+%{pkgname}+` expands to the GAP name for the add-on.
+
+GAP add-ons are written to be installed simply by unpacking them
+in an existing GAP directory tree.
+For most add-ons,
+the only build action necessary is building the documentation.
+However,
+since the add-on authors assumed this would happen within the GAP tree,
+add-ons freely use relative paths to access GAP files.
+For example,
+packages that use TTH to build documentation (see below) commonly invoke
+`+../../../convert.pl+`.
+The RPM spec file MUST account for this,
+either by altering the add-on to point to paths under
+`+%{gap_libdir}+`,
+or by creating symbolic links
+to create the appearance that the build is taking place inside the GAP tree.
+If the add-on is altered for the build,
+the spec file SHOULD arrange
+for the original (unaltered) files to be installed,
+so that paths are correct after installation.
+
+GAP add-ons are frequently distributed in tarballs
+with a top-level directory of the form `addon-version`.
 The add-on SHOULD be installed without the version number.
-Documentation for one package often crosslinks into documentation for other packages.
-If the directories involved contain version numbers, then the crosslinks can be broken by a package upgrade.
+Documentation for one package often crosslinks
+into documentation for other packages.
+If the directories involved contain version numbers,
+then the crosslinks can be broken by a package upgrade.
 Avoid this situation by omitting the version numbers.
-GAP itself can retrieve the version number from the add-on's `+PackageInfo.g+` file, so no information is lost.
+GAP itself can retrieve the version number from the add-on's
+`+PackageInfo.g+` file, so no information is lost.
 
 == BuildRequires
 
-All add-ons MUST include `+BuildRequires: gap-devel+`, as that package contains essential tools needed for compiling binary modules and building documentation, as well as a set of RPM macros for use in spec files.
-Each add-on also MUST contain a `+BuildRequires+` that is dependent on the documentation style used by the GAP add-on.
+All add-ons MUST include `+BuildRequires: gap-devel+`,
+as that package contains essential tools
+needed for compiling binary modules and building documentation,
+as well as a set of RPM macros for use in spec files.
+Each add-on also MUST contain a `+BuildRequires+`
+that is dependent on the documentation style used by the GAP add-on.
 
 === TTH
 
-Add-ons that use a `+buildman.pe+` or `+convert.pl+` script to build documentation also need `+BuildRequires: tth+` in order to build HTML documentation pages from TeX input.
-Some add-ons bundle these scripts, as well as a few auxiliary files.
-Add-ons containing any of the following files should be modified to link to the version of the file contained in the gap or gap-devel packages.
+Add-ons that use a `+buildman.pe+` or `+convert.pl+` script
+to build documentation also need `+BuildRequires: tth+`
+in order to build HTML documentation pages from TeX input.
+Some add-ons bundle these scripts,
+as well as a few auxiliary files.
+Add-ons containing any of the following files should be modified
+to link to the version of the file
+contained in the gap or gap-devel packages.
 
 * `+gapmacro.tex+` → `+%{gap_libdir}/doc/gapmacro.tex+`
 * `+gapmacrodoc.tex+` → `+%{gap_libdir}/doc/gapmacrodoc.tex+`
@@ -48,33 +88,54 @@ Add-ons containing any of the following files should be modified to link to the 
 
 === GAPDoc
 
-Add-ons that use GAPDoc to build documentation MUST include `+BuildRequires: GAPDoc-latex+` to pull in the necessary LaTeX packages.
-These packages do not need `+Requires: GAPDoc+`, since `+gap-core+` depends on GAPDoc.
+Add-ons that use GAPDoc to build documentation MUST include
+`+BuildRequires: GAPDoc-latex+`
+to pull in the necessary LaTeX packages.
+These packages do not need `+Requires: GAPDoc+`,
+since `+gap-core+` depends on GAPDoc.
 
 === Autodoc
 
-Add-ons that use Autodoc to build documentation MUST include `+BuildRequires: gap-pkg-autodoc+`.
-Such packages do not need to include `+BuildRequires: GAPDoc-latex+`, as the Autodoc package `+Requires: GAPDoc-latex+`.
+Add-ons that use Autodoc to build documentation MUST include
+`+BuildRequires: gap-pkg-autodoc+`.
+Such packages do not need to include
+`+BuildRequires: GAPDoc-latex+`,
+as the Autodoc package `+Requires: GAPDoc-latex+`.
 
 == Requires, Recommends, and Suggests
 
-All add-ons MUST include `+Requires: gap-core+`, either directly or transitively.
-In addition, dependencies on other GAP packages, as recorded in `+PackageInfo.g+`, MUST be specified, with the exception of `+GAPDoc+`, as noted above.
-GAP has a 2-level dependency system, specified with `+NeededOtherPackages+` and `+SuggestedOtherPackages+` tags in `+PackageInfo.g+`.
-How these dependencies map onto the 3-level RPM dependency system of Requires, Recommends, and Suggests is left to the discretion of the Fedora packager.
+All add-ons MUST include `+Requires: gap-core+`,
+either directly or transitively.
+In addition, dependencies on other GAP packages,
+as recorded in `+PackageInfo.g+`,
+MUST be specified,
+with the exception of `+GAPDoc+`, as noted above.
+GAP has a 2-level dependency system,
+specified with
+`+NeededOtherPackages+`
+and `+SuggestedOtherPackages+`
+tags in `+PackageInfo.g+`.
+How these dependencies map onto the 3-level RPM dependency system
+of Requires, Recommends, and Suggests
+is left to the discretion of the Fedora packager.
 
 == Unnecessary Files
 
-GAP add-ons are intended to be unpacked in place within a GAP directory tree.
-Ordinarily, the entire distribution directory is copied into `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+`.
-This includes the documentation directories, which are consumed by the tools contained in gap-online-help.
+GAP add-ons are intended to be unpacked in place
+within a GAP directory tree.
+Ordinarily,
+the entire distribution directory is copied into
+`+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+`.
+This includes the documentation directories,
+which are consumed by the tools contained in gap-online-help.
 However, some files are not needed in the final install directory.
 Files that should not appear there include:
 
 * Textual descriptions of the add-on, such as a README
 * License files (COPYING, COPYRIGHT, LICENSE, etc.)
 * Files for building documentation, often called `+make_doc+`
-* Files generated by LaTeX and associated tools, including files with these suffixes:
+* Files generated by LaTeX and associated tools,
+including files with these suffixes:
 ** .aux
 ** .bbl
 ** .blg
@@ -84,26 +145,55 @@ Files that should not appear there include:
 ** .log
 ** .toc
 
-Note that License files MUST still be included in the package with the %license tag, and other documentation such as README files can be included as %doc.
+Note that License files MUST still be included in the package
+with the %license tag,
+and other documentation such as README files
+can be included as %doc.
 
-The `+%gap_copy_docs+` macro is intended to make installation of documentation files easier.
-For most packages, ensure that the `doc` subdirectory exists in the buildroot, then invoke the macro without arguments in `+%install+`.
+The `+%gap_copy_docs+` macro is intended
+to make installation of documentation files easier.
+For most packages,
+ensure that the `doc` subdirectory exists in the buildroot,
+then invoke the macro without arguments in `+%install+`.
 For special cases, two optional arguments can be given:
 
-* `+-d directory+`: for cases where the documentation directory is not named `doc`, or there are multiple documentation directories
-* `+-n package+`: the installed add-on directory name is assumed to be available from a macro `+%pkgname+`.  If that is not the case, use this macro to give the main add-on directory name.
+* `+-d directory+`:
+for cases where the documentation directory is not named `doc`,
+or there are multiple documentation directories
+
+* `+-n package+`:
+the installed add-on directory name is assumed
+to be available from a macro `+%pkgname+`.
+ If that is not the case,
+use this macro to give the main add-on directory name.
 
 == Documentation
 
-Since GAP documentation MUST be installed under `+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+` for the builtin documentation browser to find it, such documentation SHOULD NOT be duplicated with `+%doc+`.
-However, the documentation SHOULD still be marked as such so that documentation-free installs work as expected.
-Most add-ons SHOULD include `+%docdir+` declarations in the `+%files+` section of the spec file; e.g., `+%docdir %{gap_libdir}/pkg/%{pkgname}/doc+` and `+%docdir %{gap_libdir}/pkg/%{pkgname}/htm+`.
+Since GAP documentation MUST be installed under
+`+%{gap_libdir}/pkg+` or `+%{gap_archdir}/pkg+`
+for the builtin documentation browser to find it,
+such documentation SHOULD NOT be duplicated with `+%doc+`.
+However, the documentation SHOULD still be marked as such
+so that documentation-free installs work as expected.
+Most add-ons SHOULD include `+%docdir+` declarations
+in the `+%files+` section of the spec file;
+e.g., `+%docdir %{gap_libdir}/pkg/%{pkgname}/doc+`
+and `+%docdir %{gap_libdir}/pkg/%{pkgname}/htm+`.
 
 == Other RPM macros
 
-Other RPM macros that may be useful for GAP add-on spec files include the following:
+Other RPM macros that may be useful
+ for GAP add-on spec files include the following:
+
+* `+%gap_version+`:
+the version of the main GAP package; e.g., 4.12.0.
+
+* `+%gap_archdir+`:
+ parent directory for arch-specific GAP add-ons,
+currently `+%{_libdir}/gap+`.
+
+* `+%gap_libdir+`:
+ the root directory of the GAP installation, currently `+%{_datadir}/gap+`.
 
-* `+%gap_version+`: the version of the main GAP package; e.g., 4.12.0.
-* `+%gap_archdir+`: parent directory for arch-specific GAP add-ons, currently `+%{_libdir}/gap+`.
-* `+%gap_libdir+`: the root directory of the GAP installation, currently `+%{_datadir}/gap+`.
-* `+%gap_arch+`: the GAP name for the build architecture; e.g., `x86_64-redhat-linux-gnu`.
+* `+%gap_arch+`:
+ the GAP name for the build architecture; e.g., `x86_64-redhat-linux-gnu`.

From 25831409787d5a1fb1473da6a64d1b0f4ea48636 Mon Sep 17 00:00:00 2001
From: Cristian Le 
Date: Apr 09 2024 12:22:57 +0000
Subject: [PATCH 130/232] Add note about `debugsourcefiles.list`


---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 988a295..2c396f2 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -1623,6 +1623,8 @@ When the contents of subpackages, including the `+-devel+` package,
 are actually architecture-independent, they may still be marked noarch.
 Since the base package for a header library typically has no `+%files+` list,
 this may result in an arched package that builds only noarch rpms.
+This may require adding `+%global debug_package %{nil}+` to the spec file in
+order to avoid empty `+debugsourcefiles.list+` issues.
 
 === Statically Linking Executables
 

From 1ac400f2bd301da90bb91884fa52f10d4ceeffdb Mon Sep 17 00:00:00 2001
From: Petr Bokoc 
Date: Apr 09 2024 18:40:17 +0000
Subject: [PATCH 131/232] Fix footnotes in ReviewGuidelines.adoc


---

diff --git a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
index 8935878..343b79b 100644
--- a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
+++ b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
@@ -14,49 +14,49 @@ Contributors and reviewers MUST follow the https://docs.fedoraproject.org/en-US/
 
 There are many many things to check for a review. This list is provided to assist new reviewers in identifying areas that they should look for, but is by no means complete. Reviewers should use their own good judgement when reviewing packages. The items listed fall into two categories: *SHOULD* and *MUST*.
 
-* *MUST*: rpmlint must be run on the source rpm and all binary rpms the build produces. The output should be posted in the review.footnote:[xref:index.adoc#_use_rpmlint[Packaging Guidelines: Use rpmlint\]] +
+* *MUST*: rpmlint must be run on the source rpm and all binary rpms the build produces. The output should be posted in the review. See xref:index.adoc#_use_rpmlint[Packaging Guidelines: Use rpmlint] +
 * *MUST*: The package must be named according to the xref:Naming.adoc[Package Naming Guidelines] . +
-* *MUST*: The spec file name must match the base package `+%{name}+`, in the format `+%{name}.spec+` unless your package has an exemption. footnote:[xref:index.adoc#_spec_file_naming[Packaging Guidelines: Spec File Naming\]] . +
+* *MUST*: The spec file name must match the base package `+%{name}+`, in the format `+%{name}.spec+` unless your package has an exemption. See xref:index.adoc#_spec_file_naming[Packaging Guidelines: Spec File Naming] . +
 * *MUST*: The package must meet the xref:index.adoc[Packaging Guidelines] . +
 * *MUST*: The package must be licensed with a Fedora approved license and meet the xref:LicensingGuidelines.adoc[Licensing Guidelines] . +
-* *MUST*: The License field in the package spec file must match the actual license. footnote:[xref:LicensingGuidelines.adoc#_valid_license_short_names[Licensing Guidelines: Valid License Short Names\]] +
-* *MUST*: If (and only if) the source package includes the text of the license(s) in its own file, then that file, containing the text of the license(s) for the package must be included in `+%license+`.footnote:[xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text\]] +
-* *MUST*: The spec file must be written in American English. footnote:[xref:index.adoc#_summary_and_description[Packaging Guidelines: Summary and description\]] +
-* *MUST*: The spec file for the package *MUST* be legible. footnote:[xref:index.adoc#_spec_legibility[Packaging Guidelines: Spec Legibility\]] +
+* *MUST*: The License field in the package spec file must match the actual license. See xref:LicensingGuidelines.adoc#_valid_license_short_names[Licensing Guidelines: Valid License Short Names] +
+* *MUST*: If (and only if) the source package includes the text of the license(s) in its own file, then that file, containing the text of the license(s) for the package must be included in `+%license+`. See xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text] +
+* *MUST*: The spec file must be written in American English. See xref:index.adoc#_summary_and_description[Packaging Guidelines: Summary and description] +
+* *MUST*: The spec file for the package *MUST* be legible. See xref:index.adoc#_spec_legibility[Packaging Guidelines: Spec Legibility] +
 * *MUST*: The sources used to build the package must match the upstream source, as provided in the spec URL. Reviewers should use sha256sum for this task as it is used by the `+sources+` file once imported into git. If no upstream URL can be specified for this package, please see the xref:SourceURL.adoc[Source URL Guidelines] for how to deal with this. +
-* *MUST*: The package *MUST* successfully compile and build into binary rpms on at least one primary architecture. footnote:[xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support\]] +
-* *MUST*: If the package does not successfully compile, build or work on an architecture, then those architectures should be listed in the spec in `+ExcludeArch+`. Each architecture listed in `+ExcludeArch+` *MUST* have a bug filed in bugzilla, describing the reason that the package does not compile/build/work on that architecture. The bug number *MUST* be placed in a comment, next to the corresponding `+ExcludeArch+` line. footnote:[xref:index.adoc#_architecture_build_failures[Packaging Guidelines: Architecture Build Failures\]] +
-* *MUST*: All build dependencies must be listed in `+BuildRequires+`. footnote:[xref:index.adoc#buildrequires[Packaging Guidelines: Build-Time Dependencies (BuildRequires)\]] +
-* *MUST*: The spec file MUST handle locales properly. This is done by using the `+%find_lang+` macro. Using `+%{_datadir}/locale/*+` is strictly forbidden.footnote:[xref:index.adoc#_handling_locale_files[Packaging Guidelines: Handling Locale Files\]] +
-* *MUST*: Packages must NOT bundle copies of system libraries.footnote:[xref:index.adoc#bundling[Packaging Guidelines: Bundling and Duplication of System Libraries\]] +
-* *MUST*: If the package is designed to be relocatable, the packager must state this fact in the request for review, along with the rationalization for relocation of that specific package. Without this, use of Prefix: /usr is considered a blocker. footnote:[xref:index.adoc#_relocatable_packages[Packaging Guidelines: Relocatable Packages\]] +
-* *MUST*: A package must own all directories that it creates. If it does not create a directory that it uses, then it should require a package which does create that directory. footnote:[xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File And Directory Ownership\]] +
-* *MUST*: A Fedora package must not list a file more than once in the spec file's %files listings. (Notable exception: license texts in specific situations)footnote:[xref:index.adoc#_duplicate_files[Packaging Guidelines: Duplicate Files\]] +
-* *MUST*: Permissions on files must be set properly. Executables should be set with executable permissions, for example. footnote:[xref:index.adoc#_file_permissions[Packaging Guidelines: File Permissions\]] +
-* *MUST*: Each package must consistently use macros. footnote:[xref:index.adoc#_macros[Packaging Guidelines: Macros\]] +
-* *MUST*: The package must contain code, or permissible content. footnote:[xref:what-can-be-packaged.adoc[What Can Be Packaged\]] +
-* *MUST*: Large documentation files must go in a -doc subpackage. (The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity). footnote:[xref:index.adoc#_documentation[Packaging Guidelines: Documentation\]] +
-* *MUST*: If a package includes something as %doc, it must not affect the runtime of the application. To summarize: If it is in %doc, the program must run properly if it is not present. footnote:[xref:index.adoc#_documentation[Packaging Guidelines: Documentation\]] +
-* *MUST*: Static libraries must be in a -static package. footnote:[xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries\]] +
-* *MUST*: Development files must be in a -devel package. footnote:[xref:index.adoc#_devel_packages[Packaging Guidelines: Devel Packages\]] +
-* *MUST*: In the vast majority of cases, devel packages must require the base package using a fully versioned dependency: `+Requires: %{name}%{?_isa} = %{version}-%{release}+` footnote:[xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package\]] +
-* *MUST*: Packages must NOT contain any .la libtool archives, these must be removed in the spec if they are built.footnote:[xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries\]] +
-* *MUST*: Packages containing GUI applications must include a %\{name}.desktop file, and that file must be properly installed with desktop-file-install in the %install section. If you feel that your packaged GUI application does not need a .desktop file, you must put a comment in the spec file with your explanation. footnote:[xref:index.adoc#_desktop_files[Packaging Guidelines: Desktop files\]] +
-* *MUST*: Packages must not own files or directories already owned by other packages. The rule of thumb here is that the first package to be installed should own the files or directories that other packages may rely upon. This means, for example, that no package in Fedora should ever share ownership with any of the files or directories owned by the `+filesystem+` or `+man+` package. If you feel that you have a good reason to own a file or directory that another package owns, then please present that at package review time. footnote:[xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File and Directory Ownership\]] +
-* *MUST*: All filenames in rpm packages must be valid UTF-8. footnote:[xref:index.adoc#_non_ascii_filenames[Packaging Guidelines: Non-ASCII Filenames\]] +
-* *MUST*: Packages being added to the distribution MUST NOT depend on any packages which have been marked as being deprecated. footnote:[xref:deprecating-packages.adoc[Deprecating Packages\]] +
+* *MUST*: The package *MUST* successfully compile and build into binary rpms on at least one primary architecture. See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support] +
+* *MUST*: If the package does not successfully compile, build or work on an architecture, then those architectures should be listed in the spec in `+ExcludeArch+`. Each architecture listed in `+ExcludeArch+` *MUST* have a bug filed in bugzilla, describing the reason that the package does not compile/build/work on that architecture. The bug number *MUST* be placed in a comment, next to the corresponding `+ExcludeArch+` line. See xref:index.adoc#_architecture_build_failures[Packaging Guidelines: Architecture Build Failures] +
+* *MUST*: All build dependencies must be listed in `+BuildRequires+`. See xref:index.adoc#buildrequires[Packaging Guidelines: Build-Time Dependencies (BuildRequires)] +
+* *MUST*: The spec file MUST handle locales properly. This is done by using the `+%find_lang+` macro. Using `+%{_datadir}/locale/*+` is strictly forbidden. See xref:index.adoc#_handling_locale_files[Packaging Guidelines: Handling Locale Files] +
+* *MUST*: Packages must NOT bundle copies of system libraries. See xref:index.adoc#bundling[Packaging Guidelines: Bundling and Duplication of System Libraries] +
+* *MUST*: If the package is designed to be relocatable, the packager must state this fact in the request for review, along with the rationalization for relocation of that specific package. Without this, use of Prefix: /usr is considered a blocker. See xref:index.adoc#_relocatable_packages[Packaging Guidelines: Relocatable Packages] +
+* *MUST*: A package must own all directories that it creates. If it does not create a directory that it uses, then it should require a package which does create that directory. See xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File And Directory Ownership] +
+* *MUST*: A Fedora package must not list a file more than once in the spec file's %files listings. (Notable exception: license texts in specific situations)See xref:index.adoc#_duplicate_files[Packaging Guidelines: Duplicate Files] +
+* *MUST*: Permissions on files must be set properly. Executables should be set with executable permissions, for example. See xref:index.adoc#_file_permissions[Packaging Guidelines: File Permissions] +
+* *MUST*: Each package must consistently use macros. See xref:index.adoc#_macros[Packaging Guidelines: Macros] +
+* *MUST*: The package must contain code, or permissible content. See xref:what-can-be-packaged.adoc[What Can Be Packaged] +
+* *MUST*: Large documentation files must go in a -doc subpackage. (The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity). See xref:index.adoc#_documentation[Packaging Guidelines: Documentation] +
+* *MUST*: If a package includes something as %doc, it must not affect the runtime of the application. To summarize: If it is in %doc, the program must run properly if it is not present. See xref:index.adoc#_documentation[Packaging Guidelines: Documentation] +
+* *MUST*: Static libraries must be in a -static package. See xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries] +
+* *MUST*: Development files must be in a -devel package. See xref:index.adoc#_devel_packages[Packaging Guidelines: Devel Packages] +
+* *MUST*: In the vast majority of cases, devel packages must require the base package using a fully versioned dependency: `+Requires: %{name}%{?_isa} = %{version}-%{release}+` See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package] +
+* *MUST*: Packages must NOT contain any .la libtool archives, these must be removed in the spec if they are built. See xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries] +
+* *MUST*: Packages containing GUI applications must include a %\{name}.desktop file, and that file must be properly installed with desktop-file-install in the %install section. If you feel that your packaged GUI application does not need a .desktop file, you must put a comment in the spec file with your explanation. See xref:index.adoc#_desktop_files[Packaging Guidelines: Desktop files] +
+* *MUST*: Packages must not own files or directories already owned by other packages. The rule of thumb here is that the first package to be installed should own the files or directories that other packages may rely upon. This means, for example, that no package in Fedora should ever share ownership with any of the files or directories owned by the `+filesystem+` or `+man+` package. If you feel that you have a good reason to own a file or directory that another package owns, then please present that at package review time. See xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File and Directory Ownership] +
+* *MUST*: All filenames in rpm packages must be valid UTF-8. See xref:index.adoc#_non_ascii_filenames[Packaging Guidelines: Non-ASCII Filenames] +
+* *MUST*: Packages being added to the distribution MUST NOT depend on any packages which have been marked as being deprecated. See xref:deprecating-packages.adoc[Deprecating Packages] +
 
 '''
 
-* *SHOULD*: If the source package does not include license text(s) as a separate file from upstream, the packager SHOULD query upstream to include it. footnote:[xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text\]] +
-* *SHOULD*: The reviewer should test that the package builds in mock. footnote:[https://fedoraproject.org/wiki/Using_Mock_to_test_package_builds[Using Mock to test package builds\]] +
-* *SHOULD*: The package should compile and build into binary rpms on all supported architectures. footnote:[xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support\]] +
+* *SHOULD*: If the source package does not include license text(s) as a separate file from upstream, the packager SHOULD query upstream to include it. See xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text] +
+* *SHOULD*: The reviewer should test that the package builds in mock. See https://fedoraproject.org/wiki/Using_Mock_to_test_package_builds[Using Mock to test package builds] +
+* *SHOULD*: The package should compile and build into binary rpms on all supported architectures. See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support] +
 * *SHOULD*: The reviewer should test that the package functions as described. A package should not segfault instead of running, for example. +
-* *SHOULD*: If scriptlets are used, those scriptlets must be sane. This is vague, and left up to the reviewers judgement to determine sanity. footnote:[xref:index.adoc#_scriptlets[Packaging Guidelines: Scriptlets\]] +
-* *SHOULD*: Usually, subpackages other than devel should require the base package using a fully versioned dependency. footnote:[xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package\]] +
-* *SHOULD*: The placement of pkgconfig(.pc) files depends on their usecase, and this is usually for development purposes, so should be placed in a -devel pkg. A reasonable exception is that the main pkg itself is a devel tool not installed in a user runtime, e.g. gcc or gdb. footnote:[xref:index.adoc#_pkgconfig_files_foo_pc[Packaging Guidelines: Pkgconfig Files\]] +
-* *SHOULD*: If the package has file dependencies outside of /etc, /bin, /sbin, /usr/bin, or /usr/sbin consider requiring the package which provides the file instead of the file itself. footnote:[xref:index.adoc#_file_and_directory_dependencies[Packaging Guidelines: File and Directory Dependencies\]] +
-* *SHOULD*: your package should contain man pages for binaries/scripts. If it doesn't, work with upstream to add them where they make sense.footnote:[xref:index.adoc#_manpages[Packaging Guidelines: Manpages\]] +
+* *SHOULD*: If scriptlets are used, those scriptlets must be sane. This is vague, and left up to the reviewers judgement to determine sanity. See xref:index.adoc#_scriptlets[Packaging Guidelines: Scriptlets] +
+* *SHOULD*: Usually, subpackages other than devel should require the base package using a fully versioned dependency. See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package] +
+* *SHOULD*: The placement of pkgconfig(.pc) files depends on their usecase, and this is usually for development purposes, so should be placed in a -devel pkg. A reasonable exception is that the main pkg itself is a devel tool not installed in a user runtime, e.g. gcc or gdb. See xref:index.adoc#_pkgconfig_files_foo_pc[Packaging Guidelines: Pkgconfig Files] +
+* *SHOULD*: If the package has file dependencies outside of /etc, /bin, /sbin, /usr/bin, or /usr/sbin consider requiring the package which provides the file instead of the file itself. See xref:index.adoc#_file_and_directory_dependencies[Packaging Guidelines: File and Directory Dependencies] +
+* *SHOULD*: your package should contain man pages for binaries/scripts. If it doesn't, work with upstream to add them where they make sense. See xref:index.adoc#_manpages[Packaging Guidelines: Manpages] +
 
 == A note on dependencies
 

From 33cef3917b9a85aff9e2da27ee5dad354c70217c Mon Sep 17 00:00:00 2001
From: Marian Koncek 
Date: Apr 15 2024 11:31:17 +0000
Subject: [PATCH 132/232] Drop requirement on java-headless for Java libraries


---

diff --git a/guidelines/modules/ROOT/pages/Java.adoc b/guidelines/modules/ROOT/pages/Java.adoc
index 4f7ffa4..0ff43ed 100644
--- a/guidelines/modules/ROOT/pages/Java.adoc
+++ b/guidelines/modules/ROOT/pages/Java.adoc
@@ -84,7 +84,7 @@ Java packages MUST BuildRequire their respective build system:
 * `+BuildRequires: ant+` for packages built with ant
 * `+BuildRequires: java-devel+` for packages built with javac
 
-Java binary packages or their dependencies MUST have `+Requires+` (generated by RPM or manual) on:
+Java applications MUST have `+Requires+` on:
 
 * `+java-headless+` or `+java-headless >= 1:minimal_required_version+`
 * `+javapackages-filesystem+`

From 2fe6a793b9839ea7240d74d4b3a90f35bc5b05e2 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Apr 18 2024 16:24:51 +0000
Subject: [PATCH 133/232] Drop historical rule for canonical file locations


rpm uses the location listed in %files as the canonical location of a file.
This is the location that must be used in Requires to refer to files.
(In other words, even though /bin is a symlink to /usr/bin, and /bin/foo
is really /usr/sbin/foo in the file system, if the package has /bin/foo
in %files, Requires:/usr/bin/foo is not going to work.)

When UsrMove was implemented 10+ years ago, the real locations in the file
system were changed from /[b]bin/* to /usr/[b]bin/*, but as a compatibility
measure, a packaging rule was introduced where the location reported in %files
was supposed to stay unchanged, so that other packages which used file
dependencies wouldn't need to be updated. The rule means that the packager needs
to figure out where the file was located "historically" and make %files conform
to that. This obviously made the transition easier, but I think it's time to
retire this rule. In fact, I think the rule has been mostly forgotten, because
it doesn't seem to be widely known or followed and many important packages
violate it (for example util-linux, systemd).

In fact the rule now it makes the life of packagers harder, because they cannot
just check where the file is located, they need to do the dance where they check
the canonical location of the file:
  rpm -ql $(rpm -qf /usr/sbin/ifconfig)|grep sbin/ifconfig

We can make packaging easier by removing the rule. It's possible that some
packages using file dependencies will need to be adjusted, but it's probably not
many and it should be simple to fix them.

Once the rule is removed from Packaging Guidelines, we can simplify packages
that still take the extra steps to followed the rule to just list files normally
in %files.

I noticed this rule when preparing for the unification of /usr/bin and /usr/sbin
(https://fedoraproject.org/wiki/Changes/Unify_bin_and_sbin). It's not
strictly necessary, but I think that if we simplify file locations, it's good
to get rid of this old complex rule too.

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 988a295..553a9ef 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -683,41 +683,22 @@ So an rpm which specified:
 
 would be able to satisfy a file dependency for `+/bin/sh+`
 but not for `+/usr/bin/sh+`.
-As a packager you may need to pay attention
-to where other packages expect to find your files.
-Things that history has placed into
-`+/bin+`, `+/sbin+`, `+/lib+`, or `+/lib64+`
-should be listed in the `+%files+` section as being in those directories.
-Things that history placed in
-`+/usr/bin+`, `+/usr/sbin+`, etc,
-should be listed in the `+%files+` section as being in
-`+%{_bindir}+`, `+%{_sbindir}+`, etc.
-If you feel that there is some historical confusion
-as to which directory a program is placed in,
-you can use a Virtual Provides to list the alternate path.
+Packages **must** use the real filesystem paths in the `+%files+` section.
+If other packages have dependencies on a different path
+that resolves to the same file,
+and it is not convenient to update them to the new path,
+packages **may** use a virtual `+Provides+` to list the alternate path.
+
 For instance:
 
 [source, rpm-spec]
 ----
-Provides: %{_sbindir}/ifconfig
+Provides: /sbin/ifconfig
 [...]
 %files
-/sbin/ifconfig
+%{_sbindir}/ifconfig
 ----
 
-If you are a packager who uses file dependencies
-to Require the proper dependencies
-then you may need to make sure that the file dependencies
-are pointing to the location that the packager of that file specified to rpm.
-Here's an example of doing this:
-
-....
-$ rpm -ql $(rpm -qf /usr/sbin/ifconfig)|grep sbin/ifconfig
-/sbin/ifconfig
-....
-
-So you'd want to use `+Requires: /sbin/ifconfig+` in your spec file.
-
 == Use `+rpmlint+`
 
 Run rpmlint on binary and source rpms to examine them for common errors,

From d20f4a142747ef39e622c561268b62d278ed1d3b Mon Sep 17 00:00:00 2001
From: James Antill 
Date: Apr 18 2024 16:34:52 +0000
Subject: [PATCH 134/232] Merge #1357 `Add note about `debugsourcefiles.list``


---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 553a9ef..1751cd4 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -1604,6 +1604,8 @@ When the contents of subpackages, including the `+-devel+` package,
 are actually architecture-independent, they may still be marked noarch.
 Since the base package for a header library typically has no `+%files+` list,
 this may result in an arched package that builds only noarch rpms.
+This may require adding `+%global debug_package %{nil}+` to the spec file in
+order to avoid empty `+debugsourcefiles.list+` issues.
 
 === Statically Linking Executables
 

From 85d4593d294649f6ab5131811c6b3abfe7126d4f Mon Sep 17 00:00:00 2001
From: Björn Persson 
Date: Apr 20 2024 12:44:49 +0000
Subject: [PATCH 135/232] URL and Source tags should use https:.


---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 1751cd4..adae898 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -729,6 +729,9 @@ the upstream sources for the package.
 In most cases this SHOULD be a complete URL to the upstream tarball.
 For special cases, please see the
 xref:SourceURL.adoc[SourceURL Guidelines].
+* URLs in the `+URL:+` and `+Source:+` tags
+SHOULD require authentication of the server whenever possible.
+This typically means writing `+https:+` instead of `+http:+` or `+ftp:+`.
 
 == Package Dependencies
 

From 45ff3fa83070a1f77b5457eec181b43d4569aabc Mon Sep 17 00:00:00 2001
From: Björn Persson 
Date: Apr 23 2024 14:54:45 +0000
Subject: [PATCH 136/232] URLs in Patch tags should also use https:.


---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index adae898..08e9dd3 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -729,7 +729,7 @@ the upstream sources for the package.
 In most cases this SHOULD be a complete URL to the upstream tarball.
 For special cases, please see the
 xref:SourceURL.adoc[SourceURL Guidelines].
-* URLs in the `+URL:+` and `+Source:+` tags
+* URLs in the `+URL:+`, `+Source:+` and `+Patch:+` tags
 SHOULD require authentication of the server whenever possible.
 This typically means writing `+https:+` instead of `+http:+` or `+ftp:+`.
 

From da54912cf7dc952aef414576920a16869669fe82 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Apr 25 2024 16:20:57 +0000
Subject: [PATCH 137/232] Lisp: drop cruft


Those things are not needed in spec files.

---

diff --git a/guidelines/modules/ROOT/pages/Lisp.adoc b/guidelines/modules/ROOT/pages/Lisp.adoc
index fde8f0f..42e4733 100644
--- a/guidelines/modules/ROOT/pages/Lisp.adoc
+++ b/guidelines/modules/ROOT/pages/Lisp.adoc
@@ -66,8 +66,6 @@ Requires(preun): common-lisp-controller
 %build
 
 %install
-%{__rm} -rf %{buildroot}
-
 # Replace @NAME@ below with the Common Lisp library name, which may be different from the
 # package name if it is not already prefixed with "cl-".
 
@@ -90,9 +88,6 @@ done
 %preun
 /usr/sbin/unregister-common-lisp-source @NAME@
 
-%clean
-%{__rm} -rf %{buildroot}
-
 %files
 %doc
 %{_datadir}/common-lisp/source/@NAME@

From f593707735281384a354db9cc3214ef62b7c24ed Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Apr 25 2024 16:20:57 +0000
Subject: [PATCH 138/232] Drop absolute paths where they are not useful


Absolute paths generally make things more complicated and less portable.

Historically, rpm packaging was big on specifying absolute paths
everywhere, for example with macros like %__mkdir and %__rm. This made
the spec files harder to read, but was not particularly useful. We run
with $PATH set and all those binaries are in $PATH. Maybe this rule
made some sense if people were installing rpms in some strange
half-broken environments, but this is not something that we support or
actually do in the last twenty years of Linux.

(On the security angle, if somebody managed to insert a rogue 'mkdir'
or 'rm' into one of the directories in $PATH, using an absolute path
in some rpm scriptlet is not going to help much. More complicated
programs may call other programs, and they do this using $PATH, so
even if it seems like we're providing aditional protection here, it's
not worth much. And those rogue binaries would be soon called by the
administrator anyway in some other context.)

Similarly, systemd required absolute paths in ExecStart= and similar
lines. This was "because selinux", but that seems bogus in hindsight,
because selinux still works fine after we switched to non-absolute
paths. This is particularly true for systemd units, which would often
be completely portable between distributions, except for the absolute
paths.

Thus, drop absolute paths in various examples.

This also makes things nicer for the upcoming merge of /usr/sbin and
/usr/bin. With an absolute path, we could either say "/usr/bin/foo"
which doesn't work on old systems, or we say "/usr/sbin/foo" which
works also on merged systems but is the compat path. So say "foo"
which is correct everywhere and easier to write.

---

diff --git a/guidelines/modules/ROOT/pages/Alternatives.adoc b/guidelines/modules/ROOT/pages/Alternatives.adoc
index a56bb9a..4fbbfb2 100644
--- a/guidelines/modules/ROOT/pages/Alternatives.adoc
+++ b/guidelines/modules/ROOT/pages/Alternatives.adoc
@@ -93,12 +93,12 @@ Requires(postun): %{_sbindir}/update-alternatives
 touch %{buildroot}%{_bindir}/antlr
 
 %post
-%{_sbindir}/update-alternatives --install %{_bindir}/antlr \
+update-alternatives --install %{_bindir}/antlr \
   %{name} %{_bindir}/antlr-java 10
 
 %postun
 if [ $1 -eq 0 ] ; then
-  %{_sbindir}/update-alternatives --remove %{name} %{_bindir}/antlr-java
+  update-alternatives --remove %{name} %{_bindir}/antlr-java
 fi
 ...
 %files
@@ -137,13 +137,13 @@ touch %{buildroot}%{_mandir}/man8/sendmail.8
 %postun
 if [ "$1" -ge "1" ]; then
     if [ "`+readlink %{_sysconfdir}/alternatives/mta+`" == "%{_sbindir}/sendmail.sendmail" ]; then
-        %{_sbindir}/alternatives --set mta %{_sbindir}/sendmail.sendmail
+        alternatives --set mta %{_sbindir}/sendmail.sendmail
     fi
 fi
 
 %post
 # Set up the alternatives files for MTAs.
-%{_sbindir}/update-alternatives --install %{_sbindir}/sendmail mta %{_sbindir}/sendmail.sendmail 90 \
+update-alternatives --install %{_sbindir}/sendmail mta %{_sbindir}/sendmail.sendmail 90 \
     --slave %{_bindir}/mailq mta-mailq %{_bindir}/mailq.sendmail \
     --slave %{_bindir}/newaliases mta-newaliases %{_bindir}/newaliases.sendmail \
     --slave %{_bindir}/rmail mta-rmail %{_bindir}/rmail.sendmail \
@@ -158,7 +158,7 @@ fi
 
 %preun
 if [ $1 = 0 ]; then
-    %{_sbindir}/update-alternatives --remove mta %{_sbindir}/sendmail.sendmail
+    update-alternatives --remove mta %{_sbindir}/sendmail.sendmail
 fi
 ...
 
diff --git a/guidelines/modules/ROOT/pages/Lisp.adoc b/guidelines/modules/ROOT/pages/Lisp.adoc
index 42e4733..8016db4 100644
--- a/guidelines/modules/ROOT/pages/Lisp.adoc
+++ b/guidelines/modules/ROOT/pages/Lisp.adoc
@@ -35,9 +35,9 @@ Libraries should depend on the common-lisp-controller package.
 Lisp source should be installed in %\{_datadir}/common-lisp/source/.
 The package should own that directory. The parent directories are owned by the common-lisp-controller package.
 A symlink to the asdf system definition file should be created from %\{_datadir}/common-lisp/systems/.asd to %\{_datadir}/common-lisp/source//.asd (this target directory is also owned by common-lisp-controller).
-The %post section should call "%\{_sbindir}/register-common-lisp-source ".
-The %preun section should call "%\{_sbindir}/unregister-common-lisp-source "
-These scripts are provided by common-lisp-controller.
+The %post section should call `+register-common-lisp-source+`.
+The %preun section should call `+unregister-common-lisp-source+`.
+These scripts are provided by `+common-lisp-controller+`.
 
 === Spec file template
 
@@ -83,10 +83,10 @@ for asd in *.asd; do
 done
 
 %post
-/usr/sbin/register-common-lisp-source @NAME@
+register-common-lisp-source @NAME@
 
 %preun
-/usr/sbin/unregister-common-lisp-source @NAME@
+unregister-common-lisp-source @NAME@
 
 %files
 %doc
@@ -116,12 +116,12 @@ Common Lisp implementations should depend on the common-lisp-controller package.
 
 Common Lisp implementations should install a script in %\{_libdir}/common-lisp/bin/.sh that supports a single command on the command line: "install-clc". This should load %\{_datadir}/common-lisp/source/common-lisp-controller/common-lisp-controller.lisp, call (common-lisp-controller:init-common-lisp-controller-v4 ) and then save the resulting image as default for the system.
 
-The %post section should call "%\{_sbindir}/register-common-lisp-implementation ".
-The %preun section should call "%\{_sbindir}/unregister-common-lisp-implementation "
+The %post section should call `+register-common-lisp-implementation+`.
+The %preun section should call `+unregister-common-lisp-implementation+`.
 
-These scripts, and the %\{_libdir}/common-lisp/bin directory are provided and owned by the common-lisp-controller package.
+These scripts, and the `+%{_libdir}/common-lisp/bin+` directory are provided and owned by the common-lisp-controller package.
 
-All implementations should be modified to load common-lisp-controller's %\{_sysconfdir}/lisp-config.lisp on startup.
+All implementations should be modified to load common-lisp-controller's `+%{_sysconfdir}/lisp-config.lisp+` on startup.
 
 == Further reading
 
diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc
index 9f9cfde..6c2a2ec 100644
--- a/guidelines/modules/ROOT/pages/Scriptlets.adoc
+++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc
@@ -211,7 +211,7 @@ They MUST NOT use the
 `+%ldconfig+`, `+%ldconfig_post+`,
 `+%ldconfig_postun+` or `+%ldconfig_scriptlets+` macros to do this,
 since these macros do not have any effect on Fedora.
-Instead simply call `+/sbin/ldconfig+` directly in both
+Instead simply call `+ldconfig+` directly in both
 `+%post+` and `+%postun+`
 as well as adding the necessary dependencies when necessary:
 
@@ -228,11 +228,11 @@ Requires(postun): /sbin/ldconfig
 [...]
 %post
 [...]
-/sbin/ldconfig
+ldconfig
 [...]
 %postun
 [...]
-/sbin/ldconfig
+ldconfig
 [...]
 ....
 
@@ -246,10 +246,10 @@ which cause ldconfig to be run automatically when necessary:
 
 ....
 %transfiletriggerin -P 2000000 -- DIRECTORIES
-/sbin/ldconfig
+ldconfig
 
 %transfiletriggerpostun -P 2000000 -- DIRECTORIES
-/sbin/ldconfig
+ldconfig
 ....
 
 Replace `+DIRECTORIES+` with the space-separated list of directories
diff --git a/guidelines/modules/ROOT/pages/Systemd.adoc b/guidelines/modules/ROOT/pages/Systemd.adoc
index ae7bfd9..fb2cf08 100644
--- a/guidelines/modules/ROOT/pages/Systemd.adoc
+++ b/guidelines/modules/ROOT/pages/Systemd.adoc
@@ -198,8 +198,8 @@ Example:
 [Service]
 Type=forking
 EnvironmentFile=-/etc/sysconfig/httpd
-ExecStart=/usr/sbin/httpd $OPTIONS
-ExecReload=/usr/sbin/httpd $OPTIONS -k restart
+ExecStart=httpd $OPTIONS
+ExecReload=httpd $OPTIONS -k restart
 ....
 
 You may then refer to variables set in the `+/etc/sysconfig/httpd+` file
@@ -283,7 +283,7 @@ Description=ABRT Automated Bug Reporting Tool
 [Service]
 Type=dbus
 BusName=com.redhat.abrt
-ExecStart=/usr/sbin/abrtd -d -s
+ExecStart=abrtd -d -s
 
 [Install]
 WantedBy=multi-user.target
@@ -383,7 +383,7 @@ The ConsoleKit bus activation file
 ....
 [D-BUS Service]
 Name=org.freedesktop.ConsoleKit
-Exec=/usr/sbin/console-kit-daemon --no-daemon
+Exec=console-kit-daemon --no-daemon
 User=root
 SystemdService=console-kit-daemon.service
 ....
@@ -398,7 +398,7 @@ Description=Console Manager
 [Service]
 Type=dbus
 BusName=org.freedesktop.ConsoleKit
-ExecStart=/usr/sbin/console-kit-daemon --no-daemon
+ExecStart=console-kit-daemon --no-daemon
 ....
 
 As you can see `+SystemdService=+` is used in the D-Bus activation file
@@ -442,7 +442,7 @@ SystemdService=dbus-org.freedesktop.Avahi.service
 
 # This service should not be bus activated if systemd isn't running,
 # so that activation won't conflict with the init script startup.
-Exec=/bin/false
+Exec=false
 ....
 
 Here is the Avahi systemd unit `+.service+` file
@@ -456,8 +456,8 @@ Requires=avahi-daemon.socket
 [Service]
 Type=dbus
 BusName=org.freedesktop.Avahi
-ExecStart=/usr/sbin/avahi-daemon -s
-ExecReload=/usr/sbin/avahi-daemon -r
+ExecStart=avahi-daemon -s
+ExecReload=avahi-daemon -r
 NotifyAccess=main
 
 [Install]

From f80e2dc64197d88821fdaae53f297f4f4315cd97 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Apr 25 2024 16:20:57 +0000
Subject: [PATCH 139/232] Describe the file system after sbin-bin merge


https://fedoraproject.org/wiki/Changes/Unify_bin_and_sbin

Since now %_sbindir is the same %_bindir, relegate it to the
compat section. Use "/usr/bin" or "%{_bindir}" everywhere.

---

diff --git a/guidelines/modules/ROOT/pages/RPMMacros.adoc b/guidelines/modules/ROOT/pages/RPMMacros.adoc
index 5c2549c..124cd28 100644
--- a/guidelines/modules/ROOT/pages/RPMMacros.adoc
+++ b/guidelines/modules/ROOT/pages/RPMMacros.adoc
@@ -55,7 +55,6 @@ The following table lists macros which are widely used in fedora `.spec` files.
 | +%{_bindir}+         | +%{_exec_prefix}+/bin       | default: `/usr/bin`
 | +%{_libdir}+         | +%{_exec_prefix}/%{_lib}+   | default: `+/usr/%{_lib}+`
 | +%{_libexecdir}+     | +%{_exec_prefix}+/libexec   | default: `/usr/libexec`
-| +%{_sbindir}+        | +%{_exec_prefix}+/sbin      | default: `/usr/sbin`
 | +%{_datadir}+        | +%{_datarootdir}+           | default: `/usr/share`
 | +%{_infodir}+        | +%{_datarootdir}+/info      | default: `/usr/share/info`
 | +%{_mandir}+         | +%{_datarootdir}+/man       | default: `/usr/share/man`
@@ -75,6 +74,7 @@ and there might be cases where they are still needed.
 | macro                | definition                   | comment
 | +%{_datarootdir}+    | +%{_prefix}/share+           | default: `/usr/share`
 | +%{_var}+            | /var                         |
+| +%{_sbindir}+        | same as +%{_bindir}+         | historically `/usr/sbin`, now `/usr/bin`, provided for compatibility
 | +%{_tmppath}+        | +%{_var}/tmp+                | default: `/var/tmp`
 | +%{_usr}+            | /usr                         |
 | +%{_usrsrc}+         | +%{_usr}/src+                | default: `/usr/src`
diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 08e9dd3..ef5650b 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -641,10 +641,10 @@ as long as package as a whole also supports Chromium.
 If Chrome in the future allows a more standard directory
 to be used for this purpose, this exception will be removed.
 
-=== Effect of the UsrMove Fedora Feature
+=== Merged file system layout
 
-Fedora has merged several directories in `+/+`
-with their counterparts in `+/usr/+`:
+Fedora has merged several directories that historically used to be
+separate.
 
 [cols=",,"]
 |===
@@ -655,8 +655,12 @@ with their counterparts in `+/usr/+`:
 |`+{_bindir}+`
 
 |`+/sbin+`
+|`+/usr/bin+`
+|`+%{_bindir}+`
+
 |`+/usr/sbin+`
-|`+%{_sbindir}+`
+|`+/usr/bin+`
+|`+%{_bindir}+`
 
 |`+/lib64+` or `+/lib+`
 |`+/usr/lib64+` or `+/usr/lib+`
@@ -667,8 +671,9 @@ with their counterparts in `+/usr/+`:
 |`+%{_prefix}/lib+`
 |===
 
-For example, end users will find that `+/bin/sh+`
-is the same file as `+/usr/bin/sh+`.
+For example, end users will find that
+`+/bin/sh+` is the same file as `+/usr/bin/sh+`,
+and `+/usr/sbin/sendmail+` is the the same as `+/usr/bin/sendmail+`.
 
 However,
 rpm file dependencies don't work according to what's on the filesystem,
@@ -696,7 +701,7 @@ For instance:
 Provides: /sbin/ifconfig
 [...]
 %files
-%{_sbindir}/ifconfig
+%{_bindir}/ifconfig
 ----
 
 == Use `+rpmlint+`
@@ -825,7 +830,6 @@ instead of packages.
 Packages MAY include such dependencies for paths inside one of the following directories:
 
 * `+/usr/bin+`
-* `+/usr/sbin+`
 * `+/etc+`
 
 They also MAY depend on paths listed in an explicit `Provides:`.

From 507e5ff6a6058587e7c13427b46cb9560815c6f4 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Apr 25 2024 16:20:57 +0000
Subject: [PATCH 140/232] Use /usr/bin/ in all paths for binaries


Those old paths would still work, but would be confusing to new
packagers, since we require that the real paths be used in %files [1].

In particular, ldconfig was "moved" in [2] and sendmail in [3].

[1] https://pagure.io/packaging-committee/pull-request/1355
[2] https://src.fedoraproject.org/rpms/glibc/pull-request/91
[3] https://src.fedoraproject.org/rpms/sendmail/pull-request/7

---

diff --git a/guidelines/modules/ROOT/pages/Alternatives.adoc b/guidelines/modules/ROOT/pages/Alternatives.adoc
index 4fbbfb2..f1ec3d5 100644
--- a/guidelines/modules/ROOT/pages/Alternatives.adoc
+++ b/guidelines/modules/ROOT/pages/Alternatives.adoc
@@ -37,7 +37,7 @@ If a non-root user would gain value by switching between the variants
 then alternatives *MUST NOT* be used.
 
 A good example of using alternatives are the various MTAs
-which all provide `+/usr/sbin/sendmail+` with similar command line arguments.
+which all provide `+/usr/bin/sendmail+` with similar command line arguments.
 
 Bad examples of using alternatives include:
 
@@ -61,10 +61,10 @@ are example packages using environment-modules for this purpose.
 If a package is using alternatives,
 the files which would otherwise conflict MUST be installed
 with an appropriate suffix
-(for example: `+%{_sbindir}/sendmail.postfix+`
-instead of `+%{_sbindir}/sendmail+`),
+(for example: `+%{_bindir}/sendmail.postfix+`
+instead of `+%{_bindir}/sendmail+`),
 the original locations MUST be touched
-(for example: `+touch %{_sbindir}/sendmail+`),
+(for example: `+touch %{_bindir}/sendmail+`),
 the links set up by alternatives MUST be listed as %ghost in the file list
 and proper Requires: MUST be added, like in the examples below.
 
@@ -85,8 +85,8 @@ Example from antlr.spec:
 
 [source, rpm-spec]
 ----
-Requires(post): %{_sbindir}/update-alternatives
-Requires(postun): %{_sbindir}/update-alternatives
+Requires(post): %{_bindir}/update-alternatives
+Requires(postun): %{_bindir}/update-alternatives
 ...
 %install
 ...
@@ -112,15 +112,15 @@ slightly edited:
 
 [source, rpm-spec]
 ----
-Requires(post): %{_sbindir}/update-alternatives
-Requires(postun): %{_sbindir}/update-alternatives
-Requires(preun): %{_sbindir}/update-alternatives
+Requires(post): %{_bindir}/update-alternatives
+Requires(postun): %{_bindir}/update-alternatives
+Requires(preun): %{_bindir}/update-alternatives
 ...
 %install
 ...
 # rename files for alternative usage
-mv %{buildroot}%{_sbindir}/sendmail %{buildroot}%{_sbindir}/sendmail.sendmail
-touch %{buildroot}%{_sbindir}/sendmail
+mv %{buildroot}%{_bindir}/sendmail %{buildroot}%{_bindir}/sendmail.sendmail
+touch %{buildroot}%{_bindir}/sendmail
 for i in mailq newaliases rmail; do
     mv %{buildroot}%{_bindir}/$i %{buildroot}%{_bindir}/$i.sendmail
     touch %{buildroot}%{_bindir}/$i
@@ -136,14 +136,14 @@ touch %{buildroot}%{_mandir}/man8/sendmail.8
 
 %postun
 if [ "$1" -ge "1" ]; then
-    if [ "`+readlink %{_sysconfdir}/alternatives/mta+`" == "%{_sbindir}/sendmail.sendmail" ]; then
-        alternatives --set mta %{_sbindir}/sendmail.sendmail
+    if [ "`+readlink %{_sysconfdir}/alternatives/mta+`" == "%{_bindir}/sendmail.sendmail" ]; then
+        %{_bindir}/alternatives --set mta %{_bindir}/sendmail.sendmail
     fi
 fi
 
 %post
 # Set up the alternatives files for MTAs.
-update-alternatives --install %{_sbindir}/sendmail mta %{_sbindir}/sendmail.sendmail 90 \
+update-alternatives --install %{_bindir}/sendmail mta %{_bindir}/sendmail.sendmail 90 \
     --slave %{_bindir}/mailq mta-mailq %{_bindir}/mailq.sendmail \
     --slave %{_bindir}/newaliases mta-newaliases %{_bindir}/newaliases.sendmail \
     --slave %{_bindir}/rmail mta-rmail %{_bindir}/rmail.sendmail \
@@ -158,13 +158,13 @@ update-alternatives --install %{_sbindir}/sendmail mta %{_sbindir}/sendmail.send
 
 %preun
 if [ $1 = 0 ]; then
-    update-alternatives --remove mta %{_sbindir}/sendmail.sendmail
+    update-alternatives --remove mta %{_bindir}/sendmail.sendmail
 fi
 ...
 
 %files
 ...
-%ghost %{_sbindir}/sendmail
+%ghost %{_bindir}/sendmail
 %ghost %{_bindir}/mailq
 %ghost %{_bindir}/newaliases
 %ghost %{_bindir}/rmail
@@ -175,7 +175,7 @@ fi
 %ghost %{_mandir}/man1/newaliases.1.gz
 %ghost %{_mandir}/man5/aliases.5.gz
 
-%{_sbindir}/sendmail.sendmail
+%{_bindir}/sendmail.sendmail
 %{_bindir}/mailq.sendmail
 %{_bindir}/newaliases.sendmail
 %{_bindir}/rmail.sendmail
diff --git a/guidelines/modules/ROOT/pages/CronFiles.adoc b/guidelines/modules/ROOT/pages/CronFiles.adoc
index 9f62791..f50beac 100644
--- a/guidelines/modules/ROOT/pages/CronFiles.adoc
+++ b/guidelines/modules/ROOT/pages/CronFiles.adoc
@@ -20,7 +20,7 @@ then a custom crontab file should be added to /etc/cron.d
 (with 0640 permissions).
 In this case, the cron job file (the script)
 must be placed in an appropriate system location
-(e.g. %\{_sbindir}, %\{_libexecdir}), and NOT in /etc/cron.d.
+(e.g. %\{_bindir}, %\{_libexecdir}), and NOT in /etc/cron.d.
 
 Both cron job files and crontab definition files
 installed in any of these directories
@@ -53,7 +53,7 @@ specified in /etc/cron.d/example
 # |  |  |  |  |
 # *  *  *  *  * user-name  command to be executed
 
-0 */2 * * * root /usr/sbin/example
+0 */2 * * * root /usr/bin/example
 ....
 
 == Cron job file names
diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc
index 6c2a2ec..961aec7 100644
--- a/guidelines/modules/ROOT/pages/Scriptlets.adoc
+++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc
@@ -28,7 +28,7 @@ of the rpm spec file.
 The scripts support a special flag, `+-p+`
 which allows the scriptlet to invoke a single program directly
 rather than having to spawn a shell to invoke the programs.
-(i.e., `+%post -p /sbin/ldconfig+`)
+(i.e., `+%post -p /usr/bin/ldconfig+`)
 
 When scriptlets are called,
 they will be supplied with an argument.
@@ -216,15 +216,15 @@ Instead simply call `+ldconfig+` directly in both
 as well as adding the necessary dependencies when necessary:
 
 ....
-%post -p /sbin/ldconfig
-%postun -p /sbin/ldconfig
+%post -p /usr/bin/ldconfig
+%postun -p /usr/bin/ldconfig
 ....
 
 or, as part of existing `+%post+` or `+%postun+` scriptlets:
 
 ....
-Requires(post): /sbin/ldconfig
-Requires(postun): /sbin/ldconfig
+Requires(post): /usr/bin/ldconfig
+Requires(postun): /usr/bin/ldconfig
 [...]
 %post
 [...]

From ba7de5fcc7c270ab70dca1d34d6ef8ce3a17d590 Mon Sep 17 00:00:00 2001
From: Maxwell G 
Date: Apr 25 2024 16:21:47 +0000
Subject: [PATCH 141/232] Golang: adjust Go architectures documentation


---

diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc
index de0be1e..769ca15 100644
--- a/guidelines/modules/ROOT/pages/Golang.adoc
+++ b/guidelines/modules/ROOT/pages/Golang.adoc
@@ -275,7 +275,14 @@ see upstream issue#13192), s390x, armv7hl and aarch64.
 Binaries SHOULD set ExclusiveArch so that we only attempt to build packages on
 those arches.
 This is now automatically added by the `+%gometa+` macro by leveraging the
-`+%{go_arches}+` macro.
+`+%{golang_arches}+` macro.
+Packagers can exclude `+%ix86+`
+(see https://fedoraproject.org/wiki/Changes/EncourageI686LeafRemoval[Changes/EncourageI686LeafRemoval])
+by passing `+-f+` to the `+%gometa+` macro.
+The `+-f+` flag tells `+%gometa+` to set `+ExclusiveArch: %{golang_arches_future}+`
+instead of `+ExclusiveArch: %{golang_arches}+`.
+`+%{golang_arches_future}+` includes the same architectures as
+`+{golang_arches}+` sans `+%ix86+`.
 
 == Dependencies
 

From d63dc74c1df2bc300f76bddbf90c73937cca689a Mon Sep 17 00:00:00 2001
From: Jerry James 
Date: May 13 2024 21:37:26 +0000
Subject: [PATCH 142/232] Remove all mention of XEmacs


- Modernize the spec file templates
- Describe all current emacs variants
- Recommend building with emacs-nw
- Guard against %{_emacs_version} being undefined
- Update location of emacs RPM macro file
- Change British English spelling to American English spelling
- Add semantic line breaks

---

diff --git a/guidelines/modules/ROOT/pages/Emacs.adoc b/guidelines/modules/ROOT/pages/Emacs.adoc
index 606ba04..7c760ef 100644
--- a/guidelines/modules/ROOT/pages/Emacs.adoc
+++ b/guidelines/modules/ROOT/pages/Emacs.adoc
@@ -1,35 +1,35 @@
-= Packaging of add-ons for GNU Emacs and XEmacs
+= Packaging of add-ons for GNU Emacs
 
 == Purpose
 
-The purpose of this document is to promote good practice in packaging add-ons for GNU Emacs and XEmacs, and to encourage the submission of more Emacs add-on packages to the package collection by providing easy to use spec file templates.
+The purpose of this document is to promote good practice in packaging add-ons for GNU Emacs, and to encourage the submission of more Emacs add-on packages to the package collection by providing easy to use spec file templates.
 
 == Important notes on these Guidelines
 
-The guidelines in the following sections make extensive use of the macros defined in /etc/rpm/macros.emacs and /etc/rpm/macros.xemacs which are installed with the emacs-common and xemacs-common packages.
+The guidelines in the following sections make extensive use of the macros defined in /usr/lib/rpm/macros.d/macros.emacs which is installed with the emacs-common package.
 
 There are two distinct cases where consideration of these guidelines is required:
 
-1.  This case refers to the situation where a package's principal purpose is to provide extra functionality for (X)Emacs, and the package serves no purpose without the presence of (X)Emacs. An example of this case is the VM mail reader, as packaged in emacs-vm. Below we refer to this as *Case I*.
-2.  This case refers to the situation where a package's principal functionality does not require (X)Emacs, but the package also includes some auxiliary Elisp files to provide support for the package in (X)Emacs. Below we refer to this as *Case II*.
+1.  This case refers to the situation where a package's principal purpose is to provide extra functionality for Emacs, and the package serves no purpose without the presence of Emacs. An example of this case is the VM mail reader, as packaged in emacs-vm. Below we refer to this as *Case I*.
+2.  This case refers to the situation where a package's principal functionality does not require Emacs, but the package also includes some auxiliary Elisp files to provide support for the package in Emacs. Below we refer to this as *Case II*.
 
 == Package naming and sub-package organization
 
 === Case I
 
-1.  Where an add-on package foo is for both GNU Emacs and XEmacs, the main package should be called emacs-common-foo. This main package should contain files common to both GNU Emacs and XEmacs such as documentation etc. Files specific to each of GNU Emacs and XEmacs should be placed in sub-packages called emacs-foo and xemacs-foo.
-2.  Where a package is primarily an add-on for one flavour of (X)Emacs, the main package should be called emacs-foo or xemacs-foo.
+Where a package is primarily an add-on for Emacs, the main package should be called emacs-foo.
 
 === Case II
 
-Where a package's principal functionality does not require (X)Emacs, but the package also includes some auxiliary Elisp files to provide support for the package in (X)Emacs, these should be included in the main package which will need to Require the emacs-filesystem and/or xemacs-filesystem packages. More detail below.
+Where a package's principal functionality does not require Emacs, but the package also includes some auxiliary Elisp files to provide support for the package in Emacs, these should be included in the main package which will need to Require the emacs-filesystem package.
+More detail below.
 
 == Package contents
 
 === Case I
 
-1.  Files specific to GNU Emacs should be placed in a sub-package called emacs-foo. This should contain the elisp source, compiled elisp and any other files needed to use the package or sub-package with GNU Emacs.
-2.  Files specific to XEmacs should be placed in a sub-package called xemacs-foo. This should contain the elisp source, compiled elisp and any other files needed to use the add-on package or sub-package with XEmacs.
+Files specific to GNU Emacs should be placed in the main package, emacs-foo.
+This should contain the elisp source, compiled elisp and any other files needed to use the package or sub-package with GNU Emacs.
 
 === Case II
 
@@ -37,46 +37,33 @@ The compiled elisp source and the elisp source files should be packaged as part 
 
 == File locations
 
-1.  File locations for GNU Emacs add-on (sub-)packages:
+File locations for GNU Emacs add-on (sub-)packages:
 * All elisp and related files for the package should be installed in the directory `+%{_emacs_sitelispdir}/foo+`.
 * If the package requires a startup file this should be called foo-init.el and be placed in `+%{_emacs_sitestartdir}+`.
-2.  File locations for XEmacs add-on (sub-)packages:
-* All elisp files for package should be installed in the directory `+%{_xemacs_sitelispdir}/foo+` (`+%{_xemacs_sitelispdir}+` translates to `+/usr/share/xemacs/site-packages/lisp/+`)
-* All other files for the add-on package should be installed under the relevant sub-directories in `+%{_xemacs_sitepkgdir}+`, e.g. `+%{_xemacs_sitepkgdir}/etc/foo+` (`+%{_xemacs_sitepkgdir}+` translates to `+/usr/share/xemacs/site-packages+`).
-* If the package requires a startup file this should be called `+foo-init.el+` and be placed in `+%{_xemacs_sitestartdir}+`.
 
 == Package Requires
 
 === Case I
 
-1.  Package Requires for GNU Emacs add-on (sub-)packages
+Package Requires for GNU Emacs add-on (sub-)packages:
 * Where relevant emacs-foo must have `+Requires: emacs-common-foo = %{version}-%{release}+`
-* emacs-foo must have `+Requires: emacs(bin) >= %{_emacs_version}+`
-2.  Package Requires for XEmacs add-on (sub-)packages
-* Where relevant xemacs-foo must have `+Requires: emacs-common-foo = %{version}-%{release}+`
-* xemacs-foo must have `+Requires: xemacs(bin) >= %{_xemacs_version}+`
+* emacs-foo must have `+Requires: emacs(bin)%{?_emacs_version: >= %{_emacs_version}}+`
 
 === Case II
 
-1.  If the package has auxillary files for use with GNU Emacs, the package must have `+Requires: emacs-filesystem >= %{_emacs_version}+`
-2.  If the package has auxillary files for use with XEmacs, the package must have `+Requires: xemacs-filesystem >= %{_xemacs_version}+`
+If the package has auxillary files for use with GNU Emacs, the package must have `+Requires: emacs-filesystem >= %{_emacs_version}+`
 
 == Package BuildRequires
 
-1.  Package BuildRequires for GNU Emacs add-on packages:
-* In general it should suffice to have `+BuildRequires: emacs+`
-2.  Package BuildRequires for XEmacs add-on packages:
-* In general it should suffice to have `+BuildRequires: xemacs+`
-* It may be necessary to also add `+BuildRequires: xemacs-devel+` in rare circumstances
+Package BuildRequires for GNU Emacs add-on packages:
+* In general it should suffice to have `+BuildRequires: emacs-nw+`
 
 == Manual byte compilation
 
-Usually package Elisp compilation is handled via a make file shipped with the package, but on some occasions it may be necessary to add commands to the %build section of the spec file to byte compile files. The following macros are provided to help with this:
+Usually package Elisp compilation is handled via a make file shipped with the package, but on some occasions it may be necessary to add commands to the %build section of the spec file to byte compile files.
+In that case, use `+%{_emacs_bytecompile} file.el+`
 
-* For GNU Emacs byte compilation, use `+%{_emacs_bytecompile} file.el+`
-* For XEmacs byte compilation, use `+%{_xemacs_bytecompile} file.el+`
-
-It is a requirement that all Elisp files are byte compiled and packaged, unless there is a good reason not to, in which case this should be documented with a comment in the spec file. If you are packaging for both GNU Emacs and XEmacs, be sure to byte compile for both.
+It is a requirement that all Elisp files are byte compiled and packaged, unless there is a good reason not to, in which case this should be documented with a comment in the spec file.
 
 == Use of BuildArch: noarch
 
@@ -84,99 +71,11 @@ If an add-on package requires only byte compilation of elisp then `+BuildArch: n
 
 == Example spec file templates
 
-=== Template for a package for both GNU Emacs and XEmacs (Case I)
-
-This spec-file template for the add-on package "foo" creates 3 packages:
-
-1.  emacs-common-foo is the main package. This should contain files which are common to both the emacs-foo and xemacs-foo subpackages below. Examples of what this file would contain are the package documentation, the COPYING file, the CHANGELOG file etc.
-2.  emacs-foo. This sub-package Requires emacs-common-foo and contains the files needed to run foo with Emacs only. This package contains both the compiled and source elisp files.
-3.  xemacs-foo. This sub-package Requires emacs-common-foo and contains the files needed to run foo with Emacs only. This package contains both the compiled and source elisp files.
-
-For convenience, there are two macros at the top of the file which you should customise to your package. You do not have to use the macros placed at the top of the file, but they help readability and make writing a spec file for a new package much quicker.
-
-....
-%global pkg foo
-%global pkgname Foo
-
-Name:           emacs-common-%{pkg}
-Version:
-Release:        1%{?dist}
-Summary:
-
-Group:
-License:
-URL:
-Source0:
-
-BuildArch:  noarch
-BuildRequires:  emacs
-BuildRequires:  xemacs
-Requires:
-
-%description
-%{pkgname} is an add-on package for GNU Emacs and XEmacs. It does wonderful things...
-
-This package contains the files common to both the GNU Emacs and XEmacs %{pkgname}
-packages.
-
-%package -n emacs-%{pkg}
-Summary:    Compiled elisp files to run %{pkgname} under GNU Emacs
-Group:
-Requires:   emacs(bin) >= %{_emacs_version}
-Requires:       emacs-common-%{pkg} = %{version}-%{release}
-
-%description -n emacs-%{pkg}
-This package contains the byte compiled elisp packages to run %{pkgname} with GNU
-Emacs.
-
-
-%package -n xemacs-%{pkg}
-Summary:    Compiled elisp files to run %{pkgname} under XEmacs
-Group:
-Requires:   xemacs(bin) >= %{_xemacs_version}
-Requires:       emacs-common-%{pkg} = %{version}-%{release}
-
-%description -n xemacs-%{pkg}
-This package contains the byte compiled elisp packages to use %{pkgname} with
-XEmacs.
-
-
-%prep
-%setup -q -n %{pkg}-%{version}
-
-%build
-
-
-%install
-
-
-%post
-
-
-%preun
-
-
-%files
-%doc
-
-
-%files -n emacs-%{pkg}
-%{_emacs_sitelispdir}/%{pkg}
-%{_emacs_sitestartdir/*.el
+=== Template for an add-on package for GNU Emacs (Case I)
 
-
-%files -n xemacs-%{pkg}
-%{_xemacs_sitelispdir}/%{pkg}
-%{_xemacs_sitestartdir}/*.el
-
-
-
-%changelog
-....
-
-=== Template for a add-on package for GNU Emacs only (Case I)
-
-This is a template for a package for GNU Emacs only. The main package is called emacs-foo and contains all files needed to run package foo with GNU Emacs. This includes both compiled and source elisp files.
+This is a template for a package for GNU Emacs.
+The main package is called emacs-foo and contains all files needed to run package foo with GNU Emacs.
+This includes both compiled and source elisp files.
 
 ....
 %global pkg foo
@@ -184,7 +83,7 @@ This is a template for a package for GNU Emacs only. The main package is called 
 
 Name:           emacs-%{pkg}
 Version:
-Release:        1%{?dist}
+Release:        %autorelease
 Summary:
 
 Group:
@@ -193,15 +92,15 @@ URL:
 Source0:
 
 BuildArch:      noarch
-BuildRequires:  emacs
-Requires:       emacs(bin) >= %{_emacs_version}
+BuildRequires:  emacs-nw
+Requires:       emacs(bin)%{?_emacs_version: >= %{_emacs_version}}
 
 %description
 %{pkgname} is an add-on package for GNU Emacs. It does wonderful things...
 
 
 %prep
-%setup -q -n %{pkg}-%{version}
+%autosetup -n %{pkg}-%{version}
 
 %build
 
@@ -222,16 +121,17 @@ Requires:       emacs(bin) >= %{_emacs_version}
 
 
 %changelog
+%autochangelog
 ....
 
-=== Template for a package which contains auxiliary GNU Emacs and XEmacs files (Case II)
+=== Template for a package which contains auxiliary GNU Emacs files (Case II)
 
-This is a skeleton of a package which also includes support files for both GNU Emacs and XEmacs
+This is a skeleton of a package which also includes support files for GNU Emacs
 
 ....
 Name:           foo
 Version:
-Release:        1%{?dist}
+Release:        %autorelease
 Summary:
 
 Group:
@@ -239,19 +139,15 @@ License:
 URL:
 Source0:
 
-BuildRequires:  emacs
-Requires:       emacs-filesystem >= %{_emacs_version}
-
-BuildRequires:  xemacs
-Requires:       xemacs-filesystem >= %{_xemacs_version}
-
+BuildRequires:  emacs-nw
+Requires:       emacs-filesystem%{?_emacs_version: >= %{_emacs_version}}
 
 %description
-Foo is a package which contains auxiliary Emacs and XEmacs support files
+Foo is a package which contains auxiliary Emacs support files.
 
 
 %prep
-%setup -q 
+%autosetup
 
 %build
 
@@ -270,91 +166,79 @@ Foo is a package which contains auxiliary Emacs and XEmacs support files
 %{_emacs_sitelispdir}/foo
 %{_emacs_sitestartdir}/*.el
 
-%{_xemacs_sitelispdir}/foo
-%{_xemacs_sitestartdir}/*.el
-
 %changelog
+%autochangelog
 ....
 
 == Principles behind the guidelines
 
-The existence of the GNU Emacs and XEmacs variants makes packaging Emacs add-on packaging slightly complex. GNU Emacs and XEmacs have different philosophies regarding add-on packages.
-
-XEmacs has its own packaging system and maintains and distributes its own library of third party add-on modules. These are distributed in Fedora in the xemacs-packages-base and xemacs-packages-extra packages. GNU Emacs doesn't have any equivalent system, and third party add-ons are left for the user or distribution to install.
-
-The packaging naming guidelines state that:
-
-_Packages of emacs add-on components (code that adds additional functionality to emacs compatible editors) have their own naming scheme. It is often the case that a component will add functionality to several different compatible editors, such as GNU Emacs and XEmacs (and possibly development versions of these editors). The package name should take into account the upstream name of the emacs component._
-
-_Where a component adds functionality to more than one emacs compatible editor, the package name should be of the form emacs-common-$NAME. In this case, the main package should contain only files common to all emacs compatible editors, and the code specific to each should be placed in a subpackage reflecting the specific editor $EDITOR-$NAME e.g., xemacs-$NAME, emacs-$NAME (the latter being the package specific to GNU Emacs). An example of this scheme can be found in the package emacs-common-muse._
-
-_Where a component is designed to add functionality to only a single emacs compatible editor, the main package name should reflect this by being called $EDITOR-$NAME. An example of this situation can be found in the package emacs-auctex, which is built only for GNU Emacs._
-
-Wherever possible, we encourage making an add-on package available for both GNU Emacs and XEmacs. One common case where that is not desirable is when an add-on package is already available for XEmacs in either xemacs-packages-base or xemacs-packages-extra. For example VM (a mail reader for Emacs) is provided for XEmacs in the xemacs-packages-extra package, but is not included in the emacs or emacs-common packages. Therefore it is sensible to create a package called emacs-vm which is the VM package for GNU Emacs only. Another such example is AUCTeX.
-
 === Location of installed files
 
-==== GNU Emacs
-
-For GNU Emacs, files for add-on package foo should be placed in %\{_emacs_sitelispdir}/foo which evaluates to /usr/share/emacs/site-lisp/foo.
+Files for add-on package foo should be placed in %\{_emacs_sitelispdir}/foo which evaluates to /usr/share/emacs/site-lisp/foo.
 
 Usually an add-on package will require a startup file, and this should be called foo-init.el and be placed in %\{_emacs_sitestartdir} which evaluates to /usr/share/emacs/site-lisp/site-start.d/.
 
-==== XEmacs
-
-XEmacs expects add-on packages to be installed under %\{_xemacs_sitepkgdir} which evaluates to /usr/share/xemacs/site-packages.
-
-Lisp files for add-on package foo should be placed in %\{_xemacs_sitelispdir}/foo which evaluates to %\{_xemacs_sitepkgdir}/lisp/foo.
-
-Other files for the add-on which are not elisp files should be placed in package specific sub-directories under %\{_xemacs_sitepkgdir} e.g., %\{_xemacs_sitepkgdir}/etc/foo.
-
-Usually an add-on package will require a startup file, and this should be called foo-init.el and be placed in %\{_xemacs_sitestartdir} which evaluates to /usr/share/xemacs/site-packages/lisp/site-start.d/.
-
 === Packaging of source elisp files
 
-Typically, an Emacs add-on package will be compiled from source elisp files. The resulting compiled elisp files will then be included in the relevant emacs-foo and xemacs-foo packages. It is important to also include the source elisp files for several reasons. For example when debugging a problem with an (X)Emacs package, the Elisp debugger can look up the relevant code or symbol definition in the source lisp file if present. Also, it's sometimes helpful to jump to a variable description string from the Emacs help system.
+Typically, an Emacs add-on package will be compiled from source elisp files.
+The resulting compiled elisp files will then be included in the relevant emacs-foo package.
+It is important to also include the source elisp files for several reasons.
+For example when debugging a problem with an Emacs package, the Elisp debugger can look up the relevant code or symbol definition in the source lisp file if present.
+Also, it's sometimes helpful to jump to a variable description string from the Emacs help system.
 
-=== BuildArch for (X)Emacs add-on packages
+=== BuildArch for Emacs add-on packages
 
 You should set BuildArch: noarch for add-on packages which only compile elisp files during building.
 
 If the package building process also compiles programs in other languages, you may need to not set BuildArch.
 
-=== Requires for GNU Emacs and XEmacs
+=== Requires for GNU Emacs
 
-Add-on packages should have appropriate Requires entries for the flavour of (X)Emacs they are targeted at. Both GNU Emacs and XEmacs are available in two different packages - some details of these packages follow.
+Add-on packages should have appropriate Requires entries for the flavor of Emacs they are targeted at.
+GNU Emacs is available in multiple packages - some details of these packages follow.
 
-\1. GNU Emacs is packaged as two variants. The emacs package is built with Xorg support to allow the user to run Emacs in a windowed environment. The emacs-nox package is built without Xorg support and hence allows Emacs to be run only in a console. Note:
+1. The emacs package is built with pure GTK support to allow the user to run Emacs in a windowed environment.
+2. The emacs-gtk+x11 package is built with X11 support via the GTK toolkit to allow the user to run Emacs in a windowed environment.
+3. The emacs-lucid package is built with X11 support via the Lucid toolkit to allow the user to run Emacs in a windowed environment.
+4. The emacs-nw package is built without GUI support.  It is suitable for running in a terminal.
 
-* Both the emacs and emacs-nox packages have Requires: emacs-common.
-* Both emacs and emacs-nox have a virtual Provides: emacs(bin)
+Note:
 
-\2. XEmacs is packaged as two variants. The xemacs package is built with Xorg support to allow the user to run Emacs in a windowed environment. The xemacs-nox package is built without Xorg support and hence allows Emacs to be run only in a console. Note:
+* The emacs, emacs-gtk+x11, emacs-lucid, and emacs-nw packages all have Requires: emacs-common.
+* The emacs, emacs-gtk+x11, emacs-lucid, and emacs-nw packages all have a virtual Provides: emacs(bin).
 
-* Both the xemacs and xemacs-nox packages have Requires: xemacs-common.
-* Both xemacs and xemacs-nox have a virtual Provides: xemacs(bin)
+Assuming your add-on package will work in both a windowed and a console Emacs session, it is wrong to have Requires: emacs as that would pull in a dependency on GTK even if the console variant of Emacs is installed.
+Rather you should use Requires: emacs(bin) for GNU Emacs add-on packages.
 
-Assuming your add-on package will work in both a windowed and a console (X)Emacs session, it is wrong to have Requires: emacs or Requires: xemacs as that would pull in a dependency on Xorg even if the console variants of (X)Emacs was installed. Rather you should use Requires: xemacs(bin) for XEmacs add-on packages, and Requires: emacs(bin) for GNU Emacs add-on packages.
-
-If the package ONLY works with Xorg support built into (X)Emacs, then the packages should have Requires: emacs or Requires: xemacs. This is very uncommon.
+If the package ONLY works with GTK support built into Emacs, then the package should have Requires: emacs.
+This is very uncommon.
 
 ==== Why we need versioned Requires
 
-Many elisp packages aim for backwards source level compatibility by checking whether some features exist in the (X)Emacs in use when the package is being run or byte-compiled. If yes, they use what's available. If no, they provide their own versions of missing functions, macros etc. This propagates into *.elc during byte compilation, and quite a few functions do get added between upstream (X)Emacs releases.
-
-So let's say I byte-compile a package into *.elc with XEmacs 21.5.28. Elisp package quux checks if the foo-bar function is available in the XEmacs being used to byte-compile it. Yes, it is, so the internal backwards compat version of foo-bar included in quux does not end up in the *.elc. Now, let's assume foo-bar was added in XEmacs 21.5.28 and didn't exist in 21.5.27 and we're trying to run the *.elc with 21.5.27 -> boom, foo-bar is not available. Note: this wouldn't happen if only *.el were shipped - *.elc are the potential and likely problem. Requiring >= version of the (X)Emacs used to byte-compile the *.elc is not the only solution (nor enough for all corner cases), but is the best one we currently have available.
+Many elisp packages aim for backwards source level compatibility by checking whether some features exist in the Emacs in use when the package is being run or byte-compiled.
+If yes, they use what's available.
+If no, they provide their own versions of missing functions, macros etc.
+This propagates into *.elc during byte compilation, and quite a few functions do get added between upstream Emacs releases.
 
-The main package and subpackages will need to have appropriately version Requires to ensure that a recent enough version of (X)Emacs is installed. (X)Emacs byte compiled lisp is usually forward compatible with later (X)Emacs versions, but is frequently not compatible with earlier versions of (X)Emacs.
+So let's say I byte-compile a package into *.elc with Emacs 29.3.
+Elisp package quux checks if the foo-bar function is available in the Emacs being used to byte-compile it.
+Yes, it is, so the internal backwards compat version of foo-bar included in quux does not end up in the *.elc.
+Now, let's assume foo-bar was added in Emacs 29.3 and didn't exist in 29.2 and we're trying to run the *.elc with 29.2 -> boom, foo-bar is not available.
+Note: this wouldn't happen if only *.el were shipped - *.elc are the potential and likely problem.
+Requiring >= version of the Emacs used to byte-compile the *.elc is not the only solution (nor enough for all corner cases), but is the best one we currently have available.
 
-==== Determining the Required (X)Emacs version at package build time
+The main package and subpackages will need to have appropriately versioned Requires to ensure that a recent enough version of Emacs is installed.
+Emacs byte compiled lisp is usually forward compatible with later Emacs versions, but is frequently not compatible with earlier versions of Emacs.
 
-It is recommended to derive greater-than-or-equal-to valued versioned dependencies from the version of (X)Emacs used to byte-compile the package at package build time. The emacs-common and xemacs-common packages both place files in /etc/rpm which define macros containing the version of (X)Emacs installed. The relevant macros are:
+==== Determining the Required Emacs version at package build time
 
-....
-%{_emacs_version}
-%{_xemacs_version}
-....
+It is recommended to derive greater-than-or-equal-to valued versioned dependencies from the version of Emacs used to byte-compile the package at package build time.
+The emacs-common package includes /usr/lib/rpm/macros.d/macros.emacs which defines a `+%\{_emacs_version}+` macro containing the version of Emacs installed.
 
 === Other packages containing Emacsen add-ons (Case II)
 
-It is often the case that a software package, while not being primarily an Emacs add-on package, will contain components for (X)Emacs. For example, the Gnuplot program contains some elisp files for editing Gnuplot input files in GNU Emacs and running Gnuplot from GNU Emacs. In this case, we want to enable the (X)Emacs support IF (X)Emacs is installed, but we don't want to mandate the installation of (X)Emacs on installation of this package since (X)Emacs is not required for providing the core functionality of the package. To enable this, the emacs-filesystem and xemacs-filesystem sub-packages were created which own the /usr/share/emacs/site-lisp and /usr/share/xemacs/site-packages directories respectively. A package can then Require these (x)emacsfilesystem packages in order to install their Elisp files without pulling in (X)Emacs and their dependency chain.
+It is often the case that a software package, while not being primarily an Emacs add-on package, will contain components for Emacs.
+For example, the Gnuplot program contains some elisp files for editing Gnuplot input files in GNU Emacs and running Gnuplot from GNU Emacs.
+In this case, we want to enable the Emacs support IF Emacs is installed, but we don't want to mandate the installation of Emacs on installation of this package since Emacs is not required for providing the core functionality of the package.
+To enable this, the emacs-filesystem sub-package was created which owns the /usr/share/emacs/site-lisp directory.
+A package can then Require the emacs-filesystem package in order to install its Elisp files without pulling in Emacs and its dependency chain.
diff --git a/guidelines/modules/ROOT/pages/Naming.adoc b/guidelines/modules/ROOT/pages/Naming.adoc
index 09cbfb7..2bd567e 100644
--- a/guidelines/modules/ROOT/pages/Naming.adoc
+++ b/guidelines/modules/ROOT/pages/Naming.adoc
@@ -265,40 +265,16 @@ SDL_ttf (TrueType font rendering support for SDL, relies on SDL)
 === emacs components
 
 Packages of emacs add-on components
-(code that adds additional functionality to emacs compatible editors)
-have their own naming scheme.
-It is often the case that a component will add functionality
-to several different compatible editors,
-such as GNU Emacs and XEmacs
-(and possibly development versions of these editors).
-The package name SHOULD take into account the upstream name
-of the emacs component.
-
-Where a component adds functionality to more than one emacs compatible editor,
-the package name SHOULD be of the form `+emacs-common-$NAME+`.
-In this case,
-the main package SHOULD contain only files common
-to all emacs compatible editors,
-and the code specific to each SHOULD be placed
-in a subpackage reflecting the specific editor `+$EDITOR-$NAME+`
-e.g., `+xemacs-$NAME+`, `+emacs-$NAME+`
-(the latter being the package specific to GNU Emacs).
-An example of this scheme can be found in the package
-`+emacs-common-muse+`.
-
-Where a component is designed to add functionality
-to only a single emacs compatible editor,
-the main package name SHOULD reflect this
-by being called `+$EDITOR-$NAME+`.
-An example of this situation can be found in the package
-`+emacs-auctex+`, which is built only for GNU Emacs.
+(code that adds additional functionality to emacs)
+SHOULD have a name that takes into account the upstream name
+of the emacs component by being called `+emacs-$NAME+`.
 
 *Examples:*
 
 ....
-emacs-common-muse (muse component for all emacs compatible editors)
-xemacs-muse (muse component subpackage that provides XEmacs specific files)
-emacs-autex (autex component only for GNU Emacs)
+emacs-auctex (auctex component for GNU Emacs)
+emacs-deferred (deferred component for GNU Emacs)
+emacs-flycheck (flycheck component for GNU Emacs)
 ....
 
 === Erlang modules

From 9ccd192964fb7df3335a3d55f9d0957c59892924 Mon Sep 17 00:00:00 2001
From: James Antill 
Date: May 30 2024 16:22:38 +0000
Subject: [PATCH 143/232] Merge #1360 `Drop requirement on java-headless for Java libraries`


---

diff --git a/guidelines/modules/ROOT/pages/Java.adoc b/guidelines/modules/ROOT/pages/Java.adoc
index 4f7ffa4..0ff43ed 100644
--- a/guidelines/modules/ROOT/pages/Java.adoc
+++ b/guidelines/modules/ROOT/pages/Java.adoc
@@ -84,7 +84,7 @@ Java packages MUST BuildRequire their respective build system:
 * `+BuildRequires: ant+` for packages built with ant
 * `+BuildRequires: java-devel+` for packages built with javac
 
-Java binary packages or their dependencies MUST have `+Requires+` (generated by RPM or manual) on:
+Java applications MUST have `+Requires+` on:
 
 * `+java-headless+` or `+java-headless >= 1:minimal_required_version+`
 * `+javapackages-filesystem+`

From c9f1920a29a5c981a601fb1db10e2e3b997de41f Mon Sep 17 00:00:00 2001
From: Marian Koncek 
Date: Jun 12 2024 14:33:02 +0000
Subject: [PATCH 144/232] Clear wording on JRE Requires


---

diff --git a/guidelines/modules/ROOT/pages/Java.adoc b/guidelines/modules/ROOT/pages/Java.adoc
index 0ff43ed..d6d8604 100644
--- a/guidelines/modules/ROOT/pages/Java.adoc
+++ b/guidelines/modules/ROOT/pages/Java.adoc
@@ -84,7 +84,7 @@ Java packages MUST BuildRequire their respective build system:
 * `+BuildRequires: ant+` for packages built with ant
 * `+BuildRequires: java-devel+` for packages built with javac
 
-Java applications MUST have `+Requires+` on:
+Java applications or their dependencies MUST have `+Requires+` on:
 
 * `+java-headless+` or `+java-headless >= 1:minimal_required_version+`
 * `+javapackages-filesystem+`

From 889df8add798409318298969216700a423453bff Mon Sep 17 00:00:00 2001
From: Stephen Gallagher 
Date: Jun 13 2024 15:10:15 +0000
Subject: [PATCH 145/232] Node.js: permit pre-minified JS


Fixes: https://pagure.io/packaging-committee/issue/1343
Related: https://pagure.io/fesco/issue/3177

Signed-off-by: Stephen Gallagher 

---

diff --git a/guidelines/modules/ROOT/pages/Node.js.adoc b/guidelines/modules/ROOT/pages/Node.js.adoc
index 7144678..86af23f 100644
--- a/guidelines/modules/ROOT/pages/Node.js.adoc
+++ b/guidelines/modules/ROOT/pages/Node.js.adoc
@@ -2,6 +2,8 @@
 
 The upstream Node.js stance on https://nodejs.org/en/blog/npm/npm-1-0-global-vs-local-installation/[global library packages] is that they are ".. best avoided if not needed."  In Fedora, we take the same stance with our nodejs packages.  You can provide a package that uses nodejs, but you should bundle all the nodejs libraries that are needed.
 
+Packages containing JavaScript should make the best effort to regenerate any precompiled/pre-minimized JS wherever possible, as this leads to more maintainable packages. Where this would result in a significant hardship, the bundled pregenerated JS may be shipped with a specfile comment explaining the decision. This does not eliminate the requirement to validate licenses of bundled code. See <> below.
+
 == What to Package
 
 * The interpreter, development headers/libraries, and the assorted tools to manage project-level installations.

From b4c34ea7800c771463be449cd0ae68a51fe9e62d Mon Sep 17 00:00:00 2001
From: James Antill 
Date: Jun 13 2024 15:49:38 +0000
Subject: [PATCH 146/232] Merge #1370 `Node.js: permit pre-minified JS`


---

diff --git a/guidelines/modules/ROOT/pages/Node.js.adoc b/guidelines/modules/ROOT/pages/Node.js.adoc
index 7144678..86af23f 100644
--- a/guidelines/modules/ROOT/pages/Node.js.adoc
+++ b/guidelines/modules/ROOT/pages/Node.js.adoc
@@ -2,6 +2,8 @@
 
 The upstream Node.js stance on https://nodejs.org/en/blog/npm/npm-1-0-global-vs-local-installation/[global library packages] is that they are ".. best avoided if not needed."  In Fedora, we take the same stance with our nodejs packages.  You can provide a package that uses nodejs, but you should bundle all the nodejs libraries that are needed.
 
+Packages containing JavaScript should make the best effort to regenerate any precompiled/pre-minimized JS wherever possible, as this leads to more maintainable packages. Where this would result in a significant hardship, the bundled pregenerated JS may be shipped with a specfile comment explaining the decision. This does not eliminate the requirement to validate licenses of bundled code. See <> below.
+
 == What to Package
 
 * The interpreter, development headers/libraries, and the assorted tools to manage project-level installations.

From 92d0338f36f2b47d3807e5890e8f6d6185fffbf0 Mon Sep 17 00:00:00 2001
From: Carl George 
Date: Jun 14 2024 19:55:01 +0000
Subject: [PATCH 147/232] Update packaging tutorial link


The creating-rpm-packages page no longer exists.  There is a page-alias
for it, but that alias broke recently and our link didn't work for a
period of time.  It will be more resiliant to use the direct link
instead of relying on the alias.

https://pagure.io/fedora-docs/package-maintainer-docs/issue/160
https://pagure.io/fedora-docs/package-maintainer-docs/pull-request/155

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index ef5650b..2c41cf6 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -24,7 +24,7 @@ please see the following:
 
 * https://docs.fedoraproject.org/en-US/package-maintainers/Joining_the_Package_Maintainers/[Join the Package Maintainers]
 * https://docs.fedoraproject.org/en-US/package-maintainers/New_Package_Process_for_Existing_Contributors/[New Package Process for Existing Contributors]
-* https://docs.fedoraproject.org/en-US/quick-docs/creating-rpm-packages/index.html[Creating RPM packages]
+* https://docs.fedoraproject.org/en-US/package-maintainers/Packaging_Tutorial/[Packaging Tutorial]
 
 It is the package reviewer's responsibility to point out specific problems with a package
 and a packager's responsibility to deal with those issues.

From aef334b8f26de89843042753b120eedf40d0566a Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Jun 18 2024 13:20:34 +0000
Subject: [PATCH 148/232] BRP scripts: update advice


The command to get a list of scripts was outdated, since a bunch
of them are pulled in via %_os_install_post_python, and since
https://fedoraproject.org/wiki/Changes/ReproduciblePackageBuilds,
via %__os_install_post_build_reproducibility.

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 2c41cf6..d5fe39a 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -3179,7 +3179,7 @@ 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:
+For example, to disable the `+brp-python-bytecompile+` script:
 
 [source, rpm-spec]
 ----
@@ -3193,7 +3193,12 @@ in an accompanying comment.
 For a list of the BRP scripts run by default,
 invoke:
 
- fgrep '%__brp_' /usr/lib/rpm/redhat/macros
+ sed -r -n '/^%.?__os_install_post/,/%.?nil/p' /usr/lib/rpm/redhat/macros
+
+For a list of all BRP scripts,
+invoke:
+
+ rpmbuild --eval '%dump' |& grep ': __brp_'
 
 == Packaging for EPEL
 

From 1ad96626e43a7dce217ce354a07422825b288be1 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Jun 18 2024 13:20:34 +0000
Subject: [PATCH 149/232] BRP scripts: add short subsection about add-determinism


https://fedoraproject.org/wiki/Changes/ReproduciblePackageBuilds

Note that I added some more information to
/usr/lib/rpm/macros.d/macros.build-reproducibility upstream, but
it's not visible in Fedora package yet. See
https://github.com/keszybz/add-determinism/blob/main/rpm/macros.build-reproducibility
for the latest version.

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index d5fe39a..a7e52b0 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -3200,6 +3200,17 @@ invoke:
 
  rpmbuild --eval '%dump' |& grep ': __brp_'
 
+=== Removal of common sources of build irreproducibility
+
+One of the BRP scripts that is invoked by default is
+`+%__os_install_post_build_reproducibility+`.
+Its purpose is to normalize installed files
+by removing unwanted embedded metadata that is dependent on the build environment
+and may cause different builds from the same sources to be irreproducible.
+
+See `/usr/lib/rpm/macros.d/macros.build-reproducibility`
+for details about how it can be configured.
+
 == Packaging for EPEL
 
 For the most part, these guidelines

From 6971aed95db412841443abf5ff566a4e704e67e6 Mon Sep 17 00:00:00 2001
From: Marian Koncek 
Date: Jul 16 2024 16:34:03 +0000
Subject: [PATCH 150/232] OCaml guidelines: fix unordered and nested lists


---

diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc
index 565a9eb..7c262d6 100644
--- a/guidelines/modules/ROOT/pages/OCaml.adoc
+++ b/guidelines/modules/ROOT/pages/OCaml.adoc
@@ -148,12 +148,13 @@ This is because OCaml scripts are recompiled each time they run.
 == RPM Macros
 
 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:
-    * -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).
+** -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).
 
 == Examples
 
@@ -163,20 +164,21 @@ This section contains example spec files illustrating how to build OCaml library
 
 Dune is a popular build tool for OCaml packages.
 RPM macros are available to make building with dune simple.
+
 * `%dune_build`: Invoke dune to build all installable artifacts in release mode.  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`.
-    * -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact.
-    * --: separate flags for this macro from flags to pass to dune
+** -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`.
+** -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact.
+** --: 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.
-    * --: separate flags for this macro from flags to pass to dune
+** -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.
+** --: 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`.
-    * -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact.
-    * --: separate flags for this macro from flags to pass to dune
+** -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`.
+** -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact.
+** --: separate flags for this macro from flags to pass to dune
 * `%odoc_package`: Declare a subpackage that olds odoc-generated documentation.  Flags:
-    * -L : give the name of a file to include in the subpackage as a license file.
+** -L : give the name of a file to include in the subpackage as a license file.
 
 The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with dune.
 

From 237094dd8e620680801ae93b14429a6c4b9947a7 Mon Sep 17 00:00:00 2001
From: Marian Koncek 
Date: Jul 16 2024 16:47:12 +0000
Subject: [PATCH 151/232] OCaml guidelines: use monospace fonts much more


---

diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc
index 7c262d6..c1d1f59 100644
--- a/guidelines/modules/ROOT/pages/OCaml.adoc
+++ b/guidelines/modules/ROOT/pages/OCaml.adoc
@@ -8,10 +8,10 @@ It does not intend to cover all situations, but to codify those practices which 
 The base OCaml compiler is called ocaml.
 
 OCaml modules, libraries and syntax extensions should be named ocaml-foo.
-Examples include: ocaml-extlib, ocaml-ssl.
+Examples include: `ocaml-extlib`, `ocaml-ssl`.
 
 This naming does not apply to applications written in OCaml, which can be given their normal name.
-Examples include: coccinelle, frama-c, virt-top.
+Examples include: `coccinelle`, `frama-c`, `virt-top`.
 
 Rationale: this is how they are named in other distros (Debian, PLD) and this is consistent with Perl / PHP / Python naming.
 
@@ -21,72 +21,73 @@ Rationale: this is how they are named in other distros (Debian, PLD) and this is
 
 In order to allow OCaml scripts and the toplevel to use a library, the main package should contain only files matching:
 
-* *.cma (contains the bytecode)
-* *.cmi (contains the compiled signature)
-* *.so (if present, contains OCaml <-> C stubs)
-* META (the findlib description)
-* *.so.owner (if present, used by findlib)
-* a license file (if present) marked %license
+* `*.cma` (contains the bytecode)
+* `*.cmi` (contains the compiled signature)
+* `*.so` (if present, contains OCaml <-> C stubs)
+* `META` (the findlib description)
+* `*.so.owner` (if present, used by findlib)
+* a license file (if present) marked `%license`
 
-* .cmo files are not normally included. There is one exception where *.cmo files may be included: if the cmo file is needed to link, then it must be included to allow the library to be linked properly.
+* `.cmo` files are not normally included. There is one exception where `*.cmo` files may be included: if the `.cmo` file is needed to link, then it must be included to allow the library to be linked properly.
 
-If the package contains *.so files, then they should not have rpaths, as per Fedora packaging guidelines.
+If the package contains `*.so` files, then they should not have rpaths, as per Fedora packaging guidelines.
 
-The packager should check the META file footnote:[http://projects.camlcity.org/projects/dl/findlib-1.9.5/doc/ref-html/r759.html[findlib Reference Manual - META files.]].
-If there is no META file, then the packager should create one, include it in the package, and pass it to the upstream maintainer.
+The packager should check the `META` file footnote:[http://projects.camlcity.org/projects/dl/findlib-1.9.5/doc/ref-html/r759.html[findlib Reference Manual - META files.]].
+If there is no `META` file, then the packager should create one, include it in the package, and pass it to the upstream maintainer.
 
 Rationale: OCaml does not support dynamic linking of binaries, and even if it did with the current module hash system for expressing strict typing requirements almost any conceivable change to a library would require the binary to be recompiled.
 OCaml scripts are the closest we come to dynamic linking, in as much as they do not usually depend on a specific version of a library (albeit this only works because the scripts are recompiled each time they run).
 
-=== -devel subpackage
+=== `-devel` subpackage
 
-The -devel subpackage of a library should contain all other files required to allow development with the library. Normally these would be:
+The `-devel` subpackage of a library should contain all other files required to allow development with the library. Normally these would be:
 
-* *.a (contains the compiled machine code)
-* *.cmxa (describes the compiled machine code)
-* *.cmx (if present, allows cross-module optimizations)
-* *.mli (contains the signature of the library)
+* `*.a` (contains the compiled machine code)
+* `*.cmxa` (describes the compiled machine code)
+* `*.cmx` (if present, allows cross-module optimizations)
+* `*.mli` (contains the signature of the library)
 
-* .o files are not normally included. There is one exception -- if the file is needed to link (like std_exit.cmx and std_exit.o in OCaml itself), then it should be included.
+* `.o` files are not normally included. There is one exception -- if the file is needed to link (like `std_exit.cmx` and `std_exit.o` in OCaml itself), then it should be included.
 
-* .ml files are not normally included. The exception is if the file describes a module signature _and_ there is no corresponding .mli file, then the .ml file should be included. (Note that Debian is more permissive and they often distribute *.ml files, allowing the programmer to peek at the implementation of a module).
+* `.ml` files are not normally included. The exception is if the file describes a module signature _and_ there is no corresponding `.mli` file, then the `.ml` file should be included. (Note that Debian is more permissive and they often distribute `*.ml` files, allowing the programmer to peek at the implementation of a module).
 
-Documentation, examples and other articles which are useful to the developer may be included in the -devel sub-package.
-The license file (which is in the main package) does not need to be included again in the -devel subpackage.
+Documentation, examples and other articles which are useful to the developer may be included in the `-devel` sub-package.
+The license file (which is in the main package) does not need to be included again in the `-devel` subpackage.
 
-If the -devel subpackage would only contain documentation files, then the packager may at their discretion place the documentation files in the main package and not have a -devel subpackage at all.
+If the `-devel` subpackage would only contain documentation files, then the packager may at their discretion place the documentation files in the main package and not have a `-devel` subpackage at all.
 
-The -devel subpackage should require the exact name-version-release of the main package (as per Fedora policy).
-It should also require any C libraries required for development, and sometimes this means an explicit 'Requires' is needed.
-For example, ocaml-pcre-devel needs an explicit 'Requires: pcre-devel' to make it usable for development.
+The `-devel` subpackage should require the exact name-version-release of the main package (as per Fedora policy).
+It should also require any C libraries required for development, and sometimes this means an explicit `Requires` is needed.
+For example, `ocaml-pcre-devel` needs an explicit `Requires: pcre-devel` to make it usable for development.
 
-Rationale for inclusion of all cmx files: [*.cmx files] are needed even for modules included in .cmxa libraries in order to enable cross-module optimizations (inlining, constant propagation and direct function calls).
-The .o files are not needed. [From a private email from Alain Frisch]
+Rationale for inclusion of all `.cmx` files: these files are needed even for modules included in `.cmxa` libraries in order to enable cross-module optimizations (inlining, constant propagation and direct function calls).
+The `.o` files are not needed. [From a private email from Alain Frisch]
 
-=== -doc subpackage
+=== `-doc` subpackage
 
 If the documentation files are very large they may be placed in a
-separate -doc subpackage, as per normal Fedora guidelines.
+separate `-doc` subpackage, as per normal Fedora guidelines.
 
-=== -data subpackage
+=== `-data` subpackage
 
 If the package contains excessively large data files, they may
-be placed in a separate -data subpackage, as per normal Fedora guidelines.
+be placed in a separate `-data` subpackage, as per normal Fedora guidelines.
 
-=== Requires and provides
+=== `Requires` and `Provides`
 
-For each module that library A uses from another library B, library A must have a Requires of the form:
-ocaml(Modulename) = MD5hash
-Similarly for each module that library A may provide to other libraries, library A must have a Provides of the same form.
+For each module that library `A` uses from another library `B`, library `A` must have a `Requires` of the form:
+`ocaml(Modulename) = MD5hash`
+
+Similarly for each module that library `A` may provide to other libraries, library `A` must have a `Provides` of the same form.
 
 A library must depend on the precise version of the OCaml compiler, for example:
-ocaml(runtime) = 3.10.0
+`ocaml(runtime) = 3.10.0`
 
-The correct Requires and Provides should be generated automatically.
+The correct `Requires` and `Provides` should be generated automatically.
 
 Rationale: OCaml does not offer binary compatibility between releases of the compiler (even between bugfixes).
 Furthermore the module system uses a hash over the interface and some internals of a module which basically means a library or program must be linked against the identical modules it was compiled with.
-The Requires and Provides lines express the module name and hash so that RPM enforces the same requirements as the OCaml linker itself.
+The `Requires` and `Provides` lines express the module name and hash so that RPM enforces the same requirements as the OCaml linker itself.
 Please see the further reading at the end of this page for more details.
 
 == Packaging binaries
@@ -101,7 +102,7 @@ Binaries should be stripped, as per ordinary Fedora packaging guidelines.
 
 There is one exception where a binary should not be stripped.
 If the package was compiled with `ocamlc -custom` then the package contains bytecode which strip will remove, thus rendering the binary inoperable.
-It is easy to test for this: if after stripping, any attempt to run the binary results in the message _No bytecode file specified_ then the binary is compiled like this and should not be stripped.
+It is easy to test for this: if after stripping, any attempt to run the binary results in the message `No bytecode file specified` then the binary is compiled like this and should not be stripped.
 
 Rationale: https://bugs.debian.org/256900
 
@@ -111,7 +112,7 @@ The packager should attempt to ship native code compiled binaries in preference 
 
 == Bytecode-only architectures
 
-The OCaml native code compiler (ocamlopt) contains code generators for popular architectures, but not for every architecture that Fedora might support.
+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.
@@ -126,7 +127,7 @@ make opt
 %endif
 ....
 
-To test that your spec file will work on such an architecture, temporarily remove or rename /usr/bin/ocamlopt and /usr/bin/ocamlopt.opt while building.
+To test that your spec file will work on such an architecture, temporarily remove or rename `/usr/bin/ocamlopt` and `/usr/bin/ocamlopt.opt` while building.
 
 Rationale: Debian packaging policy section 2.3 does the same thing.
 
@@ -134,9 +135,9 @@ Rationale: Debian packaging policy section 2.3 does the same thing.
 
 The following files should not normally be distributed:
 
-* *.cmo object files. Exception: see above.
-* *.o for corresponding *.cmx. Exception: see above.
-* *.ml sources. Exception: see above.
+* `*.cmo` object files. Exception: see above.
+* `*.o` for corresponding `*.cmx`. Exception: see above.
+* `*.ml` sources. Exception: see above.
 
 == Security issues in OCaml libraries
 
@@ -152,9 +153,9 @@ 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:
-** -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).
+* `%{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).
 
 == Examples
 
@@ -166,21 +167,21 @@ Dune is a popular build tool for OCaml packages.
 RPM macros are available to make building with dune simple.
 
 * `%dune_build`: Invoke dune to build all installable artifacts in release mode.  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`.
-** -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact.
-** --: separate flags for this macro from flags to pass to dune
+** `-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`.
+** `-p `: tell dune to build the comma-separated list of modules only, rather than every installable artifact.
+** `--`: 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.
-** --: separate flags for this macro from flags to pass to dune
+** `-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.
+** `--`: 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`.
-** -p : tell dune to build the comma-separated list of modules only, rather than every installable artifact.
-** --: separate flags for this macro from flags to pass to dune
+** `-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`.
+** `-p `: tell dune to build the comma-separated list of modules only, rather than every installable artifact.
+** `--`: separate flags for this macro from flags to pass to dune
 * `%odoc_package`: Declare a subpackage that olds odoc-generated documentation.  Flags:
-** -L : give the name of a file to include in the subpackage as a license file.
+** `-L `: give the name of a file to include in the subpackage as a license file.
 
-The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with dune.
+The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with `dune`.
 
 .ocaml-dune-example.spec
 [source]
@@ -188,11 +189,11 @@ The following is an example specfile for an imaginary OCaml library called _fool
 include::{examplesdir}/ocaml-dune-example.spec[]
 ----
 
-=== Topkg
+=== `Topkg`
 
-Topkg, the "transitory OCaml software packager", generates scripts that are executed to perform various package and build tasks.
+`topkg`, the "transitory OCaml software packager", generates scripts that are executed to perform various package and build tasks.
 
-The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with topkg.
+The following is an example specfile for an imaginary OCaml library called _foolib_ that is built with `topkg`.
 
 .ocaml-topkg-example.spec
 [source]

From 7711c04bbf241cb313dbc27e472138963b555ee6 Mon Sep 17 00:00:00 2001
From: Marian Koncek 
Date: Jul 16 2024 16:47:36 +0000
Subject: [PATCH 152/232] OCaml guidelines: use one sentence per line


---

diff --git a/guidelines/modules/ROOT/pages/OCaml.adoc b/guidelines/modules/ROOT/pages/OCaml.adoc
index c1d1f59..12914b0 100644
--- a/guidelines/modules/ROOT/pages/OCaml.adoc
+++ b/guidelines/modules/ROOT/pages/OCaml.adoc
@@ -65,13 +65,11 @@ The `.o` files are not needed. [From a private email from Alain Frisch]
 
 === `-doc` subpackage
 
-If the documentation files are very large they may be placed in a
-separate `-doc` subpackage, as per normal Fedora guidelines.
+If the documentation files are very large they may be placed in a separate `-doc` subpackage, as per normal Fedora guidelines.
 
 === `-data` subpackage
 
-If the package contains excessively large data files, they may
-be placed in a separate `-data` subpackage, as per normal Fedora guidelines.
+If the package contains excessively large data files, they may be placed in a separate `-data` subpackage, as per normal Fedora guidelines.
 
 === `Requires` and `Provides`
 

From ec76818f787640238f0afb6c00faf17ac40f66c1 Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Jul 18 2024 16:57:32 +0000
Subject: [PATCH 153/232] Document the -a/-A option for %python_extras_subpkg/%pyproject_extras_subpkg


Co-Authored-By: Karolina Surma 

---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 0bb8aed..f8b1774 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1666,6 +1666,8 @@ The macro also takes `+-i+`/`+-f+`/`+-F+` arguments
 for `+%python_extras_subpkg+` below,
 but if they are not given, a filelist written by `+%pyproject_install+` is used.
 +
+Similarly, the `+-a+`/`+-A+` flags are passed to `+%python_extras_subpkg+`.
++
 This macro generates all the subpackage definition sections
 (`+%package+` including the `+Summary+` and `+Requires+` on the base package,
 `+%description+` and, by default, `+%files+`).
@@ -1715,6 +1717,10 @@ Conflicts with `+-i+` and `+-F+`.
 ** `+-F+`: Skip the %files section entirely
 (if the packager wants to construct it manually).
 Conflicts with `+-i+` and `+-f+`.
+** `+-a+`: Include `+BuildArch: noarch+` in the package definition,
+to be used only when the package is archful,
+but the “base” package passed to `+-n+` is not.
+** `+-A+`: Explicitly disables `+-a+` (does nothing at the moment).
 --
 +
 As with `+%pyproject_extras_subpkg+`:

From c29853b9a1cd4ab017e9604dc7457831e87e05e1 Mon Sep 17 00:00:00 2001
From: Jonathan Steffan 
Date: Jul 18 2024 17:39:00 +0000
Subject: [PATCH 154/232] Update DSO Packaging Guidelines


- Add dedicated section for unversioned SONAMEs
- Detail Vulkan and OpenXR filesystem layout
- Detail loader configuration

---

diff --git a/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc
new file mode 100644
index 0000000..4be5a18
--- /dev/null
+++ b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc
@@ -0,0 +1,112 @@
+= Unversioned Dynamic Shared Objects
+
+The standard policy
+is to have versioned SONAMES
+for all dynamic shared objects (DSO).
+Packagers ``SHOULD`` work with upstreams
+that do not have versioned SONAMES
+to enable this capability.
+This is a hard requirement
+if the DSO is being linked
+between different software.
+
+This policy
+helps to ensure ABI compatibility
+when DSOs are dynamically linked
+between different software.
+
+== When Are Unversioned Dynamic Shared Objects Acceptable
+
+There are a few conditions
+that need to exist in which DSOs are allowed to remain unversioned.
+
+* The DSO ``MUST NOT`` be visible
+to the dynamic linker
+(i.e. the DSO does not show up in ``ldconfig -p`` output)
+
+* The DSO ``MUST`` be located in a private directory
+(i.e. not located directly in /usr/lib[64] or in another directory listed as a library path for the linker)
+
+* The DSO ``MUST NOT`` be linked against and is loaded at runtime
+by the implementing application 
+(i.e. ``dlopen()``)
+
+If these conditions are met,
+the unversioned DSOs
+do not need to be placed in a -devel package.
+
+== Implementation Details
+
+Listed below is information
+for each known use-case for unversioned DSOs.
+Evaluate if your situation matches any of these
+and ask for any clarification
+by opening a ticket with the {packaging-committee}.
+
+=== Vulkan
+
+The https://vulkan.org[Vulkan] ecosystem
+continues to grow in capabilities and adoption.
+One of the core concepts
+is the https://docs.vulkan.org/guide/latest/loader.html[Vulkan Loader].
+This component is responsible for initializing the stack
+and includes loading unversioned DSOs,
+called Drivers and Layers.
+
+Vulkan Drivers need to be visible to the default loader
+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``)
+
+* 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] 
+(i.e. ``%{_libdir}/%{name}/layer``)
+and loaded by configuration
+
+=== OpenXR
+
+The https://www.khronos.org/openxr/[OpenXR] ecosystem
+enables users to run XR applications built against the SDK.
+One of the core concepts
+is the https://registry.khronos.org/OpenXR/specs/1.1/loader.html[OpenXR Loader].
+This component is responsible for initializing the stack
+and includes loading unversioned DSOs,
+called Runtimes and Layers.
+
+OpenXR Runtimes are loaded by configuration as defined by the OpenXR Loader specification.
+
+Runtimes have the following requirements:
+
+* 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 
+(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``)
+and loaded by configuration
+
+=== Other Cases
+
+An example of another case
+is an unversioned DSO
+that is loaded at runtime
+within the same application.
+This allows an application
+to load an optional feature, ship modular capabilities,
+or otherwise ``dlopen()`` it's own capabilities.
+These are allowed as long as the main requirements are met.
diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index a7e52b0..08902dc 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -1363,21 +1363,26 @@ 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.
 
+=== Unversioned Shared Objects
+
 As an additional complication,
-some software generates unversioned shared objects
+some software generates xref:Unversioned_shared_objects.
+adoc[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.
+These files are usually plugins or modular functionality specific to an application,
+and are not to be located in the ld library paths or cache.
+These types of unversioned shared objects
+do not need to go into a -devel package.
+They are only loaded at runtime
+and should be included in a private directory of the main package.
+
+For specific details
+about how to deal with these types of DSOs,
+please see xref:Unversioned_shared_objects.
+adoc[unversioned shared objects]
+for detailed guidance.
+
+=== Exceptions
 
 There are some notable exceptions to this packaging model, specifically:
 

From 7db48db638b6fcf3c86b707a7b7a52bfe99d2536 Mon Sep 17 00:00:00 2001
From: Miroslav Suchý 
Date: Jul 23 2024 08:36:55 +0000
Subject: [PATCH 155/232] Document that Summary tag should not end in a period.


Copying this from "Tags and Sections" for convenience.
---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index a7e52b0..59968bb 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -998,6 +998,8 @@ Packages can contain additional translated summary/description
 for supported Non-English languages,
 if available.
 
+The Summary tag value SHOULD NOT end in a period.
+
 === Trademarks in Summary or Description
 
 Packagers should be careful how they use trademarks

From 56c36b9f7aa7fcd753eb4edf68cd989287185965 Mon Sep 17 00:00:00 2001
From: Arthur Bols 
Date: Aug 01 2024 16:14:47 +0000
Subject: [PATCH 156/232] Add shell completions section


---

diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc
index c75834e..5a366c7 100644
--- a/guidelines/modules/ROOT/nav.adoc
+++ b/guidelines/modules/ROOT/nav.adoc
@@ -79,6 +79,7 @@
 ** xref:LibreOfficeExtensions.adoc[LibreOffice Extensions]
 ** xref:MinGW.adoc[MinGW]
 ** xref:MPI.adoc[MPI]
+** xref:ShellCompletions.adoc[Shell Completions]
 ** xref:SugarActivityGuidelines.adoc[Sugar activities]
 ** xref:Web_Assets.adoc[Web Assets]
 ** xref:WordPress_plugin_packaging_guidelines.adoc[WordPress extensions]
diff --git a/guidelines/modules/ROOT/pages/ShellCompletions.adoc b/guidelines/modules/ROOT/pages/ShellCompletions.adoc
new file mode 100644
index 0000000..e9cf43c
--- /dev/null
+++ b/guidelines/modules/ROOT/pages/ShellCompletions.adoc
@@ -0,0 +1,48 @@
+= Shell Completions
+
+Shell completions are command line completions for a specific shell,
+such as Bash, fish or Zsh.
+
+== RPM Macros
+
+The following macros *MUST* be used instead of hardcoding paths.
+
+[cols=",",options="header"]
+|======================================================================
+| macro                     | definition
+| +%{bash_completions_dir}+ | +%{_datadir}/bash-completion/completions+
+| +%{fish_completions_dir}+ | +%{_datadir}/fish/vendor_completions.d+
+| +%{zsh_completions_dir}+  | +%{_datadir}/zsh/site-functions+
+|======================================================================
+
+
+== Shell Completions Packaging
+
+Shell completion files *MUST* use standard file permissions (0644).
+
+=== Example of shell completions packaging
+
+[source, rpm-spec]
+----
+Name: foo
+...
+
+%install
+...
+
+# Bash completion
+install -Dpm 0644 foo.bash -t %{buildroot}%{bash_completions_dir}
+
+# Fish completion
+install -Dpm 0644 foo.fish -t %{buildroot}%{fish_completions_dir}
+
+# Zsh completion
+install -Dpm 0644 _foo -t     %{buildroot}%{zsh_completions_dir}
+...
+
+%files
+%{bash_completions_dir}/foo.bash
+%{fish_completions_dir}/foo.fish
+%{zsh_completions_dir}/_foo
+
+----

From 308b5422d9817cdab1960e0e34c9bc986e78a88c Mon Sep 17 00:00:00 2001
From: James Antill 
Date: Aug 01 2024 16:28:59 +0000
Subject: [PATCH 157/232] Merge #1368 `Initial unversioned SONAME handling policy.`


---

diff --git a/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc
new file mode 100644
index 0000000..4be5a18
--- /dev/null
+++ b/guidelines/modules/ROOT/pages/Unversioned_shared_objects.adoc
@@ -0,0 +1,112 @@
+= Unversioned Dynamic Shared Objects
+
+The standard policy
+is to have versioned SONAMES
+for all dynamic shared objects (DSO).
+Packagers ``SHOULD`` work with upstreams
+that do not have versioned SONAMES
+to enable this capability.
+This is a hard requirement
+if the DSO is being linked
+between different software.
+
+This policy
+helps to ensure ABI compatibility
+when DSOs are dynamically linked
+between different software.
+
+== When Are Unversioned Dynamic Shared Objects Acceptable
+
+There are a few conditions
+that need to exist in which DSOs are allowed to remain unversioned.
+
+* The DSO ``MUST NOT`` be visible
+to the dynamic linker
+(i.e. the DSO does not show up in ``ldconfig -p`` output)
+
+* The DSO ``MUST`` be located in a private directory
+(i.e. not located directly in /usr/lib[64] or in another directory listed as a library path for the linker)
+
+* The DSO ``MUST NOT`` be linked against and is loaded at runtime
+by the implementing application 
+(i.e. ``dlopen()``)
+
+If these conditions are met,
+the unversioned DSOs
+do not need to be placed in a -devel package.
+
+== Implementation Details
+
+Listed below is information
+for each known use-case for unversioned DSOs.
+Evaluate if your situation matches any of these
+and ask for any clarification
+by opening a ticket with the {packaging-committee}.
+
+=== Vulkan
+
+The https://vulkan.org[Vulkan] ecosystem
+continues to grow in capabilities and adoption.
+One of the core concepts
+is the https://docs.vulkan.org/guide/latest/loader.html[Vulkan Loader].
+This component is responsible for initializing the stack
+and includes loading unversioned DSOs,
+called Drivers and Layers.
+
+Vulkan Drivers need to be visible to the default loader
+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``)
+
+* 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] 
+(i.e. ``%{_libdir}/%{name}/layer``)
+and loaded by configuration
+
+=== OpenXR
+
+The https://www.khronos.org/openxr/[OpenXR] ecosystem
+enables users to run XR applications built against the SDK.
+One of the core concepts
+is the https://registry.khronos.org/OpenXR/specs/1.1/loader.html[OpenXR Loader].
+This component is responsible for initializing the stack
+and includes loading unversioned DSOs,
+called Runtimes and Layers.
+
+OpenXR Runtimes are loaded by configuration as defined by the OpenXR Loader specification.
+
+Runtimes have the following requirements:
+
+* 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 
+(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``)
+and loaded by configuration
+
+=== Other Cases
+
+An example of another case
+is an unversioned DSO
+that is loaded at runtime
+within the same application.
+This allows an application
+to load an optional feature, ship modular capabilities,
+or otherwise ``dlopen()`` it's own capabilities.
+These are allowed as long as the main requirements are met.
diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 59968bb..eb1aac9 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -1365,21 +1365,26 @@ 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.
 
+=== Unversioned Shared Objects
+
 As an additional complication,
-some software generates unversioned shared objects
+some software generates xref:Unversioned_shared_objects.
+adoc[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.
+These files are usually plugins or modular functionality specific to an application,
+and are not to be located in the ld library paths or cache.
+These types of unversioned shared objects
+do not need to go into a -devel package.
+They are only loaded at runtime
+and should be included in a private directory of the main package.
+
+For specific details
+about how to deal with these types of DSOs,
+please see xref:Unversioned_shared_objects.
+adoc[unversioned shared objects]
+for detailed guidance.
+
+=== Exceptions
 
 There are some notable exceptions to this packaging model, specifically:
 

From 948afc37be88c2e5aed04cf5481e8f1f285a7384 Mon Sep 17 00:00:00 2001
From: Vít Ondruch 
Date: Aug 01 2024 16:35:24 +0000
Subject: [PATCH 158/232] Revert "Recommend avoiding macros in file depenencies"


This reverts commit 35d89f0f3ff118359f1fef1c328570a944e0ddf8.

Expanding `%{_bindir}` does not help with deciding, where some specific
tool comes from. Paths must always be taken with care.

---

diff --git a/guidelines/modules/ROOT/pages/RPMMacros.adoc b/guidelines/modules/ROOT/pages/RPMMacros.adoc
index 124cd28..25e1e6e 100644
--- a/guidelines/modules/ROOT/pages/RPMMacros.adoc
+++ b/guidelines/modules/ROOT/pages/RPMMacros.adoc
@@ -31,7 +31,7 @@ $ rpm --define "test Hello, World!" --eval "%{test}"
 Hello, World!
 ....
 
-[#macros_installation]
+
 == Macros for paths set and used by build systems
 
 The macros for build system invocations
diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index eb1aac9..4d6c0d9 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -843,13 +843,6 @@ to express the dependency on that directory existing,
 not on any other functionality of any other package
 that might provide that directory.
 
-When declaring file and directory dependencies,
-xref:RPMMacros.adoc#macros_installation[installation path macros] like `+%{_bindir}+`
-MUST NOT be used.
-`+%{_bindir}+` of the package that provides `+sometool+`
-may be different from `+%{_bindir}+` of a package that requires `+sometool+`.
-In such case, `+BuildRequires: %{_bindir}/sometool+` does not work as expected.
-
 === Explicit Requires
 
 Explicit Requires are Requires added manually by the packager in the spec file.

From 763e981fc43406c9ba186ad4fd7cf4c4e96c7040 Mon Sep 17 00:00:00 2001
From: James Antill 
Date: Aug 01 2024 18:00:51 +0000
Subject: [PATCH 159/232] Reapply "Recommend avoiding macros in file depenencies"


This reverts commit 948afc37be88c2e5aed04cf5481e8f1f285a7384.

---

diff --git a/guidelines/modules/ROOT/pages/RPMMacros.adoc b/guidelines/modules/ROOT/pages/RPMMacros.adoc
index 25e1e6e..124cd28 100644
--- a/guidelines/modules/ROOT/pages/RPMMacros.adoc
+++ b/guidelines/modules/ROOT/pages/RPMMacros.adoc
@@ -31,7 +31,7 @@ $ rpm --define "test Hello, World!" --eval "%{test}"
 Hello, World!
 ....
 
-
+[#macros_installation]
 == Macros for paths set and used by build systems
 
 The macros for build system invocations
diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 4d6c0d9..eb1aac9 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -843,6 +843,13 @@ to express the dependency on that directory existing,
 not on any other functionality of any other package
 that might provide that directory.
 
+When declaring file and directory dependencies,
+xref:RPMMacros.adoc#macros_installation[installation path macros] like `+%{_bindir}+`
+MUST NOT be used.
+`+%{_bindir}+` of the package that provides `+sometool+`
+may be different from `+%{_bindir}+` of a package that requires `+sometool+`.
+In such case, `+BuildRequires: %{_bindir}/sometool+` does not work as expected.
+
 === Explicit Requires
 
 Explicit Requires are Requires added manually by the packager in the spec file.

From e94b1804588c66bced9674a7232c6c4ebebcc02f Mon Sep 17 00:00:00 2001
From: Yash Malik 
Date: Aug 15 2024 09:10:37 +0000
Subject: [PATCH 160/232] Update guidelines/modules/ROOT/pages/CronFiles.adoc


minor grammatical fix
---

diff --git a/guidelines/modules/ROOT/pages/CronFiles.adoc b/guidelines/modules/ROOT/pages/CronFiles.adoc
index f50beac..716ad98 100644
--- a/guidelines/modules/ROOT/pages/CronFiles.adoc
+++ b/guidelines/modules/ROOT/pages/CronFiles.adoc
@@ -29,7 +29,7 @@ so that they can easily be modified by the local system administrator.
 
 == Cron Job file
 
-An typical cron job file is just an script like
+A typical cron job file is just a script like
 
 ....
 #!/bin/sh

From acd36770c8390cad9d7356c4bd08ec352e501539 Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Aug 15 2024 16:50:45 +0000
Subject: [PATCH 161/232] Do not require literal `BuildRequires: python3-devel` in the specfile


When this rule was introduced, using `BuildRequires: python3-devel` was the way to:

 - pull python3-rpm-macros,
 - pull python3-rpm-generators,
 - pull pyproject-rpm-macros,
 - actually BuildRequire python3-devel.

Later, it become possible to use this to achieve the same goals:

    %generate_buildrequires
    %pyproject_buildrequires

This generates the same dependency and can be used out-of-the-box thanks to
pyproject-srpm-macros.

When this feature was introduced, I decided to keep the rule,
because I wanted to encourage people to explicitly keep `BuildRequires: python3-devel`.

However, this requirement makes the use of the RPM pyproject declarative buildsystem
a bit cumbersome.

See https://src.fedoraproject.org/rpms/pyproject-rpm-macros/pull-request/455
and https://rpm-software-management.github.io/rpm/manual/buildsystem.html

If the specfile has:

    BuildSystem: pyproject

We don't also need:

    BuildRequires: python3-devel

The declarative buildsystem is not explicitly mentioned here,
as it is a provisional feature.

---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index f8b1774..cce0a8c 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -104,9 +104,11 @@ if you need help or wish to help out.
 
 *Every* package that uses Python (at runtime and/or build time)
 and/or installs Python modules
-*MUST* explicitly include `+BuildRequires: python3-devel+`
-in its `+.spec+` file,
+*MUST* explicitly BuildRequire `+python3-devel+`,
 even if Python is not actually invoked during build time.
+Such package *MUST* include `+BuildRequires: python3-devel+` in its `+.spec+` file
+or use <>
+in the `+%generate_buildrequires+` section.
 
 If the package uses an alternate Python interpreter instead of `+python3+`
 (e.g. `+pypy+`, `+jython+`, `+python2.7+`),

From 502cfe3612b8ff471f499983cfa51b66b5de2332 Mon Sep 17 00:00:00 2001
From: Clemens Lang 
Date: Aug 20 2024 16:00:48 +0000
Subject: [PATCH 162/232] Fix broken link to Fedora Security Team


The crypto team was probably always a better point of contact to review new crypto libs, considering they also maintain the crypto-policies packages and all the other crypto libraries.
---

diff --git a/guidelines/modules/ROOT/pages/CryptoPolicies.adoc b/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
index cf3a089..68e26cc 100644
--- a/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
+++ b/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
@@ -2,7 +2,7 @@
 
 == Enforcing system crypto policies
 
-In Fedora there are policies for the usage of cryptographic protocols such as TLS that are enforced system-wide. Each application being added in Fedora must be checked to comply with the policies. Currently the policies are restricted to major libraries such as GnuTLS, OpenSSL, NSS, libkrb5, languages such as Java and major applications like OpenSSH and bind. The rpmlint tool will warn when it detects that some action has to be taken; that detection is based on heuristics and limited to C programs, so manual inspection is recommended. Note however, that there are applications which intentionally set weaker, or custom settings on a purpose (e.g., postfix); those need not adhere to the policy. When in doubt, discuss with the https://lists.fedoraproject.org/mailman/listinfo/security[Fedora security team].
+In Fedora there are policies for the usage of cryptographic protocols such as TLS that are enforced system-wide. Each application being added in Fedora must be checked to comply with the policies. Currently the policies are restricted to major libraries such as GnuTLS, OpenSSL, NSS, libkrb5, languages such as Java and major applications like OpenSSH and bind. The rpmlint tool will warn when it detects that some action has to be taken; that detection is based on heuristics and limited to C programs, so manual inspection is recommended. Note however, that there are applications which intentionally set weaker, or custom settings on a purpose (e.g., postfix); those need not adhere to the policy. When in doubt, discuss with the https://lists.fedoraproject.org/admin/lists/crypto-team.lists.fedoraproject.org/[Fedora crypto team].
 
 === New crypto libraries
 

From aee8da22619e49b94a04297f751dff9072d2dd9b Mon Sep 17 00:00:00 2001
From: Davide Cavalca 
Date: Aug 22 2024 16:19:01 +0000
Subject: [PATCH 163/232] Drop obsolete guidance for sysctl.d and binfmt.d


---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index eb1aac9..6080cb6 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -2878,29 +2878,7 @@ 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
-
-If you install a sysctl configuration snippet foobar.conf
-into %\{_sysctldir} (/usr/lib/sysctl.d/)
-you must invoke %sysctl_apply in your %post section:
-
-[source, rpm-spec]
-----
-%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:
-
-[source, rpm-spec]
-----
-%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.
+== tmpfiles.d
 
 There are specific guidelines for handling tmpfiles.d
 configurations and directories

From d44be71e50f0b927590590f6da9b466df0bb9a77 Mon Sep 17 00:00:00 2001
From: Björn Persson 
Date: Aug 22 2024 16:19:48 +0000
Subject: [PATCH 164/232] Removed the "opt" part of two macro names.


Since the macro optflags is deprecated in favor of build_*flags, a corresponding
change has been made to two macros for Ada packages.

---

diff --git a/guidelines/modules/ROOT/pages/Ada.adoc b/guidelines/modules/ROOT/pages/Ada.adoc
index 30f69c5..6e099f2 100644
--- a/guidelines/modules/ROOT/pages/Ada.adoc
+++ b/guidelines/modules/ROOT/pages/Ada.adoc
@@ -20,8 +20,8 @@ and the link:../ReviewGuidelines/[Review Guidelines].
   The right macro to use depends on what build tools the package uses.
 ** For packages that are built with Gnatmake or GPRbuild but without Comfignat
    there are the macros
-   +++Gnatmake_optflags+++
-   and +++GPRbuild_optflags+++,
+   +++Gnatmake_flags+++
+   and +++GPRbuild_flags+++,
    which contain builder, compiler and linker flags.
 ** In case a package’s build system invokes the underlying GNAT tools
    without using Gnatmake or GPRbuild,

From d44ce8465214fc46dc49358c6a8b9a97af10c05b Mon Sep 17 00:00:00 2001
From: Björn Persson 
Date: Aug 22 2024 16:19:48 +0000
Subject: [PATCH 165/232] Dropped "starting with Fedora 18".


Fedora 17 and earlier are no longer a concern.

---

diff --git a/guidelines/modules/ROOT/pages/Ada.adoc b/guidelines/modules/ROOT/pages/Ada.adoc
index 6e099f2..e688cbc 100644
--- a/guidelines/modules/ROOT/pages/Ada.adoc
+++ b/guidelines/modules/ROOT/pages/Ada.adoc
@@ -52,7 +52,7 @@ the macro +++make_install+++ (*not* +++makeinstall+++)
 is recommended.
 * The macro +++GNAT_arches+++ expands to a list of architectures
 where GNAT packages are available in Fedora.
-Starting with Fedora 18, when there is a need to prevent attempts
+When there is a need to prevent attempts
 to build an Ada package on secondary architectures
 where GNAT has not been bootstrapped,
 this *MUST* be done with “`+ExclusiveArch: %{GNAT_arches}+`”.

From 37f68b08532a01702ba48b957fe872f77f6ce97a Mon Sep 17 00:00:00 2001
From: Björn Persson 
Date: Aug 22 2024 16:19:48 +0000
Subject: [PATCH 166/232] Made GPRbuild more prominent in the Ada guidelines.


GPRbuild has almost entirely superseded Gnatmake, so let's mention it first and note the need to buildrequire it.

GPRbuild_arches should have been mentioned ten years ago.

---

diff --git a/guidelines/modules/ROOT/pages/Ada.adoc b/guidelines/modules/ROOT/pages/Ada.adoc
index e688cbc..451beb4 100644
--- a/guidelines/modules/ROOT/pages/Ada.adoc
+++ b/guidelines/modules/ROOT/pages/Ada.adoc
@@ -14,17 +14,19 @@ and the link:../ReviewGuidelines/[Review Guidelines].
   the default Ada compiler in Fedora.
   All packages that contain Ada code *MUST* have “`+BuildRequires: gcc-gnat+`”
   to ensure that the compiler is available.
+* The GNAT tools are usually invoked through the builder GPRbuild,
+  so Ada packages typically need “`+BuildRequires: gprbuild+`”.
 * There are a number of RPM macros that contain
   Fedora’s standard compiler and linker flags adapted for GNAT.
   The appropriate macro *MUST* be used in the build stage.
   The right macro to use depends on what build tools the package uses.
-** For packages that are built with Gnatmake or GPRbuild but without Comfignat
+** For packages that are built with GPRbuild or Gnatmake but without Comfignat
    there are the macros
-   +++Gnatmake_flags+++
-   and +++GPRbuild_flags+++,
+   +++GPRbuild_flags+++
+   and +++Gnatmake_flags+++,
    which contain builder, compiler and linker flags.
 ** In case a package’s build system invokes the underlying GNAT tools
-   without using Gnatmake or GPRbuild,
+   without using GPRbuild or Gnatmake,
    then the appropriate macro for each tool *MUST* be used.
    If for example Gnatlink is invoked directly,
    then the expansion of +++Gnatlink_flags+++ shall be passed to it.
@@ -50,12 +52,14 @@ If needed, a different target and/or additional variables may be appended:
 For the installation stage of Comfignat-using packages,
 the macro +++make_install+++ (*not* +++makeinstall+++)
 is recommended.
-* The macro +++GNAT_arches+++ expands to a list of architectures
+* The macros +++GPRbuild_arches+++ and +++GNAT_arches+++
+expand to a list of architectures
 where GNAT packages are available in Fedora.
 When there is a need to prevent attempts
 to build an Ada package on secondary architectures
 where GNAT has not been bootstrapped,
-this *MUST* be done with “`+ExclusiveArch: %{GNAT_arches}+`”.
+this *MUST* be done with either “`+ExclusiveArch: %{GPRbuild_arches}+`”
+or “`+ExclusiveArch: %{GNAT_arches}+`”.
 * All packages that contain Ada code *MUST* have
 “`+BuildRequires: fedora-gnat-project-common+`”
 to ensure that the necessary RPM macros are defined.
@@ -63,11 +67,11 @@ to ensure that the necessary RPM macros are defined.
 for example a GNAT project file or makefiles and a configuration script,
 then it’s probably best to use that if possible.
 If not, it is recommended that the packager write a GNAT project file
-to control the compilation.
+and use GPRbuild to control the compilation.
 
 == Runpaths
 
-Gnatmake and GPRbuild both add a runpath to the built binaries by default.
+GPRbuild adds a runpath to the built binaries by default.
 Fedora’s builder flags normally include an option
 to disable the automatic runpath.
 There are however cases where it would be advantageous to allow a runpath.
@@ -76,7 +80,7 @@ but run during the build and need to link to the library in the build directory,
 and they may rely on an automatic runpath for this.
 In those cases the spec file may define a macro named
 +++GNAT_add_rpath+++.
-The builders will then be allowed to add a runpath
+The builder will then be allowed to add a runpath
 in those parts of the spec file where
 +++GNAT_add_rpath+++ is defined.
 

From 07ab5eb76f7a6fb7c6acf8e3fd7bb3125e9b80f7 Mon Sep 17 00:00:00 2001
From: Björn Persson 
Date: Aug 22 2024 16:19:48 +0000
Subject: [PATCH 167/232] Added GPRinstall_flags to the Ada guidelines.


---

diff --git a/guidelines/modules/ROOT/pages/Ada.adoc b/guidelines/modules/ROOT/pages/Ada.adoc
index 451beb4..daf1ebf 100644
--- a/guidelines/modules/ROOT/pages/Ada.adoc
+++ b/guidelines/modules/ROOT/pages/Ada.adoc
@@ -179,6 +179,10 @@ The name of the library *MUST* be included
 either in the name of each project file
 or in the name of the subdirectory where the project files are placed.
 
+Packages that use GPRinstall in the installation phase
+can use the macro +++GPRinstall_flags+++
+to pass the correct pathnames and other parameters to GPRinstall.
+
 == Rpmlint and Ada packages
 
 Rpmlint is a program that checks packages for common problems.

From bfd2c6d93b54245d5c6f7bd0445c6d37e38a27e6 Mon Sep 17 00:00:00 2001
From: Björn Persson 
Date: Aug 22 2024 16:19:48 +0000
Subject: [PATCH 168/232] Updated the guidance about trampolines in Ada.


The usage of trampolines has been greatly reduced, and those cases that remain
can't just be ignored as an executable stack has been made an error. Advice on
how to handle them belongs in the section on compilation rather than the one
about RPMlint.

I'm not aware of any other RPMlint warnings that should be ignored as a rule,
so the section about RPMlint becomes empty and is thus removed.

---

diff --git a/guidelines/modules/ROOT/pages/Ada.adoc b/guidelines/modules/ROOT/pages/Ada.adoc
index daf1ebf..a8959f8 100644
--- a/guidelines/modules/ROOT/pages/Ada.adoc
+++ b/guidelines/modules/ROOT/pages/Ada.adoc
@@ -69,6 +69,31 @@ then it’s probably best to use that if possible.
 If not, it is recommended that the packager write a GNAT project file
 and use GPRbuild to control the compilation.
 
+=== Trampolines
+
+An executable stack has been made a linker error in Fedora.
+This can affect Ada packages because
+https://gcc.gnu.org/onlinedocs/gccint/Trampolines.html[GCC uses trampolines]
+to implement some language constructs.
+The compiler’s usage of trampolines has been greatly reduced, but
+https://gcc.gnu.org/onlinedocs/gnat_rm/No_005fImplicit_005fDynamic_005fCode.html[some cases remain].
+One case that occurs is
+when a nested subprogram in Ada
+is passed as a callback routine
+to a function written in C –
+which means that the executable stack is also exposed to C code
+that may contain buffer overflows.
+In such cases the options are
+to explicitly allow an executable stack
+by passing “`+-largs -Wl,--no-warn-execstack+`” to GPRbuild,
+or restructure the code to eliminate the need for trampolines.
+Which option is best may depend on
+how exposed the program is to potentially hostile input.
+
+Correct usage of the RPM macros
+should result in a warning message from the compiler
+that points out where in the code a trampoline is needed.
+
 == Runpaths
 
 GPRbuild adds a runpath to the built binaries by default.
@@ -182,13 +207,3 @@ or in the name of the subdirectory where the project files are placed.
 Packages that use GPRinstall in the installation phase
 can use the macro +++GPRinstall_flags+++
 to pass the correct pathnames and other parameters to GPRinstall.
-
-== Rpmlint and Ada packages
-
-Rpmlint is a program that checks packages for common problems.
-For Ada packages,
-some of the rpmlint messages, such as “executable-stack”,
-can be disregarded,
-because GNAT uses trampolines for pointers to nested functions.
-(See for example
-https://gcc.gnu.org/bugzilla/show_bug.cgi?id=24355[this entry in the GCC Bugzilla].)

From c41ffdb4df2fa146c88a6f533d3c85048279a8a6 Mon Sep 17 00:00:00 2001
From: Carl George 
Date: Aug 22 2024 16:19:56 +0000
Subject: [PATCH 169/232] Adjust phrasing for python3-devel build-time requirement


The current guidelines could be misinterpreted to mean that a Python
package must always have an explicit `BuildRequires: python3-devel` in
the spec file.  This change mentions this option in a bullet list
alongside `%pyproject_buildrequires`.

This also adds a specific mention that pulling in the build-time
dependency transitively is not sufficient.

This is a follow up to #1379.

---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index cce0a8c..a949f67 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -100,16 +100,19 @@ if you need help or wish to help out.
 
 == Distro-wide guidelines
 
-=== BuildRequire python3-devel
+=== Build-time dependency on python3-devel
 
-*Every* package that uses Python (at runtime and/or build time)
+*Every* package that uses Python (at run-time and/or build-time)
 and/or installs Python modules
-*MUST* explicitly BuildRequire `+python3-devel+`,
-even if Python is not actually invoked during build time.
-Such package *MUST* include `+BuildRequires: python3-devel+` in its `+.spec+` file
-or use <>
-in the `+%generate_buildrequires+` section.
+*MUST* have a build-time dependency on `+python3-devel+`,
+even if Python is not actually invoked during build-time.
+Such a package *MUST* use one of the following in its `+.spec+` file:
 
+* <>
+in the `+%generate_buildrequires+` section
+* `+BuildRequires: python3-devel+`
+
+Only having a transitive build-time dependency on `+python3-devel+` is not sufficient.
 If the package uses an alternate Python interpreter instead of `+python3+`
 (e.g. `+pypy+`, `+jython+`, `+python2.7+`),
 it *MAY* instead require the corresponding `+*-devel+` package.

From fc234cd58a4e7184763222fbbfd9eeaabb8f2729 Mon Sep 17 00:00:00 2001
From: James Antill 
Date: Aug 22 2024 16:20:16 +0000
Subject: [PATCH 170/232] Merge #1387 `Update Ada packaging guidelines`


---

diff --git a/guidelines/modules/ROOT/pages/Ada.adoc b/guidelines/modules/ROOT/pages/Ada.adoc
index 30f69c5..a8959f8 100644
--- a/guidelines/modules/ROOT/pages/Ada.adoc
+++ b/guidelines/modules/ROOT/pages/Ada.adoc
@@ -14,17 +14,19 @@ and the link:../ReviewGuidelines/[Review Guidelines].
   the default Ada compiler in Fedora.
   All packages that contain Ada code *MUST* have “`+BuildRequires: gcc-gnat+`”
   to ensure that the compiler is available.
+* The GNAT tools are usually invoked through the builder GPRbuild,
+  so Ada packages typically need “`+BuildRequires: gprbuild+`”.
 * There are a number of RPM macros that contain
   Fedora’s standard compiler and linker flags adapted for GNAT.
   The appropriate macro *MUST* be used in the build stage.
   The right macro to use depends on what build tools the package uses.
-** For packages that are built with Gnatmake or GPRbuild but without Comfignat
+** For packages that are built with GPRbuild or Gnatmake but without Comfignat
    there are the macros
-   +++Gnatmake_optflags+++
-   and +++GPRbuild_optflags+++,
+   +++GPRbuild_flags+++
+   and +++Gnatmake_flags+++,
    which contain builder, compiler and linker flags.
 ** In case a package’s build system invokes the underlying GNAT tools
-   without using Gnatmake or GPRbuild,
+   without using GPRbuild or Gnatmake,
    then the appropriate macro for each tool *MUST* be used.
    If for example Gnatlink is invoked directly,
    then the expansion of +++Gnatlink_flags+++ shall be passed to it.
@@ -50,12 +52,14 @@ If needed, a different target and/or additional variables may be appended:
 For the installation stage of Comfignat-using packages,
 the macro +++make_install+++ (*not* +++makeinstall+++)
 is recommended.
-* The macro +++GNAT_arches+++ expands to a list of architectures
+* The macros +++GPRbuild_arches+++ and +++GNAT_arches+++
+expand to a list of architectures
 where GNAT packages are available in Fedora.
-Starting with Fedora 18, when there is a need to prevent attempts
+When there is a need to prevent attempts
 to build an Ada package on secondary architectures
 where GNAT has not been bootstrapped,
-this *MUST* be done with “`+ExclusiveArch: %{GNAT_arches}+`”.
+this *MUST* be done with either “`+ExclusiveArch: %{GPRbuild_arches}+`”
+or “`+ExclusiveArch: %{GNAT_arches}+`”.
 * All packages that contain Ada code *MUST* have
 “`+BuildRequires: fedora-gnat-project-common+`”
 to ensure that the necessary RPM macros are defined.
@@ -63,11 +67,36 @@ to ensure that the necessary RPM macros are defined.
 for example a GNAT project file or makefiles and a configuration script,
 then it’s probably best to use that if possible.
 If not, it is recommended that the packager write a GNAT project file
-to control the compilation.
+and use GPRbuild to control the compilation.
+
+=== Trampolines
+
+An executable stack has been made a linker error in Fedora.
+This can affect Ada packages because
+https://gcc.gnu.org/onlinedocs/gccint/Trampolines.html[GCC uses trampolines]
+to implement some language constructs.
+The compiler’s usage of trampolines has been greatly reduced, but
+https://gcc.gnu.org/onlinedocs/gnat_rm/No_005fImplicit_005fDynamic_005fCode.html[some cases remain].
+One case that occurs is
+when a nested subprogram in Ada
+is passed as a callback routine
+to a function written in C –
+which means that the executable stack is also exposed to C code
+that may contain buffer overflows.
+In such cases the options are
+to explicitly allow an executable stack
+by passing “`+-largs -Wl,--no-warn-execstack+`” to GPRbuild,
+or restructure the code to eliminate the need for trampolines.
+Which option is best may depend on
+how exposed the program is to potentially hostile input.
+
+Correct usage of the RPM macros
+should result in a warning message from the compiler
+that points out where in the code a trampoline is needed.
 
 == Runpaths
 
-Gnatmake and GPRbuild both add a runpath to the built binaries by default.
+GPRbuild adds a runpath to the built binaries by default.
 Fedora’s builder flags normally include an option
 to disable the automatic runpath.
 There are however cases where it would be advantageous to allow a runpath.
@@ -76,7 +105,7 @@ but run during the build and need to link to the library in the build directory,
 and they may rely on an automatic runpath for this.
 In those cases the spec file may define a macro named
 +++GNAT_add_rpath+++.
-The builders will then be allowed to add a runpath
+The builder will then be allowed to add a runpath
 in those parts of the spec file where
 +++GNAT_add_rpath+++ is defined.
 
@@ -175,12 +204,6 @@ The name of the library *MUST* be included
 either in the name of each project file
 or in the name of the subdirectory where the project files are placed.
 
-== Rpmlint and Ada packages
-
-Rpmlint is a program that checks packages for common problems.
-For Ada packages,
-some of the rpmlint messages, such as “executable-stack”,
-can be disregarded,
-because GNAT uses trampolines for pointers to nested functions.
-(See for example
-https://gcc.gnu.org/bugzilla/show_bug.cgi?id=24355[this entry in the GCC Bugzilla].)
+Packages that use GPRinstall in the installation phase
+can use the macro +++GPRinstall_flags+++
+to pass the correct pathnames and other parameters to GPRinstall.

From 5d6912dd275bca322eb8b6b802aa71eba6e4e7f2 Mon Sep 17 00:00:00 2001
From: Peter Oliver 
Date: Aug 25 2024 20:00:04 +0000
Subject: [PATCH 171/232] Link to the Perl module package naming guide from the Perl-specfic guide


---

diff --git a/guidelines/modules/ROOT/pages/Perl.adoc b/guidelines/modules/ROOT/pages/Perl.adoc
index f0a4fe5..831a54d 100644
--- a/guidelines/modules/ROOT/pages/Perl.adoc
+++ b/guidelines/modules/ROOT/pages/Perl.adoc
@@ -1,5 +1,9 @@
 = Perl Packaging Guidelines
 
+== Module package naming
+
+See xref:Naming.adoc#_perl_modules[Packaging Guidelines: Naming: Perl modules].
+
 == License tag
 
 See https://docs.fedoraproject.org/en-US/legal/license-field/#_perl_packages[Licensing guidelines specific to Perl].

From 2b74c5d013c28d617c9132cd2cf010dfa8f9beb1 Mon Sep 17 00:00:00 2001
From: Vít Ondruch 
Date: Aug 30 2024 11:32:25 +0000
Subject: [PATCH 172/232] Add anchor to each bullet


Resolves #994

---

diff --git a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
index 343b79b..26f95dc 100644
--- a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
+++ b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
@@ -14,49 +14,49 @@ Contributors and reviewers MUST follow the https://docs.fedoraproject.org/en-US/
 
 There are many many things to check for a review. This list is provided to assist new reviewers in identifying areas that they should look for, but is by no means complete. Reviewers should use their own good judgement when reviewing packages. The items listed fall into two categories: *SHOULD* and *MUST*.
 
-* *MUST*: rpmlint must be run on the source rpm and all binary rpms the build produces. The output should be posted in the review. See xref:index.adoc#_use_rpmlint[Packaging Guidelines: Use rpmlint] +
-* *MUST*: The package must be named according to the xref:Naming.adoc[Package Naming Guidelines] . +
-* *MUST*: The spec file name must match the base package `+%{name}+`, in the format `+%{name}.spec+` unless your package has an exemption. See xref:index.adoc#_spec_file_naming[Packaging Guidelines: Spec File Naming] . +
-* *MUST*: The package must meet the xref:index.adoc[Packaging Guidelines] . +
-* *MUST*: The package must be licensed with a Fedora approved license and meet the xref:LicensingGuidelines.adoc[Licensing Guidelines] . +
-* *MUST*: The License field in the package spec file must match the actual license. See xref:LicensingGuidelines.adoc#_valid_license_short_names[Licensing Guidelines: Valid License Short Names] +
-* *MUST*: If (and only if) the source package includes the text of the license(s) in its own file, then that file, containing the text of the license(s) for the package must be included in `+%license+`. See xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text] +
-* *MUST*: The spec file must be written in American English. See xref:index.adoc#_summary_and_description[Packaging Guidelines: Summary and description] +
-* *MUST*: The spec file for the package *MUST* be legible. See xref:index.adoc#_spec_legibility[Packaging Guidelines: Spec Legibility] +
-* *MUST*: The sources used to build the package must match the upstream source, as provided in the spec URL. Reviewers should use sha256sum for this task as it is used by the `+sources+` file once imported into git. If no upstream URL can be specified for this package, please see the xref:SourceURL.adoc[Source URL Guidelines] for how to deal with this. +
-* *MUST*: The package *MUST* successfully compile and build into binary rpms on at least one primary architecture. See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support] +
-* *MUST*: If the package does not successfully compile, build or work on an architecture, then those architectures should be listed in the spec in `+ExcludeArch+`. Each architecture listed in `+ExcludeArch+` *MUST* have a bug filed in bugzilla, describing the reason that the package does not compile/build/work on that architecture. The bug number *MUST* be placed in a comment, next to the corresponding `+ExcludeArch+` line. See xref:index.adoc#_architecture_build_failures[Packaging Guidelines: Architecture Build Failures] +
-* *MUST*: All build dependencies must be listed in `+BuildRequires+`. See xref:index.adoc#buildrequires[Packaging Guidelines: Build-Time Dependencies (BuildRequires)] +
-* *MUST*: The spec file MUST handle locales properly. This is done by using the `+%find_lang+` macro. Using `+%{_datadir}/locale/*+` is strictly forbidden. See xref:index.adoc#_handling_locale_files[Packaging Guidelines: Handling Locale Files] +
-* *MUST*: Packages must NOT bundle copies of system libraries. See xref:index.adoc#bundling[Packaging Guidelines: Bundling and Duplication of System Libraries] +
-* *MUST*: If the package is designed to be relocatable, the packager must state this fact in the request for review, along with the rationalization for relocation of that specific package. Without this, use of Prefix: /usr is considered a blocker. See xref:index.adoc#_relocatable_packages[Packaging Guidelines: Relocatable Packages] +
-* *MUST*: A package must own all directories that it creates. If it does not create a directory that it uses, then it should require a package which does create that directory. See xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File And Directory Ownership] +
-* *MUST*: A Fedora package must not list a file more than once in the spec file's %files listings. (Notable exception: license texts in specific situations)See xref:index.adoc#_duplicate_files[Packaging Guidelines: Duplicate Files] +
-* *MUST*: Permissions on files must be set properly. Executables should be set with executable permissions, for example. See xref:index.adoc#_file_permissions[Packaging Guidelines: File Permissions] +
-* *MUST*: Each package must consistently use macros. See xref:index.adoc#_macros[Packaging Guidelines: Macros] +
-* *MUST*: The package must contain code, or permissible content. See xref:what-can-be-packaged.adoc[What Can Be Packaged] +
-* *MUST*: Large documentation files must go in a -doc subpackage. (The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity). See xref:index.adoc#_documentation[Packaging Guidelines: Documentation] +
-* *MUST*: If a package includes something as %doc, it must not affect the runtime of the application. To summarize: If it is in %doc, the program must run properly if it is not present. See xref:index.adoc#_documentation[Packaging Guidelines: Documentation] +
-* *MUST*: Static libraries must be in a -static package. See xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries] +
-* *MUST*: Development files must be in a -devel package. See xref:index.adoc#_devel_packages[Packaging Guidelines: Devel Packages] +
-* *MUST*: In the vast majority of cases, devel packages must require the base package using a fully versioned dependency: `+Requires: %{name}%{?_isa} = %{version}-%{release}+` See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package] +
-* *MUST*: Packages must NOT contain any .la libtool archives, these must be removed in the spec if they are built. See xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries] +
-* *MUST*: Packages containing GUI applications must include a %\{name}.desktop file, and that file must be properly installed with desktop-file-install in the %install section. If you feel that your packaged GUI application does not need a .desktop file, you must put a comment in the spec file with your explanation. See xref:index.adoc#_desktop_files[Packaging Guidelines: Desktop files] +
-* *MUST*: Packages must not own files or directories already owned by other packages. The rule of thumb here is that the first package to be installed should own the files or directories that other packages may rely upon. This means, for example, that no package in Fedora should ever share ownership with any of the files or directories owned by the `+filesystem+` or `+man+` package. If you feel that you have a good reason to own a file or directory that another package owns, then please present that at package review time. See xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File and Directory Ownership] +
-* *MUST*: All filenames in rpm packages must be valid UTF-8. See xref:index.adoc#_non_ascii_filenames[Packaging Guidelines: Non-ASCII Filenames] +
-* *MUST*: Packages being added to the distribution MUST NOT depend on any packages which have been marked as being deprecated. See xref:deprecating-packages.adoc[Deprecating Packages] +
+* [[rpmlint]]*MUST*: rpmlint must be run on the source rpm and all binary rpms the build produces. The output should be posted in the review. See xref:index.adoc#_use_rpmlint[Packaging Guidelines: Use rpmlint] +
+* [[naming]] *MUST*: The package must be named according to the xref:Naming.adoc[Package Naming Guidelines] . +
+* [[spec-fie-name]] *MUST*: The spec file name must match the base package `+%{name}+`, in the format `+%{name}.spec+` unless your package has an exemption. See xref:index.adoc#_spec_file_naming[Packaging Guidelines: Spec File Naming] . +
+* [[packaging-guidelines]] *MUST*: The package must meet the xref:index.adoc[Packaging Guidelines] . +
+* [[approved-license]] *MUST*: The package must be licensed with a Fedora approved license and meet the xref:LicensingGuidelines.adoc[Licensing Guidelines] . +
+* [[license-field]] *MUST*: The License field in the package spec file must match the actual license. See xref:LicensingGuidelines.adoc#_valid_license_short_names[Licensing Guidelines: Valid License Short Names] +
+* [[license-file]] *MUST*: If (and only if) the source package includes the text of the license(s) in its own file, then that file, containing the text of the license(s) for the package must be included in `+%license+`. See xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text] +
+* [[spec-in-american-english]] *MUST*: The spec file must be written in American English. See xref:index.adoc#_summary_and_description[Packaging Guidelines: Summary and description] +
+* [[legible-spec]] *MUST*: The spec file for the package *MUST* be legible. See xref:index.adoc#_spec_legibility[Packaging Guidelines: Spec Legibility] +
+* [[build-sources]] *MUST*: The sources used to build the package must match the upstream source, as provided in the spec URL. Reviewers should use sha256sum for this task as it is used by the `+sources+` file once imported into git. If no upstream URL can be specified for this package, please see the xref:SourceURL.adoc[Source URL Guidelines] for how to deal with this. +
+* [[successful-build]] *MUST*: The package *MUST* successfully compile and build into binary rpms on at least one primary architecture. See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support] +
+* [[exclude-arch]] *MUST*: If the package does not successfully compile, build or work on an architecture, then those architectures should be listed in the spec in `+ExcludeArch+`. Each architecture listed in `+ExcludeArch+` *MUST* have a bug filed in bugzilla, describing the reason that the package does not compile/build/work on that architecture. The bug number *MUST* be placed in a comment, next to the corresponding `+ExcludeArch+` line. See xref:index.adoc#_architecture_build_failures[Packaging Guidelines: Architecture Build Failures] +
+* [[build-dependencies]] *MUST*: All build dependencies must be listed in `+BuildRequires+`. See xref:index.adoc#buildrequires[Packaging Guidelines: Build-Time Dependencies (BuildRequires)] +
+* [[locales]] *MUST*: The spec file MUST handle locales properly. This is done by using the `+%find_lang+` macro. Using `+%{_datadir}/locale/*+` is strictly forbidden. See xref:index.adoc#_handling_locale_files[Packaging Guidelines: Handling Locale Files] +
+* [[bundling]] *MUST*: Packages must NOT bundle copies of system libraries. See xref:index.adoc#bundling[Packaging Guidelines: Bundling and Duplication of System Libraries] +
+* [[relocatable-package]] *MUST*: If the package is designed to be relocatable, the packager must state this fact in the request for review, along with the rationalization for relocation of that specific package. Without this, use of Prefix: /usr is considered a blocker. See xref:index.adoc#_relocatable_packages[Packaging Guidelines: Relocatable Packages] +
+* [[directory-ownership]] *MUST*: A package must own all directories that it creates. If it does not create a directory that it uses, then it should require a package which does create that directory. See xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File And Directory Ownership] +
+* [[file-listed-once]] *MUST*: A Fedora package must not list a file more than once in the spec file's %files listings. (Notable exception: license texts in specific situations)See xref:index.adoc#_duplicate_files[Packaging Guidelines: Duplicate Files] +
+* [[premissions]] *MUST*: Permissions on files must be set properly. Executables should be set with executable permissions, for example. See xref:index.adoc#_file_permissions[Packaging Guidelines: File Permissions] +
+* [[consistent-macros]] *MUST*: Each package must consistently use macros. See xref:index.adoc#_macros[Packaging Guidelines: Macros] +
+* [[permisible-content]] *MUST*: The package must contain code, or permissible content. See xref:what-can-be-packaged.adoc[What Can Be Packaged] +
+* [[large-documentation]] *MUST*: Large documentation files must go in a -doc subpackage. (The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity). See xref:index.adoc#_documentation[Packaging Guidelines: Documentation] +
+* [[doc-runtime]] *MUST*: If a package includes something as %doc, it must not affect the runtime of the application. To summarize: If it is in %doc, the program must run properly if it is not present. See xref:index.adoc#_documentation[Packaging Guidelines: Documentation] +
+* [[static-libraries]] *MUST*: Static libraries must be in a -static package. See xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries] +
+* [[devel-subpackage]] *MUST*: Development files must be in a -devel package. See xref:index.adoc#_devel_packages[Packaging Guidelines: Devel Packages] +
+* [[versioned-devel-require]] *MUST*: In the vast majority of cases, devel packages must require the base package using a fully versioned dependency: `+Requires: %{name}%{?_isa} = %{version}-%{release}+` See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package] +
+* [[la-archives]] *MUST*: Packages must NOT contain any .la libtool archives, these must be removed in the spec if they are built. See xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries] +
+* [[desktop-file]] *MUST*: Packages containing GUI applications must include a %\{name}.desktop file, and that file must be properly installed with desktop-file-install in the %install section. If you feel that your packaged GUI application does not need a .desktop file, you must put a comment in the spec file with your explanation. See xref:index.adoc#_desktop_files[Packaging Guidelines: Desktop files] +
+* [[file-directory-ownership]] *MUST*: Packages must not own files or directories already owned by other packages. The rule of thumb here is that the first package to be installed should own the files or directories that other packages may rely upon. This means, for example, that no package in Fedora should ever share ownership with any of the files or directories owned by the `+filesystem+` or `+man+` package. If you feel that you have a good reason to own a file or directory that another package owns, then please present that at package review time. See xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File and Directory Ownership] +
+* [[utf-8]] *MUST*: All filenames in rpm packages must be valid UTF-8. See xref:index.adoc#_non_ascii_filenames[Packaging Guidelines: Non-ASCII Filenames] +
+* [[deprecated-packages]] *MUST*: Packages being added to the distribution MUST NOT depend on any packages which have been marked as being deprecated. See xref:deprecating-packages.adoc[Deprecating Packages] +
 
 '''
 
-* *SHOULD*: If the source package does not include license text(s) as a separate file from upstream, the packager SHOULD query upstream to include it. See xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text] +
-* *SHOULD*: The reviewer should test that the package builds in mock. See https://fedoraproject.org/wiki/Using_Mock_to_test_package_builds[Using Mock to test package builds] +
-* *SHOULD*: The package should compile and build into binary rpms on all supported architectures. See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support] +
-* *SHOULD*: The reviewer should test that the package functions as described. A package should not segfault instead of running, for example. +
-* *SHOULD*: If scriptlets are used, those scriptlets must be sane. This is vague, and left up to the reviewers judgement to determine sanity. See xref:index.adoc#_scriptlets[Packaging Guidelines: Scriptlets] +
-* *SHOULD*: Usually, subpackages other than devel should require the base package using a fully versioned dependency. See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package] +
-* *SHOULD*: The placement of pkgconfig(.pc) files depends on their usecase, and this is usually for development purposes, so should be placed in a -devel pkg. A reasonable exception is that the main pkg itself is a devel tool not installed in a user runtime, e.g. gcc or gdb. See xref:index.adoc#_pkgconfig_files_foo_pc[Packaging Guidelines: Pkgconfig Files] +
-* *SHOULD*: If the package has file dependencies outside of /etc, /bin, /sbin, /usr/bin, or /usr/sbin consider requiring the package which provides the file instead of the file itself. See xref:index.adoc#_file_and_directory_dependencies[Packaging Guidelines: File and Directory Dependencies] +
-* *SHOULD*: your package should contain man pages for binaries/scripts. If it doesn't, work with upstream to add them where they make sense. See xref:index.adoc#_manpages[Packaging Guidelines: Manpages] +
+* [[upstream-license-file]] *SHOULD*: If the source package does not include license text(s) as a separate file from upstream, the packager SHOULD query upstream to include it. See xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text] +
+* [[builds-in-mock]] *SHOULD*: The reviewer should test that the package builds in mock. See https://fedoraproject.org/wiki/Using_Mock_to_test_package_builds[Using Mock to test package builds] +
+* [[supports-all-architectures]] *SHOULD*: The package should compile and build into binary rpms on all supported architectures. See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support] +
+* [[functions-as-described]] *SHOULD*: The reviewer should test that the package functions as described. A package should not segfault instead of running, for example. +
+* [[sane-scriplets]] *SHOULD*: If scriptlets are used, those scriptlets must be sane. This is vague, and left up to the reviewers judgement to determine sanity. See xref:index.adoc#_scriptlets[Packaging Guidelines: Scriptlets] +
+* [[subpackage-versioned-requires]] *SHOULD*: Usually, subpackages other than devel should require the base package using a fully versioned dependency. See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package] +
+* [[pkgconfig-in-devel]] *SHOULD*: The placement of pkgconfig(.pc) files depends on their usecase, and this is usually for development purposes, so should be placed in a -devel pkg. A reasonable exception is that the main pkg itself is a devel tool not installed in a user runtime, e.g. gcc or gdb. See xref:index.adoc#_pkgconfig_files_foo_pc[Packaging Guidelines: Pkgconfig Files] +
+* [[file-requires]] *SHOULD*: If the package has file dependencies outside of /etc, /bin, /sbin, /usr/bin, or /usr/sbin consider requiring the package which provides the file instead of the file itself. See xref:index.adoc#_file_and_directory_dependencies[Packaging Guidelines: File and Directory Dependencies] +
+* [[man-pages]] *SHOULD*: your package should contain man pages for binaries/scripts. If it doesn't, work with upstream to add them where they make sense. See xref:index.adoc#_manpages[Packaging Guidelines: Manpages] +
 
 == A note on dependencies
 

From 48573d3c812e994a4778e56e8100038edd9da2ca Mon Sep 17 00:00:00 2001
From: Chihurumnaya Ibiam 
Date: Sep 07 2024 16:52:28 +0000
Subject: [PATCH 173/232] Move comma


Its previous position made the statement difficult
to read.

Signed-off-by: Chihurumnaya Ibiam 

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 6080cb6..e2053f4 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -439,8 +439,8 @@ of the following bugs to simplify tracking such issues:
 
 === Noarch with Unported Dependencies
 
-Sometimes you are working on a noarch package
-that can only run in locations that a different,
+Sometimes, you are working on a noarch package
+that can only run in locations that a different
 arched package builds on.
 This is common for packages written in a scripting language
 which depend on the language's interpreter package, for instance.

From cb89e727d9c7a7b5a3a45922bdb142c206227830 Mon Sep 17 00:00:00 2001
From: Chihurumnaya Ibiam 
Date: Sep 08 2024 14:01:48 +0000
Subject: [PATCH 174/232] Add comma


It contributes to meaning, adding it back.

Signed-off-by: Chihurumnaya Ibiam 

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index e2053f4..1c7b3f1 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -440,7 +440,7 @@ of the following bugs to simplify tracking such issues:
 === Noarch with Unported Dependencies
 
 Sometimes, you are working on a noarch package
-that can only run in locations that a different
+that can only run in locations that a different,
 arched package builds on.
 This is common for packages written in a scripting language
 which depend on the language's interpreter package, for instance.

From cee672ed920f9b51fc1970fabb246f868c570376 Mon Sep 17 00:00:00 2001
From: Chihurumnaya Ibiam 
Date: Sep 08 2024 16:34:59 +0000
Subject: [PATCH 175/232] Remove tautology


Add comma to help with readability.

Signed-off-by: Chihurumnaya Ibiam 

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 1c7b3f1..9099ca9 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -1109,7 +1109,7 @@ The commit author name and email address and the commit timestamp
 are also used in changelog entry.
 
 The text in the the commit message which will become part of the changelog
-should should provide a brief summary of the changes relevant for the user.
+should provide a brief summary of the changes relevant for the user.
 The commit message may contain additional information that is relevant
 to packagers.
 
@@ -1316,7 +1316,7 @@ 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
+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.

From af240ff91578d182c852be72047d824665f79bf5 Mon Sep 17 00:00:00 2001
From: Michal Schorm 
Date: Sep 17 2024 01:09:16 +0000
Subject: [PATCH 176/232] Fix description of %{?systemd_requires} macro to match reality


Fedora Rawhide, 40:

# dnf install systemd-rpm-macros
# rpm --eval %{?systemd_requires}
|  Requires(post): systemd 
|  Requires(preun): systemd 
|  Requires(postun): systemd 

I discovered this issue when processing 'fedora-review' tool output.
It reported:
 | - systemd_post is invoked in %post, systemd_preun in %preun, and
 |  systemd_postun in %postun for Systemd service files.
 |  Note: Systemd service file(s) in maxscale
 |  See: https://docs.fedoraproject.org/en-US/packaging-
 |  guidelines/Scriptlets/#_scriptlets

And I remembered there is a macro for that, but the macro description in the docs
did not match the requirement stated by 'fedora-review'.
---

diff --git a/guidelines/modules/ROOT/pages/Scriptlets.adoc b/guidelines/modules/ROOT/pages/Scriptlets.adoc
index 961aec7..83d7642 100644
--- a/guidelines/modules/ROOT/pages/Scriptlets.adoc
+++ b/guidelines/modules/ROOT/pages/Scriptlets.adoc
@@ -469,7 +469,7 @@ and request the restart and reload operations for the specified units in each on
 If package scriptlets call other systemd tools, for example `systemd-tmpfiles`,
 the package SHOULD declare appropriate dependencies.
 The `+%{?systemd_requires}+` macro is a shortcut to require systemd for the
-`%pre`, `%post`, and `%postun` scriptlets.
+`%post`, `%preun`, and `%postun` scriptlets.
 Note that those dependencies are **not** required for the
 `%systemd_{post,preun,postun_with_restart,user_post,user_preun}`
 macros listed above.

From 65b78e1462aefea220c3d9adfd86d7af7a920daa Mon Sep 17 00:00:00 2001
From: Clemens Lang 
Date: Sep 17 2024 12:07:59 +0000
Subject: [PATCH 177/232] Replace security team in guidelines/modules/ROOT/pages/CryptoPolicies.adoc


The security team is still defunct, I forgot to edit the second occurrence. Replace it with a link to the Fedora crypto team.
---

diff --git a/guidelines/modules/ROOT/pages/CryptoPolicies.adoc b/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
index 68e26cc..21e61ce 100644
--- a/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
+++ b/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
@@ -6,7 +6,7 @@ In Fedora there are policies for the usage of cryptographic protocols such as TL
 
 === New crypto libraries
 
-New crypto libraries must comply with the crypto policies to enter Fedora, unless an exception has been granted by Fedora packaging committee, after consulting with Fedora security team.
+New crypto libraries must comply with the crypto policies to enter Fedora, unless an exception has been granted by Fedora packaging committee, after consulting with https://lists.fedoraproject.org/admin/lists/crypto-team.lists.fedoraproject.org/[Fedora crypto team].
 
 === C/C++ applications
 

From 9331ee8cfc1a75c3442f589389a0325c90ca69ff Mon Sep 17 00:00:00 2001
From: Brian (bex) Exelbierd 
Date: Sep 20 2024 05:17:48 +0000
Subject: [PATCH 178/232] clarify summary and description section


Merges: #912

---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 9099ca9..0d0f6d3 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -981,24 +981,31 @@ 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 tag value SHOULD NOT end in a period.
+The description should expand upon this.
+
+=== Dos and Don'ts
+
+* Do not end the summary with a period.
+* The summary should be 80 characters/columns or less.
+  If you are using something other than ASCII
+  look at a utf length function or something similar
+  to calculate the column count.
+* Make sure that there are no lines in the description longer than 80 characters/columns.
+  If you are using something other than ASCII
+  look at a utf length function or something similar
+  to calculate the column count.
+* 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.
+* For consistency,
+  we use the American English spelling and grammar rules
+  in the summary and description.
+  Packages can contain additional translated summary/description
+  for supported Non-English languages,
+  if available.
 
 === Trademarks in Summary or Description
 

From aea3bb78be208437f5273fda361c12cebff378b7 Mon Sep 17 00:00:00 2001
From: Troy Dawson 
Date: Sep 25 2024 15:51:28 +0000
Subject: [PATCH 179/232] Update qt linguist section


qt-devel is for qt4 only and is no longer used.
Nowdays the qt linguist tools get pulled in by dependencies whenever the kfX-rpm-macros or qtX-qttools-devel is installed.
But, for those cases where neither of those packages are added, and the Qt Linguist tool chain is needed, we should require qt6-linguist.

Signed-off-by: Troy Dawson 
---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 0d0f6d3..4d6751e 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -2185,11 +2185,11 @@ BuildRequires: gettext
 ----
 
 For Qt-based packages that use the Linguist tool chain,
-for the localization utilities add
+for the localization utilities add the appropriate qtX-linguist package
 
 [source, rpm-spec]
 ----
-BuildRequires: qt-devel
+BuildRequires: qt6-linguist
 ----
 
 If you have few enough locale files that they can all go into one package,

From 788b0cdc9e7c6c94cd44c39711398ee2a44c06cf Mon Sep 17 00:00:00 2001
From: James Antill 
Date: Sep 26 2024 16:22:03 +0000
Subject: [PATCH 180/232] Merge #1311 `Add an evidence for font package naming`


---

diff --git a/guidelines/modules/ROOT/pages/Naming.adoc b/guidelines/modules/ROOT/pages/Naming.adoc
index 2bd567e..83637f8 100644
--- a/guidelines/modules/ROOT/pages/Naming.adoc
+++ b/guidelines/modules/ROOT/pages/Naming.adoc
@@ -210,7 +210,21 @@ Large can refer to either size or quantity of files.
 Packages containing fonts must be named
 `+[foundryname-]projectname[-fontfamilyname]-fonts+`,
 in lowercase.
-For a full explanation, see xref:FontsPolicy.adoc#_naming[Packaging/FontsPolicy#Naming].
+
+=== Clarifications
+
+1.  For Fedora purposes a “foundry” is an entity that publishes a set of fonts with consistent font QA rules. Thus a generic hosting service such as http://www.sf.net[Sourceforge] is not a foundry, but the http://openfontlibrary.org/[Open Font Library] is.
+2.  It is good practice to contract _foundryname-_ in a short prefix.
+3.  The _foundryname-_ prefix can optionally be skipped:
+* for entities that never released more than one font family, or
+* when the font project and the publishing entity are one and the same.
+4.  If _projectname_ or _foundryname_ are repeated in _fontfamilyname_, they can be dropped from _fontfamilyname_.
+5.  When _foundryname_, _projectname_ or _fontfamilyname_ contain the _font_ or _fonts_ affix, this affix should be dropped from themfootnote:[To avoid _foofont-fonts_ packages.].
+6.  _-fontfamilyname_ should not be included in the srpm name of a package that includes several different font families.
+7.  If any element of the naming contains spaces, they should be replaced by “-”.
+8.  The use of the _-fonts_ suffix is not dependant on the actual number of font files in the package.
+
+When in doubt, ask the https://fedoraproject.org/wiki/Fonts_SIG_mailing_lists[mailing list] for clarification.
 
 == Addon Packages
 

From 20172176051f437266e3ff2d5194a18183d01678 Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Oct 03 2024 07:34:03 +0000
Subject: [PATCH 181/232] Document %pyproject_buildrequires -p


Option added in pyproject-rpm-macros 1.15.0
More context can be found on python-devel thread:
https://lists.fedoraproject.org/archives/list/python-devel@lists.fedoraproject.org/message/GVV77IVGTX5JCNAHG25XVOENCPRCKCLK/

---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index a949f67..4effa8c 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1480,6 +1480,9 @@ The macro has these options:
 run-time requirements are included by default).
 ** `+-x EXTRA+`: Include dependencies given by the given <>.
 Cannot be used with `+-R+`.
+** `+-p`: Read run-time dependencies from pyproject.toml [project] table.
+This reads also the [optional-dependencies] for the given <>.
+Cannot be used with `+-R+`.
 ** `+-t+`: Include dependencies for the default _tox_ environment.
 Cannot be used with `+-R+`.
 ** `+-e ENV+`: Include dependencies for the given _tox_ environment,

From e238f14b9115023eedbdc88fcbc080f5352aaedf Mon Sep 17 00:00:00 2001
From: Jonathan Steffan 
Date: Oct 05 2024 22:27:04 +0000
Subject: [PATCH 182/232] Fix xref:Unversioned_shared_objects.adoc


---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 4d6751e..36f7272 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -1375,8 +1375,7 @@ packagers must be careful to move to the versioned layout described above.
 === Unversioned Shared Objects
 
 As an additional complication,
-some software generates xref:Unversioned_shared_objects.
-adoc[unversioned shared objects]
+some software generates xref:Unversioned_shared_objects.adoc[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 to be located in the ld library paths or cache.
@@ -1387,8 +1386,7 @@ and should be included in a private directory of the main package.
 
 For specific details
 about how to deal with these types of DSOs,
-please see xref:Unversioned_shared_objects.
-adoc[unversioned shared objects]
+please see xref:Unversioned_shared_objects.adoc[unversioned shared objects]
 for detailed guidance.
 
 === Exceptions

From 4bae8db5783671b40c6ce417df22452eb4ae02dd Mon Sep 17 00:00:00 2001
From: Michel Alexandre Salim 
Date: Oct 10 2024 16:23:50 +0000
Subject: [PATCH 183/232] Update example using python3_version_nodots


This is not defined until `python3-devel` is installed, so it has to be
conditionally evaluated just like the previous `python3_version`
example.

ALso note that the comparison using `python3_version` does not work on
EPEL 9 as well, and `python3_version_nodots` is required.

Signed-off-by: Michel Alexandre Salim 

Changed 38 back to 39.

Merges: #1292

Signed-off-by: James Antill 

---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 4effa8c..5ba0c56 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1842,12 +1842,12 @@ similar to the Python string prefixes:
 
 [NOTE]
 ====
-As a workaround for compatibility with RPM releases before 4.16 (Fedora 33),
+As a workaround for compatibility with RPM releases up to 4.16 (EPEL 9),
 `+%{python3_version_nodots}+` can be compared as an integers:
 
 [source,spec]
 ----
-%if %{python3_version_nodots} > 38
+%if 0%{?python3_version_nodots} > 39
 ...
 %endif
 ----

From 362291f8aebe40c1c60383239a76bf6d01eb64d1 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Oct 15 2024 16:18:59 +0000
Subject: [PATCH 184/232] Python: conditionalize note about marshalparser


Marshalparser's job is now done automatically by add-determinism:
https://fedoraproject.org/wiki/Changes/ReproduciblePackageBuilds.
So this section doesn't contain any actionable advice and can be
dropped.

(In principle, there might be other cases of irreproducibility in
.pyc files, e.g. see
https://pagure.io/fedora-reproducible-builds/project/issue/17.
But marshalparser can't help here, and such issues fall under the
general category of irreproducibility bugs that can apply to any
file that is part of a noarch package and there is no need to discuss
this specifically in the context of Python or Python pyc files.)

---

diff --git a/guidelines/modules/ROOT/pages/Python_Appendix.adoc b/guidelines/modules/ROOT/pages/Python_Appendix.adoc
index c2a5895..73ed4ba 100644
--- a/guidelines/modules/ROOT/pages/Python_Appendix.adoc
+++ b/guidelines/modules/ROOT/pages/Python_Appendix.adoc
@@ -424,6 +424,9 @@ Note that this *does disable* the compilation of files in `+/usr/lib(64)?/python
 
 == Byte compilation reproducibility
 
+This subsection only applies to Fedora <= 40, ELN, and EPEL.
+In later Fedora releases, this is implemented automatically.
+
 For two Python files with the exact same content and metadata,
 byte compilation might produce different results.
 The resulting `.pyc` files are functionally identical but are not bit-by-bit identical.
@@ -434,7 +437,7 @@ take a look at https://bugzilla.redhat.com/show_bug.cgi?id=1686078#c2[this Bugzi
 
 This inconvenience might cause a problem in Koji where noarch packages built as a part of an arch build might be rejected because they have different content.
 
-To workaround this issue,
+To work around this issue,
 BuildRequire marshalparser `BuildRequires: /usr/bin/marshalparser`
 (a tool that makes `.pyc` files more reproducible)
 and instruct it to process the `.pyc` files in certain paths by setting the `+%py_reproducible_pyc_path+` macro:

From 22596956706e72a4e1d92e4e3476f4b9bd6ca5b1 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Oct 18 2024 13:54:11 +0000
Subject: [PATCH 185/232] Move note about JavaScript to the JavaScript page


889df8a added the note, but put in the Node.js section. The decision
is about JS in general, so let's move it and provide a link from the
Node.js page.

---

diff --git a/guidelines/modules/ROOT/pages/JavaScript.adoc b/guidelines/modules/ROOT/pages/JavaScript.adoc
index 7b1eb6e..8673aa5 100644
--- a/guidelines/modules/ROOT/pages/JavaScript.adoc
+++ b/guidelines/modules/ROOT/pages/JavaScript.adoc
@@ -20,6 +20,12 @@ Node.js xref:Node.js.adoc[have their own guidelines],
 and software like GNOME which embeds JavaScript for extensions
 have their own directories and policies as well.
 
+Packages containing JavaScript should make the best effort to regenerate any precompiled/minimized JS wherever possible,
+as this leads to more maintainable packages.
+Where this would result in a significant hardship,
+the bundled pregenerated JS may be shipped with a specfile comment explaining the decision.
+This does not eliminate the requirement to validate licenses of bundled code.
+
 == Naming Guidelines
 
 The name of a JavaScript library package MUST start with
diff --git a/guidelines/modules/ROOT/pages/Node.js.adoc b/guidelines/modules/ROOT/pages/Node.js.adoc
index 86af23f..0ac29d6 100644
--- a/guidelines/modules/ROOT/pages/Node.js.adoc
+++ b/guidelines/modules/ROOT/pages/Node.js.adoc
@@ -2,8 +2,6 @@
 
 The upstream Node.js stance on https://nodejs.org/en/blog/npm/npm-1-0-global-vs-local-installation/[global library packages] is that they are ".. best avoided if not needed."  In Fedora, we take the same stance with our nodejs packages.  You can provide a package that uses nodejs, but you should bundle all the nodejs libraries that are needed.
 
-Packages containing JavaScript should make the best effort to regenerate any precompiled/pre-minimized JS wherever possible, as this leads to more maintainable packages. Where this would result in a significant hardship, the bundled pregenerated JS may be shipped with a specfile comment explaining the decision. This does not eliminate the requirement to validate licenses of bundled code. See <> below.
-
 == What to Package
 
 * The interpreter, development headers/libraries, and the assorted tools to manage project-level installations.
@@ -72,7 +70,11 @@ Native (binary) packages must omit `+noarch+` and list only `+%{nodejs_arches}+`
 
 The licenses of the bundled Node.js modules need to be in the spec file.  If you are using our bundling script they will be listed in --bundled-licenses.txt.  It is recommended that you include --bundled-licenses.txt in your rpm
 
-Each time you update your package, you need to verify the bundled licenses against https://fedoraproject.org/wiki/Licensing:Main#Software_License_List[Fedoras Software License List].
+Each time you update your package, you need to verify the bundled licenses against
+https://fedoraproject.org/wiki/Licensing:Main#Software_License_List[Fedoras Software License List].
+Note that precompiled/minimized JavaScript may be packaged,
+but the requirement to verify the licenses also applies to it,
+see the :xref:JavaScript.adoc[JavaScript guidelines].
 
 List all unique licenses on the License: line of your spec file.  https://fedoraproject.org/wiki/Licensing:FAQ?rd=Licensing/FAQ#How_should_I_handle_multiple_licensing_situations.3F[Separate each license with the word "and"]
 

From 319061ff09596f8f715c4adca5ae50f12c83f4ce Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Oct 18 2024 14:06:39 +0000
Subject: [PATCH 186/232] Add missing punctuation, fix link


The wiki page redirects to the antora page, and the anchor didn't work
anymore.

Also use semanatic line breaks.

---

diff --git a/guidelines/modules/ROOT/pages/Node.js.adoc b/guidelines/modules/ROOT/pages/Node.js.adoc
index 0ac29d6..c458977 100644
--- a/guidelines/modules/ROOT/pages/Node.js.adoc
+++ b/guidelines/modules/ROOT/pages/Node.js.adoc
@@ -68,7 +68,10 @@ Native (binary) packages must omit `+noarch+` and list only `+%{nodejs_arches}+`
 
 == Bundled Licenses
 
-The licenses of the bundled Node.js modules need to be in the spec file.  If you are using our bundling script they will be listed in --bundled-licenses.txt.  It is recommended that you include --bundled-licenses.txt in your rpm
+The licenses of the bundled Node.js modules need to be in the spec file.
+If you are using our bundling script,
+they will be listed in `+--bundled-licenses.txt+`.
+It is recommended that you include `+--bundled-licenses.txt+` in the rpm.
 
 Each time you update your package, you need to verify the bundled licenses against
 https://fedoraproject.org/wiki/Licensing:Main#Software_License_List[Fedoras Software License List].
@@ -76,7 +79,8 @@ Note that precompiled/minimized JavaScript may be packaged,
 but the requirement to verify the licenses also applies to it,
 see the :xref:JavaScript.adoc[JavaScript guidelines].
 
-List all unique licenses on the License: line of your spec file.  https://fedoraproject.org/wiki/Licensing:FAQ?rd=Licensing/FAQ#How_should_I_handle_multiple_licensing_situations.3F[Separate each license with the word "and"]
+List all unique licenses on the License: line of your spec file.
+https://docs.fedoraproject.org/en-US/legal/license-field/#_basic_rule[Separate each license with the word "and"].
 
 ....
 License:   and  and 
@@ -91,7 +95,7 @@ cp %{SOURCE3} .
 %license LICENSE %{npm_name}-%{version}-bundled-licenses.txt
 ....
 
-If you have further questions refer to the https://docs.fedoraproject.org/en-US/packaging-guidelines/LicensingGuidelines/[Fedora Licensing Guidelines]
+If you have further questions refer to the https://docs.fedoraproject.org/en-US/packaging-guidelines/LicensingGuidelines/[Fedora Licensing Guidelines].
 
 == Using tarballs from the npm registry
 

From adf7c36214bda86daefb1e02d4c26057b71a5816 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Oct 18 2024 14:06:51 +0000
Subject: [PATCH 187/232] Say that pregenerated css can be shipped


Implements https://pagure.io/fesco/issue/3269.

---

diff --git a/guidelines/modules/ROOT/pages/Web_Assets.adoc b/guidelines/modules/ROOT/pages/Web_Assets.adoc
index e2a7d7c..7f1a7d0 100644
--- a/guidelines/modules/ROOT/pages/Web_Assets.adoc
+++ b/guidelines/modules/ROOT/pages/Web_Assets.adoc
@@ -103,7 +103,12 @@ Pure CSS frameworks can be included as-is.
 CSS frameworks that use an alternative language that compiles to CSS,
 such as https://lesscss.org/[LESS],
 must compile to CSS as part of the build process.
-It is not acceptable to include pre-compiled CSS in Fedora packages.
+
+Packages containing CSS should make the best effort to regenerate any precompiled/minimized CSS wherever possible,
+as this leads to more maintainable packages.
+Where this would result in a significant hardship,
+the bundled pregenerated CSS may be shipped with a specfile comment explaining the decision.
+This does not eliminate the requirement to validate licenses of bundled content.
 
 == Flash
 

From 82155a146830d2c0886df942d692c0f19d09fb67 Mon Sep 17 00:00:00 2001
From: James Antill 
Date: Oct 24 2024 16:15:55 +0000
Subject: [PATCH 188/232] Merge #1402 `Move text about JS to JS page and allow precompiled CSS`


---

diff --git a/guidelines/modules/ROOT/pages/JavaScript.adoc b/guidelines/modules/ROOT/pages/JavaScript.adoc
index 7b1eb6e..8673aa5 100644
--- a/guidelines/modules/ROOT/pages/JavaScript.adoc
+++ b/guidelines/modules/ROOT/pages/JavaScript.adoc
@@ -20,6 +20,12 @@ Node.js xref:Node.js.adoc[have their own guidelines],
 and software like GNOME which embeds JavaScript for extensions
 have their own directories and policies as well.
 
+Packages containing JavaScript should make the best effort to regenerate any precompiled/minimized JS wherever possible,
+as this leads to more maintainable packages.
+Where this would result in a significant hardship,
+the bundled pregenerated JS may be shipped with a specfile comment explaining the decision.
+This does not eliminate the requirement to validate licenses of bundled code.
+
 == Naming Guidelines
 
 The name of a JavaScript library package MUST start with
diff --git a/guidelines/modules/ROOT/pages/Node.js.adoc b/guidelines/modules/ROOT/pages/Node.js.adoc
index 86af23f..c458977 100644
--- a/guidelines/modules/ROOT/pages/Node.js.adoc
+++ b/guidelines/modules/ROOT/pages/Node.js.adoc
@@ -2,8 +2,6 @@
 
 The upstream Node.js stance on https://nodejs.org/en/blog/npm/npm-1-0-global-vs-local-installation/[global library packages] is that they are ".. best avoided if not needed."  In Fedora, we take the same stance with our nodejs packages.  You can provide a package that uses nodejs, but you should bundle all the nodejs libraries that are needed.
 
-Packages containing JavaScript should make the best effort to regenerate any precompiled/pre-minimized JS wherever possible, as this leads to more maintainable packages. Where this would result in a significant hardship, the bundled pregenerated JS may be shipped with a specfile comment explaining the decision. This does not eliminate the requirement to validate licenses of bundled code. See <> below.
-
 == What to Package
 
 * The interpreter, development headers/libraries, and the assorted tools to manage project-level installations.
@@ -70,11 +68,19 @@ Native (binary) packages must omit `+noarch+` and list only `+%{nodejs_arches}+`
 
 == Bundled Licenses
 
-The licenses of the bundled Node.js modules need to be in the spec file.  If you are using our bundling script they will be listed in --bundled-licenses.txt.  It is recommended that you include --bundled-licenses.txt in your rpm
+The licenses of the bundled Node.js modules need to be in the spec file.
+If you are using our bundling script,
+they will be listed in `+--bundled-licenses.txt+`.
+It is recommended that you include `+--bundled-licenses.txt+` in the rpm.
 
-Each time you update your package, you need to verify the bundled licenses against https://fedoraproject.org/wiki/Licensing:Main#Software_License_List[Fedoras Software License List].
+Each time you update your package, you need to verify the bundled licenses against
+https://fedoraproject.org/wiki/Licensing:Main#Software_License_List[Fedoras Software License List].
+Note that precompiled/minimized JavaScript may be packaged,
+but the requirement to verify the licenses also applies to it,
+see the :xref:JavaScript.adoc[JavaScript guidelines].
 
-List all unique licenses on the License: line of your spec file.  https://fedoraproject.org/wiki/Licensing:FAQ?rd=Licensing/FAQ#How_should_I_handle_multiple_licensing_situations.3F[Separate each license with the word "and"]
+List all unique licenses on the License: line of your spec file.
+https://docs.fedoraproject.org/en-US/legal/license-field/#_basic_rule[Separate each license with the word "and"].
 
 ....
 License:   and  and 
@@ -89,7 +95,7 @@ cp %{SOURCE3} .
 %license LICENSE %{npm_name}-%{version}-bundled-licenses.txt
 ....
 
-If you have further questions refer to the https://docs.fedoraproject.org/en-US/packaging-guidelines/LicensingGuidelines/[Fedora Licensing Guidelines]
+If you have further questions refer to the https://docs.fedoraproject.org/en-US/packaging-guidelines/LicensingGuidelines/[Fedora Licensing Guidelines].
 
 == Using tarballs from the npm registry
 
diff --git a/guidelines/modules/ROOT/pages/Web_Assets.adoc b/guidelines/modules/ROOT/pages/Web_Assets.adoc
index e2a7d7c..7f1a7d0 100644
--- a/guidelines/modules/ROOT/pages/Web_Assets.adoc
+++ b/guidelines/modules/ROOT/pages/Web_Assets.adoc
@@ -103,7 +103,12 @@ Pure CSS frameworks can be included as-is.
 CSS frameworks that use an alternative language that compiles to CSS,
 such as https://lesscss.org/[LESS],
 must compile to CSS as part of the build process.
-It is not acceptable to include pre-compiled CSS in Fedora packages.
+
+Packages containing CSS should make the best effort to regenerate any precompiled/minimized CSS wherever possible,
+as this leads to more maintainable packages.
+Where this would result in a significant hardship,
+the bundled pregenerated CSS may be shipped with a specfile comment explaining the decision.
+This does not eliminate the requirement to validate licenses of bundled content.
 
 == Flash
 

From 48eae8e80771aad02fac691ed5b86d9fa1c13ae2 Mon Sep 17 00:00:00 2001
From: Benson Muite 
Date: Oct 25 2024 11:09:51 +0000
Subject: [PATCH 189/232] Prevent breaking macro


The short first column width for widely used macros breaks _localstatedir and
_sharedstatedir at an unusual location, they often appear as _localstate-dir and
_shared-statedir
---

diff --git a/guidelines/modules/ROOT/pages/RPMMacros.adoc b/guidelines/modules/ROOT/pages/RPMMacros.adoc
index 124cd28..d02f0fd 100644
--- a/guidelines/modules/ROOT/pages/RPMMacros.adoc
+++ b/guidelines/modules/ROOT/pages/RPMMacros.adoc
@@ -45,7 +45,7 @@ by looking at `/usr/lib/rpm/platform/*/macros` for the respective platform.
 
 The following table lists macros which are widely used in fedora `.spec` files.
 
-[cols="20%m,30%m,50%",options="header"]
+[cols="32%m,28%m,40%",options="header"]
 |=================================
 | macro                | definition                  | comment
 | +%{_sysconfdir}+     | /etc                        |
@@ -69,7 +69,7 @@ Some seldomly used macros are listed below for completeness.
 Old `.spec` files might still use them,
 and there might be cases where they are still needed.
 
-[cols="20%m,30%m,50%",options="header"]
+[cols="32%m,28%m,40%",options="header"]
 |=================================
 | macro                | definition                   | comment
 | +%{_datarootdir}+    | +%{_prefix}/share+           | default: `/usr/share`
@@ -95,7 +95,7 @@ It is used for setting `DESTDIR` in the package's `%install` step.
 The other macros are usually only used outside `.spec` files.
 For example, they are set by `fedpkg` to override the default directories.
 
-[cols="20%m,60%m,20%",options="header"]
+[cols="25%m,60%m,15%",options="header"]
 |=================================
 | macro                | definition                   | comment
 | +%{buildroot}+       | +%{_buildrootdir}/%{name}-%{version}-%{release}.%{_arch}+ | same as `$BUILDROOT`

From cd5f3c2aaf15588e4ec32b80b8fb1b861b9091dd Mon Sep 17 00:00:00 2001
From: Karolina Surma 
Date: Oct 31 2024 10:39:41 +0000
Subject: [PATCH 190/232] Using %{pypi_source} without argument is deprecated


Being explicit about the first argument will improve the quality of the
specfiles.

---

diff --git a/guidelines/modules/ROOT/pages/SourceURL.adoc b/guidelines/modules/ROOT/pages/SourceURL.adoc
index 51bb955..7b3ea90 100644
--- a/guidelines/modules/ROOT/pages/SourceURL.adoc
+++ b/guidelines/modules/ROOT/pages/SourceURL.adoc
@@ -139,10 +139,11 @@ tar -czvf libfoo-$VERSION-nopatents.tar.gz libfoo-$VERSION
 
 As PyPI has moved to storing files in directories which change depending on the file being stored,
 it is rather unpleasant to use in a `Source:` URL.
-Instead, files.pythonhosted.org can be used trough the `+%{pypi_source}+` macro.
+Instead, files.pythonhosted.org can be used trough the `+%{pypi_source}+` macro,
+followed by the project name.
 
 ....
-Source: %{pypi_source}
+Source: %{pypi_source foo}
 ....
 
 See more about the macro in the xref:Python.adoc#_source_files_from_pypi[Python guidelines].

From 9efd70e0eee7d29728d8a88ac4f8f5d08260dd28 Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Nov 12 2024 22:02:52 +0000
Subject: [PATCH 191/232] Python: %pyproject_buildrequires: Document support for PEP 735 (dependency groups)


---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 5ba0c56..4f2a721 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1125,12 +1125,15 @@ is using an <> like `+[test]+`, `+[testing]+` or `+[dev]+`.
 In this case, upstream’s instructions to install test dependencies
 might look like `+$ pip install -e.[test]+`.
 
+Another way to specify test dependencies is using a dedicated dependency group
+(https://www.python.org/dev/peps/pep-0735/[PEP 735]).
+
 Projects using `+tox+` usually specify test dependencies
 in a `+tox+`-specific format:
 a https://tox.readthedocs.io/en/latest/config.html#conf-requires[requires]
 key in the configuration.
 
-These two forms are handled by
+These three forms are handled by
 the <>.
 
 If upstream does not use either form,
@@ -1144,7 +1147,7 @@ BuildRequires: python3dist(pytest)
 ----
 
 If you need to do this,
-consider asking upstream to add a `+[test]+` extra.
+consider asking upstream to add a `+[test]+` extra or a `test` dependency group.
 
 === Linters
 
@@ -1324,7 +1327,7 @@ Summary:        %{summary}
 
 
 %generate_buildrequires
-%pyproject_buildrequires -x... / -t
+%pyproject_buildrequires -x... / -g... / -t
 
 
 %build
@@ -1480,6 +1483,8 @@ The macro has these options:
 run-time requirements are included by default).
 ** `+-x EXTRA+`: Include dependencies given by the given <>.
 Cannot be used with `+-R+`.
+** `+-g GROUP+`: Include dependencies specified in the given dependency group
+(https://www.python.org/dev/peps/pep-0735/[PEP 735]).
 ** `+-p`: Read run-time dependencies from pyproject.toml [project] table.
 This reads also the [optional-dependencies] for the given <>.
 Cannot be used with `+-R+`.

From a2fc7c91b59a20f0729b52d41ddc327a92dd350c Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Nov 12 2024 22:02:52 +0000
Subject: [PATCH 192/232] Python: Fix a syntax typo


---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 4f2a721..27cacb6 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1485,7 +1485,7 @@ run-time requirements are included by default).
 Cannot be used with `+-R+`.
 ** `+-g GROUP+`: Include dependencies specified in the given dependency group
 (https://www.python.org/dev/peps/pep-0735/[PEP 735]).
-** `+-p`: Read run-time dependencies from pyproject.toml [project] table.
+** `+-p+`: Read run-time dependencies from pyproject.toml [project] table.
 This reads also the [optional-dependencies] for the given <>.
 Cannot be used with `+-R+`.
 ** `+-t+`: Include dependencies for the default _tox_ environment.

From 966dbf618d1ba129f3fda3059223b89d9449eeec Mon Sep 17 00:00:00 2001
From: Jason Tibbitts 
Date: Nov 14 2024 22:21:50 +0000
Subject: [PATCH 193/232] Semantic breaks.


---

diff --git a/guidelines/modules/ROOT/pages/CryptoPolicies.adoc b/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
index 21e61ce..35b3d3b 100644
--- a/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
+++ b/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
@@ -2,31 +2,104 @@
 
 == Enforcing system crypto policies
 
-In Fedora there are policies for the usage of cryptographic protocols such as TLS that are enforced system-wide. Each application being added in Fedora must be checked to comply with the policies. Currently the policies are restricted to major libraries such as GnuTLS, OpenSSL, NSS, libkrb5, languages such as Java and major applications like OpenSSH and bind. The rpmlint tool will warn when it detects that some action has to be taken; that detection is based on heuristics and limited to C programs, so manual inspection is recommended. Note however, that there are applications which intentionally set weaker, or custom settings on a purpose (e.g., postfix); those need not adhere to the policy. When in doubt, discuss with the https://lists.fedoraproject.org/admin/lists/crypto-team.lists.fedoraproject.org/[Fedora crypto team].
+In Fedora there are policies for the usage of cryptographic protocols
+such as TLS that are enforced system-wide.
+Each application being added in Fedora must be checked
+to comply with the policies.
+Currently the policies are restricted to major libraries
+such as GnuTLS, OpenSSL, NSS, libkrb5,
+languages such as Java and major applications like OpenSSH and bind.
+The rpmlint tool will warn when it detects that some action has to be taken;
+that detection is based on heuristics
+and limited to C programs,
+so manual inspection is recommended.
+Note however,
+that there are applications which intentionally set weaker,
+or custom settings on a purpose
+(e.g., postfix);
+those need not adhere to the policy.
+When in doubt,
+discuss with the
+https://lists.fedoraproject.org/admin/lists/crypto-team.lists.fedoraproject.org/[Fedora crypto team].
 
 === New crypto libraries
 
-New crypto libraries must comply with the crypto policies to enter Fedora, unless an exception has been granted by Fedora packaging committee, after consulting with https://lists.fedoraproject.org/admin/lists/crypto-team.lists.fedoraproject.org/[Fedora crypto team].
+New crypto libraries must comply with the crypto policies to enter Fedora,
+unless an exception has been granted by Fedora packaging committee,
+after consulting with
+https://lists.fedoraproject.org/admin/lists/crypto-team.lists.fedoraproject.org/[Fedora crypto team].
 
 === C/C++ applications
 
 * *OpenSSL applications*:
-** _If the application provides a configuration file_ that allows to modify the cipher list string, ensure that the shipped file contains "PROFILE=SYSTEM" as default. In that case no further action is required.
-** _If the application doesn't have a configuration file_, ensure that there is no default cipher list specified, or that the default list is set as "PROFILE=SYSTEM". That is, check the source code for *SSL_CTX_set_cipher_list*(). If it is not present then nothing needs to be done (the default is used). Otherwise, if that call is present and provided a fixed string which does not contain PSK or SRP, replace the string with "PROFILE=SYSTEM", or remove the call.
+** _If the application provides a configuration file_
+that allows to modify the cipher list string,
+ensure that the shipped file contains "PROFILE=SYSTEM" as default.
+In that case no further action is required.
+
+** _If the application doesn't have a configuration file_,
+ensure that there is no default cipher list specified,
+or that the default list is set as "PROFILE=SYSTEM".
+That is, check the source code for *SSL_CTX_set_cipher_list*().
+If it is not present then nothing needs to be done (the default is used).
+Otherwise, if that call is present
+and provided a fixed string which does not contain PSK or SRP,
+replace the string with "PROFILE=SYSTEM",
+or remove the call.
 
 * *GnuTLS applications*:
-** _If the application provides a configuration file_ that allows to modify the cipher priority string, the shipped file contains "@SYSTEM" as default. In that case no further action is required.
-** _If the application doesn't have a configuration file_, ensure that it uses gnutls_set_default_priority(), or that the default priority string is "@SYSTEM". That is, check the source code for *gnutls_priority_set_direct*(), *gnutls_priority_init*(); if they are not present and gnutls_set_default_priority() is used, nothing needs to be done. Otherwise check the strings provided by the application. If it contains PSK or SRP do nothing (these applications are not currently covered by the default policy). If not, then replace gnutls_priority_set_direct() with gnutls_set_default_priority(). If gnutls_priority_init() is used instead with a fixed string, replace the string with "@SYSTEM".
+** _If the application provides a configuration file_
+that allows to modify the cipher priority string,
+the shipped file contains "@SYSTEM" as default.
+In that case no further action is required.
+** _If the application doesn't have a configuration file_,
+ensure that it uses gnutls_set_default_priority(),
+or that the default priority string is "@SYSTEM".
+That is, check the source code for *gnutls_priority_set_direct*(),
+*gnutls_priority_init*();
+if they are not present and gnutls_set_default_priority() is used,
+nothing needs to be done.
+Otherwise check the strings provided by the application.
+If it contains PSK or SRP do nothing
+(these applications are not currently covered by the default policy).
+If not, then replace gnutls_priority_set_direct()
+with gnutls_set_default_priority().
+If gnutls_priority_init() is used instead with a fixed string,
+replace the string with "@SYSTEM".
 
-Applications utilizing other cryptographic libraries do not adhere to the system wide crypto policies (note that adherence to the system-wide policies is work in progress for NSS libraries). Applications in Fedora should use one of these libraries when there is choice, and preferrably the version recommended by upstream.
+Applications utilizing other cryptographic libraries
+do not adhere to the system wide crypto policies
+(note that adherence to the system-wide policies
+is work in progress for NSS libraries)
+ Applications in Fedora should use one of these libraries
+when there is choice,
+and preferrably the version recommended by upstream.
 
 === Perl applications
 
 * *IO::Socket::SSL Perl applications*:
-** Check the source code for passing *SSL_cipher_list* argument to *IO::Socket::SSL*'s methods like *new()*, *start_SSL()*, *new_from_fd()*, *set_defaults()*, *set_client_defaults()*, and *set_server_defaults()*. If it is not present then nothing needs to be done (the default is used). Otherwise, if that argument is present, remove the argument or change its value as described in OpenSSL section.
+** Check the source code for passing *SSL_cipher_list* argument
+to *IO::Socket::SSL*'s methods like *new()*,
+*start_SSL()*,
+*new_from_fd()*,
+*set_defaults()*,
+*set_client_defaults()*,
+and *set_server_defaults()*.
+If it is not present then nothing needs to be done (the default is used).
+Otherwise, if that argument is present,
+remove the argument or change its value as described in OpenSSL section.
 
 * *Net::SSLeay Perl applications*:
-** Check the source code for *CTX_set_cipher_list()*, *set_cipher_list()*, and *set_pref_cipher()* subroutine calls from *Net::SSLeay* name space. If such a call presents, follow instructions described in the OpenSSL section.
+** Check the source code for *CTX_set_cipher_list()*,
+*set_cipher_list()*,
+and *set_pref_cipher()* subroutine calls
+from *Net::SSLeay* name space.
+If such a call presents,
+follow instructions described in the OpenSSL section.
 
 * *LWP::UserAgent Perl applications*:
-** Check the source code for passing *SSL_cipher_list* argument to *ssl_opts()* method call on a *LWP::UserAgent* object. If such a call presents, follow instructions described in the OpenSSL section.
+** Check the source code for passing *SSL_cipher_list* argument
+to *ssl_opts()* method call
+on a *LWP::UserAgent* object.
+If such a call presents,
+follow instructions described in the OpenSSL section.

From 461d671c1a56fcb5382f604297e9c6bbd16db1d8 Mon Sep 17 00:00:00 2001
From: Jason Tibbitts 
Date: Nov 14 2024 22:21:50 +0000
Subject: [PATCH 194/232] Reword exception procedure


The procedure for requesting an exception was a bit unclear.  Reword it
to clarify that the crypto team must approve before FPC becomes
involved.

---

diff --git a/guidelines/modules/ROOT/pages/CryptoPolicies.adoc b/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
index 35b3d3b..b9c033b 100644
--- a/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
+++ b/guidelines/modules/ROOT/pages/CryptoPolicies.adoc
@@ -25,9 +25,14 @@ https://lists.fedoraproject.org/admin/lists/crypto-team.lists.fedoraproject.org/
 === New crypto libraries
 
 New crypto libraries must comply with the crypto policies to enter Fedora,
-unless an exception has been granted by Fedora packaging committee,
-after consulting with
+unless an exception has been granted by Fedora packaging committee.
+If you wish to submit a package which does not comply with the crypto policies,
+you MUST first consult with the
 https://lists.fedoraproject.org/admin/lists/crypto-team.lists.fedoraproject.org/[Fedora crypto team].
+Once their approval has been granted,
+open a ticket with the
+https://pagure.io/packaging-committee[Fedora Packaging Committee]
+requesting an exemption.  Please link to any relevant discussion.
 
 === C/C++ applications
 

From f246cf99b5c3fef74576ce31bf5fb60328c35b0f Mon Sep 17 00:00:00 2001
From: Neal Gompa 
Date: Nov 21 2024 17:29:26 +0000
Subject: [PATCH 195/232] Versioning: Add SCM-prefixed snapshot forms


These snapshot forms are similarly valid and are similar to the schemes
used by other distributions (openSUSE and Debian, in particular).

---

diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc
index 0587168..3cead9f 100644
--- a/guidelines/modules/ROOT/pages/Versioning.adoc
+++ b/guidelines/modules/ROOT/pages/Versioning.adoc
@@ -169,6 +169,8 @@ One of the following formats should be used for the snapshot information field:
 * `++`
 * `+.+`
 * `+.+`
+* `+.`
+* `+.`
 
 Where `++` is a short string
 identifying the source code control system upstream uses

From 6119842a97f7a8de44423ba6016f1e3a888a2e8e Mon Sep 17 00:00:00 2001
From: Miroslav Suchý 
Date: Dec 03 2024 09:19:43 +0000
Subject: [PATCH 196/232] Update Font policy to reflect recent SPDX license changes


---

diff --git a/guidelines/modules/ROOT/pages/FontsPolicy.adoc b/guidelines/modules/ROOT/pages/FontsPolicy.adoc
index f037bbe..4f4bfca 100644
--- a/guidelines/modules/ROOT/pages/FontsPolicy.adoc
+++ b/guidelines/modules/ROOT/pages/FontsPolicy.adoc
@@ -23,7 +23,7 @@ Lastly, <> provides some help, in case a third party attempts to conf
 
 === Legal
 
-* [x] Font files MUST comply with our https://fedoraproject.org/wiki/Licensing:Main?rd=Licensing#Font_Licenses[licensing rules].
+* [x] Font files MUST comply with our https://docs.fedoraproject.org/en-US/legal/license-approval/#_licenses_allowed_for_fonts.
 * [x] Trademark uses MUST be authorized by their owners,
 ** trademarks may occur in font naming or font content (logos…).
 * [x] Registered names or trademarks MUST NOT prevent downstream modifications,
@@ -385,7 +385,7 @@ Those identifiers are followed by variables, containing:
 [source,rpm-spec]
 ----
 %global foundry           SIL
-%global fontlicense       OFL
+%global fontlicense       OFL-1.1
 %global fontlicenses      OFL.txt
 %global fontdocs          *.txt
 %global fontdocsex        %{fontlicenses}

From c144f3d803a57db56730c5505624e862b39509e7 Mon Sep 17 00:00:00 2001
From: Miroslav Suchý 
Date: Dec 03 2024 09:23:36 +0000
Subject: [PATCH 197/232] Update D-lang subsection to reflect recent SPDX licensing changes


---

diff --git a/guidelines/modules/ROOT/pages/D.adoc b/guidelines/modules/ROOT/pages/D.adoc
index dd8a088..a7fdc08 100644
--- a/guidelines/modules/ROOT/pages/D.adoc
+++ b/guidelines/modules/ROOT/pages/D.adoc
@@ -61,7 +61,7 @@ Version:        1.2.3
 Release:        1%{?dist}
 Summary:        Does foo in D
 Group:          Development/Libraries
-License:        LGPLv2+
+License:        LGPL-2.1-or-later
 URL:            https://anywhere.com/
 Source:         https://anywhere.com/%{name}-%{version}.tar.bz2
 BuildRequires:  ldc

From 45c6c8de1fa8fea4991b76627293f8acd79f7420 Mon Sep 17 00:00:00 2001
From: Miroslav Suchý 
Date: Dec 03 2024 09:27:21 +0000
Subject: [PATCH 198/232] update Node.js section to reflect recent SPDX licensing changes


---

diff --git a/guidelines/modules/ROOT/pages/Node.js.adoc b/guidelines/modules/ROOT/pages/Node.js.adoc
index c458977..94c87d5 100644
--- a/guidelines/modules/ROOT/pages/Node.js.adoc
+++ b/guidelines/modules/ROOT/pages/Node.js.adoc
@@ -74,7 +74,7 @@ they will be listed in `+--bundled-licenses.txt+`.
 It is recommended that you include `+--bundled-licenses.txt+` in the rpm.
 
 Each time you update your package, you need to verify the bundled licenses against
-https://fedoraproject.org/wiki/Licensing:Main#Software_License_List[Fedoras Software License List].
+https://docs.fedoraproject.org/en-US/legal/allowed-licenses/[Fedoras Software License List].
 Note that precompiled/minimized JavaScript may be packaged,
 but the requirement to verify the licenses also applies to it,
 see the :xref:JavaScript.adoc[JavaScript guidelines].
@@ -83,7 +83,7 @@ List all unique licenses on the License: line of your spec file.
 https://docs.fedoraproject.org/en-US/legal/license-field/#_basic_rule[Separate each license with the word "and"].
 
 ....
-License:   and  and 
+License:   AND  AND 
 ...
 Source3:        %{npm_name}-%{version}-bundled-licenses.txt
 ...

From 02d90538f50ae9c74700cbfa4e418216f6f7fafc Mon Sep 17 00:00:00 2001
From: Miroslav Suchý 
Date: Dec 03 2024 09:35:57 +0000
Subject: [PATCH 199/232] update Octave section to reflect recent SPDX licensing changes


---

diff --git a/guidelines/modules/ROOT/pages/Octave.adoc b/guidelines/modules/ROOT/pages/Octave.adoc
index 31fe836..1208121 100644
--- a/guidelines/modules/ROOT/pages/Octave.adoc
+++ b/guidelines/modules/ROOT/pages/Octave.adoc
@@ -90,7 +90,7 @@ Version:        1.0.13
 Release:        1%{?dist}
 Summary:        Image processing for Octave
 Group:          Applications/Engineering
-License:        GPLv2+
+License:        GPL-2.0-or-later
 URL:            https://octave.sourceforge.io/image/
 Source:         https://downloads.sourceforge.net/octave/%{octpkg}-%{version}.tar.gz
 

From 6f8544162eeff47a97adac0650483f80aefc0e1c Mon Sep 17 00:00:00 2001
From: Miroslav Suchý 
Date: Dec 03 2024 09:45:20 +0000
Subject: [PATCH 200/232] update Rust section with correct link to legal docs


---

diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc
index 6bbea2c..9e43ae4 100644
--- a/guidelines/modules/ROOT/pages/Rust.adoc
+++ b/guidelines/modules/ROOT/pages/Rust.adoc
@@ -105,7 +105,7 @@ which in turn are covered by different license terms.
 This needs to be taken into account
 by maintaining a separate `License` tag
 for the subpackage that contains these binaries.
-More information about `License` tags is available from the link:[Fedora Legal docs].
+More information about `License` tags is available from the https://docs.fedoraproject.org/en-US/legal/license-field/[Fedora Legal docs].
 
 The `cargo-rpm-macros` package provides two RPM macros
 that help with filling the `License` tag correctly:

From de0b41f6a5061ad0241bc01ba2aac747e18202c8 Mon Sep 17 00:00:00 2001
From: Miroslav Suchý 
Date: Dec 03 2024 09:48:33 +0000
Subject: [PATCH 201/232] update Drupal section to reflect recent SPDX licensing changes


---

diff --git a/guidelines/modules/ROOT/pages/Drupal7.adoc b/guidelines/modules/ROOT/pages/Drupal7.adoc
index fae0195..5717fa2 100644
--- a/guidelines/modules/ROOT/pages/Drupal7.adoc
+++ b/guidelines/modules/ROOT/pages/Drupal7.adoc
@@ -146,7 +146,7 @@ Release:       1%{?dist}
 Summary:       __SUMMARY__
 
 Group:         Applications/Publishing
-License:       GPLv2+
+License:       GPL-2.0-or-later
 URL:           https://drupal.org/project/%{module}
 Source:        https://ftp.drupal.org/files/projects/%{module}-7.x-%{version}.tar.gz
 Source1:       %{name}-RPM-README.txt
@@ -202,7 +202,7 @@ Release:       1%{?dist}
 Summary:       __SUMMARY__
 
 Group:         Applications/Publishing
-License:       GPLv2+
+License:       GPL-2.0-or-later
 URL:           https://drupal.org/project/%{theme}
 Source:        https://ftp.drupal.org/files/projects/%{theme}-7.x-%{version}.tar.gz
 Source1:       %{name}-RPM-README.txt

From c542e02af6f68356691783653169d105f3331fec Mon Sep 17 00:00:00 2001
From: james 
Date: Dec 05 2024 17:37:47 +0000
Subject: [PATCH 202/232] Merge #1421 `update Drupal section to reflect recent SPDX licensing changes`


---

diff --git a/guidelines/modules/ROOT/pages/Drupal7.adoc b/guidelines/modules/ROOT/pages/Drupal7.adoc
index fae0195..5717fa2 100644
--- a/guidelines/modules/ROOT/pages/Drupal7.adoc
+++ b/guidelines/modules/ROOT/pages/Drupal7.adoc
@@ -146,7 +146,7 @@ Release:       1%{?dist}
 Summary:       __SUMMARY__
 
 Group:         Applications/Publishing
-License:       GPLv2+
+License:       GPL-2.0-or-later
 URL:           https://drupal.org/project/%{module}
 Source:        https://ftp.drupal.org/files/projects/%{module}-7.x-%{version}.tar.gz
 Source1:       %{name}-RPM-README.txt
@@ -202,7 +202,7 @@ Release:       1%{?dist}
 Summary:       __SUMMARY__
 
 Group:         Applications/Publishing
-License:       GPLv2+
+License:       GPL-2.0-or-later
 URL:           https://drupal.org/project/%{theme}
 Source:        https://ftp.drupal.org/files/projects/%{theme}-7.x-%{version}.tar.gz
 Source1:       %{name}-RPM-README.txt

From 291647d284d7b06b0c4349abfdd02add26eed446 Mon Sep 17 00:00:00 2001
From: james 
Date: Dec 05 2024 17:38:11 +0000
Subject: [PATCH 203/232] Merge #1419 `update Octave section to reflect recent SPDX licensing changes`


---

diff --git a/guidelines/modules/ROOT/pages/Octave.adoc b/guidelines/modules/ROOT/pages/Octave.adoc
index 31fe836..1208121 100644
--- a/guidelines/modules/ROOT/pages/Octave.adoc
+++ b/guidelines/modules/ROOT/pages/Octave.adoc
@@ -90,7 +90,7 @@ Version:        1.0.13
 Release:        1%{?dist}
 Summary:        Image processing for Octave
 Group:          Applications/Engineering
-License:        GPLv2+
+License:        GPL-2.0-or-later
 URL:            https://octave.sourceforge.io/image/
 Source:         https://downloads.sourceforge.net/octave/%{octpkg}-%{version}.tar.gz
 

From c3a38f55b420ecf4c8f3e8bfa516b9288600f5b6 Mon Sep 17 00:00:00 2001
From: james 
Date: Dec 05 2024 17:38:43 +0000
Subject: [PATCH 204/232] Merge #1418 `update Node.js section to reflect recent SPDX licensing changes`


---

diff --git a/guidelines/modules/ROOT/pages/Node.js.adoc b/guidelines/modules/ROOT/pages/Node.js.adoc
index c458977..94c87d5 100644
--- a/guidelines/modules/ROOT/pages/Node.js.adoc
+++ b/guidelines/modules/ROOT/pages/Node.js.adoc
@@ -74,7 +74,7 @@ they will be listed in `+--bundled-licenses.txt+`.
 It is recommended that you include `+--bundled-licenses.txt+` in the rpm.
 
 Each time you update your package, you need to verify the bundled licenses against
-https://fedoraproject.org/wiki/Licensing:Main#Software_License_List[Fedoras Software License List].
+https://docs.fedoraproject.org/en-US/legal/allowed-licenses/[Fedoras Software License List].
 Note that precompiled/minimized JavaScript may be packaged,
 but the requirement to verify the licenses also applies to it,
 see the :xref:JavaScript.adoc[JavaScript guidelines].
@@ -83,7 +83,7 @@ List all unique licenses on the License: line of your spec file.
 https://docs.fedoraproject.org/en-US/legal/license-field/#_basic_rule[Separate each license with the word "and"].
 
 ....
-License:   and  and 
+License:   AND  AND 
 ...
 Source3:        %{npm_name}-%{version}-bundled-licenses.txt
 ...

From 9cd2851975944b9de5079932a5aff79bf808eb59 Mon Sep 17 00:00:00 2001
From: james 
Date: Dec 05 2024 17:38:51 +0000
Subject: [PATCH 205/232] Merge #1417 `Update D-lang subsection to reflect recent SPDX licensing changes`


---

diff --git a/guidelines/modules/ROOT/pages/D.adoc b/guidelines/modules/ROOT/pages/D.adoc
index dd8a088..a7fdc08 100644
--- a/guidelines/modules/ROOT/pages/D.adoc
+++ b/guidelines/modules/ROOT/pages/D.adoc
@@ -61,7 +61,7 @@ Version:        1.2.3
 Release:        1%{?dist}
 Summary:        Does foo in D
 Group:          Development/Libraries
-License:        LGPLv2+
+License:        LGPL-2.1-or-later
 URL:            https://anywhere.com/
 Source:         https://anywhere.com/%{name}-%{version}.tar.bz2
 BuildRequires:  ldc

From 3f97efd8cfee857af4e4f5a96e77b7584c9facd9 Mon Sep 17 00:00:00 2001
From: james 
Date: Dec 05 2024 17:39:04 +0000
Subject: [PATCH 206/232] Merge #1416 `Update Font policy to reflect recent SPDX license changes`


---

diff --git a/guidelines/modules/ROOT/pages/FontsPolicy.adoc b/guidelines/modules/ROOT/pages/FontsPolicy.adoc
index f037bbe..4f4bfca 100644
--- a/guidelines/modules/ROOT/pages/FontsPolicy.adoc
+++ b/guidelines/modules/ROOT/pages/FontsPolicy.adoc
@@ -23,7 +23,7 @@ Lastly, <> provides some help, in case a third party attempts to conf
 
 === Legal
 
-* [x] Font files MUST comply with our https://fedoraproject.org/wiki/Licensing:Main?rd=Licensing#Font_Licenses[licensing rules].
+* [x] Font files MUST comply with our https://docs.fedoraproject.org/en-US/legal/license-approval/#_licenses_allowed_for_fonts.
 * [x] Trademark uses MUST be authorized by their owners,
 ** trademarks may occur in font naming or font content (logos…).
 * [x] Registered names or trademarks MUST NOT prevent downstream modifications,
@@ -385,7 +385,7 @@ Those identifiers are followed by variables, containing:
 [source,rpm-spec]
 ----
 %global foundry           SIL
-%global fontlicense       OFL
+%global fontlicense       OFL-1.1
 %global fontlicenses      OFL.txt
 %global fontdocs          *.txt
 %global fontdocsex        %{fontlicenses}

From c6941673221a6cd94dae44262c931a83444ddbdd Mon Sep 17 00:00:00 2001
From: Remi Collet 
Date: Dec 06 2024 06:43:45 +0000
Subject: [PATCH 207/232] Revising PHP packaging for PIE


---

diff --git a/guidelines/modules/ROOT/pages/PHP.adoc b/guidelines/modules/ROOT/pages/PHP.adoc
index 899cc04..8842f70 100644
--- a/guidelines/modules/ROOT/pages/PHP.adoc
+++ b/guidelines/modules/ROOT/pages/PHP.adoc
@@ -10,11 +10,13 @@ There are basically 4 different kinds of PHP modules, which are packaged for Fed
 * https://pecl.php.net[PECL] (PHP Extension Community Library) modules,
 which are PHP modules usually written in C
 and are dynamically loaded by the PHP interpreter on startup.
+This will be deprecated in favor of PIE.
 
 * https://pear.php.net[PEAR] (PHP Extension and Application Repository) modules,
 which are reusable components written in PHP, usually classes,
 which can be used in your own PHP applications and scripts
 by using e.g. the `+include()+` directive.
+This is deprecated in favor of composer and discouraged.
 
 * Composer registered libraries,
 which are reusable components written in PHP,
@@ -24,6 +26,13 @@ most often on https://packagist.org/[Packagist].
 
 * CHANNEL : packages which register a channel.
 A channel is a repository which provides PHP extensions.
+This is deprecated and discouraged.
+
+* https://github.com/php/pie[PIE] registered extensions,
+which are PHP modules usually written in C and are dynamically loaded by
+the PHP interpreter on startup, registered on a package registry,
+most often on https://packagist.org/extensions[Packagist].
+
 
 * Other packages providing a PHP extension not handled by PEAR/PECL mechanisms.
 
@@ -68,6 +77,15 @@ should be named
 When `+vendor+` equals `+library+`, one can be dropped
 (ex `+symfony/symfony+` can be named `+php-symfony+`).
 
+* PIE enabled packages (referenced in packagist.org or another registry)
+should be named
+`+php-vendor-extension-%{version}-%{release}.%{arch}.rpm+`
+(where `+vendor/extension+` is the known packagist name,
+`+name+` attribute in `+composer.json+`).
+When `+vendor+` equals `+extension+`, one can be dropped
+(ex `+xdebug/xdebug+` can be named `+php-xdebug+`).
+
+
 * Other packages should be named
 `+php-PackageName-%{version}-%{release}.%{arch}.rpm+`;
 `+%{arch}+` can be `+noarch+` where appropriate.
@@ -248,6 +266,16 @@ Requires:      php(zend-abi) = %{php_zend_api}
 Requires:      php(api) = %{php_core_api}
 ....
 
+Each extension *MUST* also have (to track the move out/in of php-src),
+using the `+module+` name as reported by "php --modules"
+or the .so file name in lowercase.
+
+....
+Provides:     php-module = %{version}
+Provides:     php-module%{_isa} = %{version}
+....
+
+
 [#requires-provides-pecl]
 === PECL Packages
 
@@ -273,6 +301,20 @@ Provides: php-pecl(channelname/foo) = %{version}
 Provides: php-pecl(channelname/foo)%{?_isa} = %{version}
 ....
 
+[#requires-provides-pie]
+=== PIE Packages
+
+PIE extension *MUST* have ABI check
+(see xref:requires-provides-c[C extensions] above).
+
+Each package registered on Packagist
+(which is the most widely used registry, so defined as the implicit one)
+*MUST* have:
+
+....
+Provides:     php-pie(vendor/extension) = %{version}
+....
+
 [#requires-provides-other]
 === Other Packages
 
@@ -295,9 +337,13 @@ should have a Requires on `+httpd+` and `+mod_php+`.
 === Extensions Requires
 
 PHP extensions must have a Requires on all of the dependent extensions
-(`+php-date+`, `+php-gd+`, `+php-mbstring+`, ...).
+(`+php-json+`, `+php-gd+`, `+php-mbstring+`, ...).
 These extensions are virtual Provides of the php sub-packages.
 
+Can be ignored as always present:
+`+core+`, `+date+`, `+filter+`, `+hash+`, `+pcre+`, `+random+`,
+`+reflection+`, `+session+`, `+spl+`, `+standard+`.
+
 [#requires-provides-min-php]
 === Requiring a Minimum PHP version
 

From c36cff8869a1042a84bc565bf6ff6ce12965a765 Mon Sep 17 00:00:00 2001
From: Hirotaka Wakabayashi 
Date: Dec 18 2024 01:38:59 +0000
Subject: [PATCH 208/232] Fixes the invalid link


---

diff --git a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
index 26f95dc..a75255f 100644
--- a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
+++ b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
@@ -1,6 +1,6 @@
 = Package Review Guidelines
 
-This is a set of guidelines for Package Reviews. Note that a complete list of things to check for would be impossible, but every attempt has been made to make this document as comprehensive as possible. Reviewers and contributors (packagers) should use their best judgement whenever items are unclear, and if in doubt, ask on the https://lists.fedoraproject.org/mailman/listinfo/packaging[Fedora packaging list] .
+This is a set of guidelines for Package Reviews. Note that a complete list of things to check for would be impossible, but every attempt has been made to make this document as comprehensive as possible. Reviewers and contributors (packagers) should use their best judgement whenever items are unclear, and if in doubt, ask on the https://lists.fedoraproject.org/admin/lists/packaging.lists.fedoraproject.org/[Fedora packaging list] .
 
 == Package Review Process
 

From a0847926ab7e76e317012034728607af11b8c958 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Jan 08 2025 12:33:53 +0000
Subject: [PATCH 209/232] Snapshots: fix markup error in scm snapshot pattern


The trailing '+' was omitted, so the rendered text retained the _leading_ '+',
literally:
• +.
• +.

The discussion in https://pagure.io/packaging-committee/pull-request/1380
indicates that the literal plus was not intended to be part of the pattern.

While at it, fix grammar above.

---

diff --git a/guidelines/modules/ROOT/pages/Versioning.adoc b/guidelines/modules/ROOT/pages/Versioning.adoc
index 3cead9f..c9f339e 100644
--- a/guidelines/modules/ROOT/pages/Versioning.adoc
+++ b/guidelines/modules/ROOT/pages/Versioning.adoc
@@ -155,7 +155,7 @@ instead.
 Snapshots (a version taken from the upstream source control system not associated with a release),
 **must** contain a snapshot information field after a caret (`+^+`).
 The first part of the field ensures proper sorting.
-That field may either the date in eight-digit "YYYYMMDD" format,
+That field may either be the date in eight-digit "YYYYMMDD" format,
 which specifies the last modification of the source code,
 or a number.
 The packager **may** include up to 17 characters of additional information after the date,
@@ -169,8 +169,8 @@ One of the following formats should be used for the snapshot information field:
 * `++`
 * `+.+`
 * `+.+`
-* `+.`
-* `+.`
+* `+.+`
+* `+.+`
 
 Where `++` is a short string
 identifying the source code control system upstream uses

From af67f0352b280aba24d158a548c963b256f5bff6 Mon Sep 17 00:00:00 2001
From: Peter Oliver 
Date: Jan 09 2025 17:16:13 +0000
Subject: [PATCH 210/232] New guidelines for Tree-sitter parsers


---

diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc
index 5a366c7..ed12e57 100644
--- a/guidelines/modules/ROOT/nav.adoc
+++ b/guidelines/modules/ROOT/nav.adoc
@@ -81,5 +81,6 @@
 ** xref:MPI.adoc[MPI]
 ** xref:ShellCompletions.adoc[Shell Completions]
 ** xref:SugarActivityGuidelines.adoc[Sugar activities]
+** xref:Tree-sitter.adoc[Tree-sitter parsers]
 ** xref:Web_Assets.adoc[Web Assets]
 ** xref:WordPress_plugin_packaging_guidelines.adoc[WordPress extensions]
diff --git a/guidelines/modules/ROOT/pages/Tree-sitter.adoc b/guidelines/modules/ROOT/pages/Tree-sitter.adoc
new file mode 100644
index 0000000..fafe34c
--- /dev/null
+++ b/guidelines/modules/ROOT/pages/Tree-sitter.adoc
@@ -0,0 +1,51 @@
+= Packaging of Tree-sitter parsers
+
+== Macros
+
+The macros in package `tree-sitter-srpm-macros` can do most of the work
+for you.
+
+=== Specifying the build system
+
+Declare that this is a Tree-sitter parser with:
+
+[source,spec]
+----
+BuildSystem: tree_sitter
+----
+
+The `%prep`, `%conf`, `%generate_buildrequires`, `%build`, `%install`
+and `%check` sections will all be provided for you.
+
+This requires RPM version 4.20 (i.e., Fedora 41) or greater.
+
+=== Defining packages and their contents
+
+Generate `%package` and `%files` sections for the subpackages built from your package:
+
+[source,spec]
+----
+%{tree_sitter -l language-name}
+----
+
+Here, _language-name_ is the human-friendly name(s) of the Language
+parser(s) provided by this package, to be mentioned in the package
+summaries and descriptions.
+
+== Example spec file
+
+[source,spec]
+----
+Name:           tree-sitter-typescript
+Version:        0.21.2
+Release:        %autorelease
+License:        MIT
+URL:            https://github.com/tree-sitter/%{name}
+Source:         %{url}/archive/v%{version}/%{name}-%{version}.tar.gz
+BuildSystem:    tree_sitter
+
+%{tree_sitter -l %{quote:TypeScript and TSX}}
+
+%changelog
+%autochangelog
+----
diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 36f7272..e01f31b 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -3247,5 +3247,6 @@ have specific guidelines written for them, located on their own pages:
 * xref:Rust.adoc[Rust]
 * xref:SugarActivityGuidelines.adoc[Sugar activities]
 * xref:Tcl.adoc[Tcl/Tk extensions]
+* xref:Tree-sitter.adoc[Tree-sitter parsers]
 * xref:Web_Assets.adoc[Web Assets]
 * xref:WordPress_plugin_packaging_guidelines.adoc[WordPress extensions]

From 8193c85b4e9d0912d303223a39bc6fbd0b65999f Mon Sep 17 00:00:00 2001
From: Peter Oliver 
Date: Jan 09 2025 17:21:27 +0000
Subject: [PATCH 211/232] Create relative not absolute symlink to binary in Node.js example


An absolute symlink causes a warning like the following:

```
RPM build warnings:
    absolute symlink: /usr/bin/tape -> /usr/lib/node_modules_20/tape/bin/tape
```

While we’re here, drop the `-f` option.  If the target already exists, something has gone wrong.

---

diff --git a/guidelines/modules/ROOT/pages/Node.js.adoc b/guidelines/modules/ROOT/pages/Node.js.adoc
index 94c87d5..8128e66 100644
--- a/guidelines/modules/ROOT/pages/Node.js.adoc
+++ b/guidelines/modules/ROOT/pages/Node.js.adoc
@@ -349,7 +349,7 @@ cp -pr node_modules node_modules_prod \
 mkdir -p %{buildroot}%{nodejs_sitelib}/tape/bin
 install -p -D -m0755 bin/tape %{buildroot}%{nodejs_sitelib}/tape/bin/tape
 mkdir -p %{buildroot}%{_bindir}
-ln -sf %{nodejs_sitelib}/tape/bin/tape %{buildroot}%{_bindir}/tape
+ln -sr %{nodejs_sitelib}/tape/bin/tape %{buildroot}%{_bindir}/tape
 
 %check
 %{__nodejs} -e 'require("./")'

From b0f7889c3d5be192d57b32e3a87bc7a325f624ea Mon Sep 17 00:00:00 2001
From: Björn Persson 
Date: Jan 09 2025 17:33:12 +0000
Subject: [PATCH 212/232] Documented one-to-many replacement.


---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index e01f31b..279c6d7 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -3021,6 +3021,46 @@ 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.
 
+=== One-to-Many Replacement
+
+Sometimes a package is split into two or more packages
+(either subpackages or separate source packages)
+to make some components optional,
+but users of the optional parts shall be able to upgrade
+without losing the functionality.
+Thus the new packages need to be pulled in
+on upgrade from a version before the split.
+If some are later removed,
+they shall not be pulled in again on further upgrades.
+
+This is achieved by putting an `+Obsoletes:+` tag like above
+in each of the packages that together replace the original package.
+If the name of the original package still exists after the split,
+that package needs to obsolete itself.
+Even if an optional split-out package requires the original package,
+the original package still must obsolete itself.
+Otherwise the split-out package won't be pulled in.
+
+Example: Foo version 3 contains Bar as a non-essential component.
+In version 4, Bar is moved to a subpackage.
+Bar shall not disappear on upgrade.
+
+[source, rpm-spec]
+----
+Name:      foo
+Version:   4
+Release:   1%{?dist}
+Obsoletes: foo < 4
+
+%package bar
+Requires:  foo%{?_isa} = %{version}-%{release}
+Obsoletes: foo < 4
+----
+
+NOTE: Packages pulled in this way are not marked as user-installed by DNF 4,
+so `+dnf autoremove+` will remove them.
+This appears to be fixed in DNF 5.
+
 == Deprecating Packages
 
 A procedure exists for indicating that a package is deprecated

From f80562a44738533e3ec5d3dcc01be333b49dc801 Mon Sep 17 00:00:00 2001
From: Cristian Le 
Date: Jan 16 2025 17:15:57 +0000
Subject: [PATCH 213/232] Add note about `requirements.txt`


---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 27cacb6..a03084d 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1499,6 +1499,8 @@ Multiple comma separated values can be given, for example:
 ----
 %pyproject_buildrequires -e %{toxenv}-unit,%{toxenv}-integration
 ----
+** Additional arguments are treated as paths to `+requirements.txt+` that are
+added on top of these dependencies
 
 [#pyproject_wheel]
 * `+%pyproject_wheel+`

From 116942c6f3069241279e5d248433b1d0d03b4343 Mon Sep 17 00:00:00 2001
From: Frank Dana (FeRD) 
Date: Jan 23 2025 23:10:47 +0000
Subject: [PATCH 214/232] Syntax highlighting for Golang_templates specfile listings


---

diff --git a/guidelines/modules/ROOT/pages/Golang_templates.adoc b/guidelines/modules/ROOT/pages/Golang_templates.adoc
index 7f1a017..d3b4a15 100644
--- a/guidelines/modules/ROOT/pages/Golang_templates.adoc
+++ b/guidelines/modules/ROOT/pages/Golang_templates.adoc
@@ -4,7 +4,7 @@
 == Minimal source package
 
 .spectemplate-go-0-source-minimal.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/spectemplate-go-0-source-minimal.spec[]
 ----
@@ -12,7 +12,7 @@ include::{examplesdir}/golang/spectemplate-go-0-source-minimal.spec[]
 == Full source package
 
 .spectemplate-go-1-source-full.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/spectemplate-go-1-source-full.spec[]
 ----
@@ -20,7 +20,7 @@ include::{examplesdir}/golang/spectemplate-go-1-source-full.spec[]
 == Minimal alternative import path
 
 .spectemplate-go-2-alternative-import-path-minimal.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/spectemplate-go-2-alternative-import-path-minimal.spec[]
 ----
@@ -28,7 +28,7 @@ include::{examplesdir}/golang/spectemplate-go-2-alternative-import-path-minimal.
 == Full alternative import path
 
 .spectemplate-go-3-alternative-import-path-full.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/spectemplate-go-3-alternative-import-path-full.spec[]
 ----
@@ -36,7 +36,7 @@ include::{examplesdir}/golang/spectemplate-go-3-alternative-import-path-full.spe
 == Minimal binary
 
 .spectemplate-go-4-binary-minimal.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/spectemplate-go-4-binary-minimal.spec[]
 ----
@@ -44,7 +44,7 @@ include::{examplesdir}/golang/spectemplate-go-4-binary-minimal.spec[]
 == Full binary
 
 .spectemplate-go-5-binary-full.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/spectemplate-go-5-binary-full.spec[]
 ----
@@ -52,7 +52,7 @@ include::{examplesdir}/golang/spectemplate-go-5-binary-full.spec[]
 == Multi package
 
 .spectemplate-go-6-multi.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/spectemplate-go-6-multi.spec[]
 ----
@@ -60,7 +60,7 @@ include::{examplesdir}/golang/spectemplate-go-6-multi.spec[]
 == Manual package (deprecated)
 
 .spectemplate-go-7-manual.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/spectemplate-go-7-manual.spec[]
 ----

From 4350a99db1483f4ab96abfcbebf55e0b50638270 Mon Sep 17 00:00:00 2001
From: FeRD (Frank Dana) 
Date: Jan 23 2025 23:10:47 +0000
Subject: [PATCH 215/232] Fix all remaining RPMSpec syntax tags


---

diff --git a/guidelines/modules/ROOT/pages/Ansible_collections.adoc b/guidelines/modules/ROOT/pages/Ansible_collections.adoc
index a6d534a..2d3e84e 100644
--- a/guidelines/modules/ROOT/pages/Ansible_collections.adoc
+++ b/guidelines/modules/ROOT/pages/Ansible_collections.adoc
@@ -204,7 +204,7 @@ allowed licenses and determining the `+License:+` field.
 
 == Example Specfile
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 # Only run tests where the dependencies are available
 %if %{defined fedora}
@@ -302,7 +302,7 @@ Here is a short breakdown of exactly what each macro included in
 
 *Usage:*
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 URL:            %{ansible_collection_url NAMESPACE NAME}
 ----
@@ -324,7 +324,7 @@ See the link:#legacy_macros[Legacy Macros] section for more information.
 
 *Usage:*
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %build
 %ansible_collection_build
@@ -338,7 +338,7 @@ This macro simply runs `+ansible-galaxy collection build+`.
 
 *Usage:*
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %install
 %ansible_collection_install
@@ -355,7 +355,7 @@ metadata it previously extracted
 
 *Usage:*
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %check
 %ansible_test_unit
@@ -371,7 +371,7 @@ script runs ansible-test units with the provided arguments.
 
 *Usage:*
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %files -f %{ansible_collection_filelist}
 %doc ...
@@ -397,7 +397,7 @@ Packagers are expected to use `+%ansible_collection_install+` and
 ===== `+%{collection_namepsace}+`
 *Usage:*
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %global collection_namespace NAMESPACE
 ----
@@ -412,7 +412,7 @@ Now, the macros extract the collection namespace from the `galaxy.yml`.
 
 *Usage:*
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %global collection_name NAME
 ----
@@ -427,7 +427,7 @@ Now, the macros extract the collection name from the `galaxy.yml`.
 
 *Usage:*
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %files
 %doc ...
diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc
index 769ca15..c1969d9 100644
--- a/guidelines/modules/ROOT/pages/Golang.adoc
+++ b/guidelines/modules/ROOT/pages/Golang.adoc
@@ -16,7 +16,7 @@ In Golang, packages are referenced by full URLs. Since this URL is
 referenced in several places throughout the rpmspec, set the
 base import path as a global define at the top of the spec file
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %global goipath     github.com/kr/pretty
 ----
@@ -105,7 +105,7 @@ Packages that ship Go code in `+%{goipath}+` should be named
 `+%{goname}-devel+`.
 If your source package is already named `+%{goname}+` then:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %package devel
 […]
@@ -122,7 +122,7 @@ described in the <> section below.
 If your source package is named something other than `+%{goname}+`, you SHOULD
 use:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %package -n %{goname}-devel
 […]
@@ -136,7 +136,7 @@ use:
 And, finally, if you wish to split the project Go code in multiple packages,
 you can compute the corresponding names with:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %global goname1 %gorpmname importpath1
 […]
@@ -171,7 +171,7 @@ changed (but please make sure with upstream).
 The new import path SHOULD be reflected in `+%{goipath}+` and compatibility
 import paths MUST be declared with the `+goaltipaths+` macro:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 # A space-separated list of import paths to simulate.
 %global goaltipaths
@@ -183,7 +183,7 @@ path.
 The packager SHOULD thus request a renaming of his package with a new import
 path and a compatibility import path:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %global goipath     github.com/sirupsen/logrus
 %global goaltipaths github.com/Sirupsen/logrus
@@ -214,7 +214,7 @@ Of course these package MUST NOT be noarch.
 For example we can create the package bbolt that will contain the binary
 of the same name:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %package -n bbolt
 […]
@@ -238,7 +238,7 @@ the release number yourself.
 
 You first specify either a Version, tag or commit in the header.
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 Version:
 %global tag
@@ -301,7 +301,7 @@ These provides are automatically deduced from import paths.
 Binary builds that include these imports will use them in BuildRequires,
 for example:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 BuildRequires: golang(github.com/gorilla/context)
 ----
@@ -347,7 +347,7 @@ BuildRequires:  golang(golang.org/x/crypto/ssh/terminal)
 If automatic buildrequires are available on your build target, you can use
 the `+%go_generate_buildrequires+` macro in `+%generate_buildrequires+`:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %generate_buildrequires
 %go_generate_buildrequires
@@ -443,7 +443,7 @@ Most of the computed variables are both overridable and optional.
 Now we can add the remaining elements of the preamble. First, we can define a
 multiline description block shared between subpackages:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %global common_description %{expand:
 cmux is a generic Go library to multiplex connections based on their payload.
@@ -488,7 +488,7 @@ these should not be provided.
 
 We can declare the usual rpm headers, using the values computed by `+%gometa+`:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 Name:      %{goname}
 # If not set before
@@ -512,7 +512,7 @@ maintenance-intensive discrepancies in the distribution.
 If they are not automatically generated, you can now add the dependencies needed
 for package building and unit testings:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 BuildRequires:  golang(github.com/stretchr/testify/assert)
 BuildRequires:  golang(github.com/stretchr/testify/require)
@@ -525,7 +525,7 @@ See <> on how to get the BuildRequires list manually.
 
 Now add the main package description:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %description
 %{common_description}
@@ -591,7 +591,7 @@ xref:Golang_advanced.adoc#_dealing_with_cyclic_dependencies[Dealing with cyclic 
 
 If BuildRequires generator are supported, you can now add them to your build:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %generate_buildrequires
 %go_generate_buildrequires
@@ -609,7 +609,7 @@ put those in `+cmd+` subdirectories named after the command that will be built,
 which is what we will document here, but it is not a general rule. Sometimes the
 whole `+%goipath+` builds as a single binary.
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 for cmd in cmd/* ; do
   %gobuild -o %{gobuilddir}/bin/$(basename $cmd) %{goipath}/$cmd
@@ -633,7 +633,7 @@ If you only need to install Go devel subpackages without compat, use:
 For binaries, we simply create the `+%{_bindir}+` directory in the buildroot
 and install the commands as executable in it:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 install -m 0755 -vd                     %{buildroot}%{_bindir}
 install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/
@@ -683,7 +683,7 @@ the necessary license and documentation files:
 Binaries are usually shipped in the main package. This package MUST include
 legal files and documentation associated with those binaries.
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %files
 %license LICENSE
@@ -696,7 +696,7 @@ legal files and documentation associated with those binaries.
 === Simple source package
 
 .golang-github-stretchr-testify.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/golang-github-stretchr-testify.spec[]
 ----
@@ -704,7 +704,7 @@ include::{examplesdir}/golang/golang-github-stretchr-testify.spec[]
 === Handling package renames
 
 .golang-github-sirupsen-logrus.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/golang-github-sirupsen-logrus.spec[]
 ----
@@ -712,7 +712,7 @@ include::{examplesdir}/golang/golang-github-sirupsen-logrus.spec[]
 === Simple binary package
 
 .golang-github-boltdb-bolt.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/golang-gopkg-square-jose-2.spec[]
 ----
diff --git a/guidelines/modules/ROOT/pages/Golang_advanced.adoc b/guidelines/modules/ROOT/pages/Golang_advanced.adoc
index 0ce8c79..f9272e9 100644
--- a/guidelines/modules/ROOT/pages/Golang_advanced.adoc
+++ b/guidelines/modules/ROOT/pages/Golang_advanced.adoc
@@ -17,7 +17,7 @@ the following macros in the preamble:
 
 For example, if you have glide files to ship:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %global gosupfiles glide.yaml glide.lock
 ----
@@ -28,7 +28,7 @@ Use `+%godevelheader+` to add specific subpackage declarations. For example, you
 might want to require the main package containing the binaries, or
 Obsoletes/Provides another package in case of renaming.
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %global godevelheader %{expand:
 Requires:
@@ -138,7 +138,7 @@ into a separate devel subpackage to resolve our cyclic dependency graph.
 
 To achieve this, we use multiple `+goipaths+` in the preamble:
 
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 %global goipaths0       cloud.google.com/go
 %global goipathsex0     cloud.google.com/go/compute
@@ -290,7 +290,7 @@ depend separately on `+golang-cloud-google-compute-devel+`.
 Here is the full example:
 
 .golang-cloud-google-go.spec
-[source,RPMSpec]
+[source,rpm-spec]
 ----
 include::{examplesdir}/golang/golang-cloud-google-go.spec[]
 ----

From 839295388b720505a3ae0ca7d50a13890c55026b Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Jan 25 2025 09:29:39 +0000
Subject: [PATCH 216/232] UsersAndGrous: drop outdated list of users and groups


The reader is referred to the authoritative list in setup.rpm instead.
Fixes https://pagure.io/packaging-committee/issue/1431.

---

diff --git a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
index 7bc9fb4..1ea737e 100644
--- a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
+++ b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
@@ -239,71 +239,5 @@ the dynamic allocation section above.
 
 === List of statically allocated UID/GID and corresponding package
 
-,===
-User name,UID,Package,Comments
-
-root,0,https://src.fedoraproject.org/rpms/setup[setup],
-bin,1,https://src.fedoraproject.org/rpms/setup[setup],
-daemon,2,https://src.fedoraproject.org/rpms/setup[setup],
-adm,3,https://src.fedoraproject.org/rpms/setup[setup],
-lp,4,https://src.fedoraproject.org/rpms/setup[setup],
-sync,5,https://src.fedoraproject.org/rpms/setup[setup],
-shutdown,6,https://src.fedoraproject.org/rpms/setup[setup],
-halt,7,https://src.fedoraproject.org/rpms/setup[setup],
-mail,8,https://src.fedoraproject.org/rpms/setup[setup],
-operator,11,https://src.fedoraproject.org/rpms/setup[setup],
-games,12,https://src.fedoraproject.org/rpms/setup[setup],
-ftp,14,https://src.fedoraproject.org/rpms/setup[setup],
-postgres,26,https://src.fedoraproject.org/rpms/postgresql[postgresql],
-rpc,32,https://src.fedoraproject.org/rpms/rpcbind[rpcbind],
-gdm,42,https://src.fedoraproject.org/rpms/gdm[gdm],
-tss,59,https://src.fedoraproject.org/rpms/tpm2-tss[tpm2-tss],
-tcpdump,72,https://src.fedoraproject.org/rpms/tcpdump[tcpdump],
-sshd,74,https://src.fedoraproject.org/rpms/openssh[openssh-server],
-dbus,81,https://src.fedoraproject.org/rpms/dbus[dbus-daemon],
-qemu,107,https://src.fedoraproject.org/rpms/libvirt[libvirt],
-ceph,167,https://src.fedoraproject.org/rpms/ceph[ceph-common],
-nobody,65534,https://src.fedoraproject.org/rpms/setup[setup],
-,===
-
-,===
-Group name,GID,Package,Comments
-
-root,0,https://src.fedoraproject.org/rpms/setup[setup],
-bin,1,https://src.fedoraproject.org/rpms/setup[setup],
-daemon,2,https://src.fedoraproject.org/rpms/setup[setup],
-sys,3,https://src.fedoraproject.org/rpms/setup[setup],
-adm,4,https://src.fedoraproject.org/rpms/setup[setup],
-tty,5,https://src.fedoraproject.org/rpms/setup[setup],
-disk,6,https://src.fedoraproject.org/rpms/setup[setup],
-lp,7,https://src.fedoraproject.org/rpms/setup[setup],
-mem,8,https://src.fedoraproject.org/rpms/setup[setup],
-kmem,9,https://src.fedoraproject.org/rpms/setup[setup],
-wheel,10,https://src.fedoraproject.org/rpms/setup[setup],
-cdrom,11,https://src.fedoraproject.org/rpms/setup[setup],
-mail,12,https://src.fedoraproject.org/rpms/setup[setup],
-man,15,https://src.fedoraproject.org/rpms/setup[setup],
-dialout,18,https://src.fedoraproject.org/rpms/setup[setup],
-floppy,19,https://src.fedoraproject.org/rpms/setup[setup],
-games,20,https://src.fedoraproject.org/rpms/setup[setup],
-utmp,22,https://src.fedoraproject.org/rpms/libutempter[libutempter],
-postgres,26,https://src.fedoraproject.org/rpms/postgresql[postgresql],
-rpc,32,https://src.fedoraproject.org/rpms/rpcbind[rpcbind],
-tape,33,https://src.fedoraproject.org/rpms/setup[setup],
-utempter,35,https://src.fedoraproject.org/rpms/libutempter[libutempter],
-kvm,36,https://src.fedoraproject.org/rpms/libvirt[libvirt],
-video,39,https://src.fedoraproject.org/rpms/setup[setup],
-gdm,42,https://src.fedoraproject.org/rpms/gdm[gdm],
-ftp,50,https://src.fedoraproject.org/rpms/setup[setup],
-lock,54,https://src.fedoraproject.org/rpms/setup[setup],
-tss,59,https://src.fedoraproject.org/rpms/tpm2-tss[tpm2-tss],
-audio,63,https://src.fedoraproject.org/rpms/setup[setup],
-tcpdump,72,https://src.fedoraproject.org/rpms/tcpdump[tcpdump],
-sshd,74,https://src.fedoraproject.org/rpms/openssh[openssh-server],
-dbus,81,https://src.fedoraproject.org/rpms/dbus[dbus-daemon],
-users,100,https://src.fedoraproject.org/rpms/setup[setup],
-qemu,107,https://src.fedoraproject.org/rpms/libvirt[libvirt],
-mock,135,https://src.fedoraproject.org/rpms/mock[mock],
-ceph,167,https://src.fedoraproject.org/rpms/ceph[ceph-common],
-nobody,65534,https://src.fedoraproject.org/rpms/setup[setup],
-,===
+The list of statically allocated accounts is maintained in the `setup` package:
+https://src.fedoraproject.org/rpms/setup/blob/rawhide/f/uidgid[uidgid].

From b488336acf856876f69b4d6c06c055155fd8506a Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Feb 13 2025 17:12:05 +0000
Subject: [PATCH 217/232] review: drop obsolete recommendation for file path dependencies


In 8ee8319f86af93a057ad6ad73c9b1addf8df5574 we forbid file path dependencies
outside of /usr/*bin and /etc. f80e2dc64197d88821fdaae53f297f4f4315cd97
simplified that to just /usr/bin and /etc. The review checklist says earlier
that Packaging Guidelines must be followed, so this recommendation is now fully
duplicate (and misleading).

---

diff --git a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
index a75255f..0988b09 100644
--- a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
+++ b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
@@ -55,7 +55,6 @@ There are many many things to check for a review. This list is provided to assis
 * [[sane-scriplets]] *SHOULD*: If scriptlets are used, those scriptlets must be sane. This is vague, and left up to the reviewers judgement to determine sanity. See xref:index.adoc#_scriptlets[Packaging Guidelines: Scriptlets] +
 * [[subpackage-versioned-requires]] *SHOULD*: Usually, subpackages other than devel should require the base package using a fully versioned dependency. See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package] +
 * [[pkgconfig-in-devel]] *SHOULD*: The placement of pkgconfig(.pc) files depends on their usecase, and this is usually for development purposes, so should be placed in a -devel pkg. A reasonable exception is that the main pkg itself is a devel tool not installed in a user runtime, e.g. gcc or gdb. See xref:index.adoc#_pkgconfig_files_foo_pc[Packaging Guidelines: Pkgconfig Files] +
-* [[file-requires]] *SHOULD*: If the package has file dependencies outside of /etc, /bin, /sbin, /usr/bin, or /usr/sbin consider requiring the package which provides the file instead of the file itself. See xref:index.adoc#_file_and_directory_dependencies[Packaging Guidelines: File and Directory Dependencies] +
 * [[man-pages]] *SHOULD*: your package should contain man pages for binaries/scripts. If it doesn't, work with upstream to add them where they make sense. See xref:index.adoc#_manpages[Packaging Guidelines: Manpages] +
 
 == A note on dependencies

From 1e70fd534bc97ca15ab4a80eed3b420d69478ad1 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Feb 13 2025 17:15:51 +0000
Subject: [PATCH 218/232] Drop obsolete chunk of text explaining scriptlet usage


The scriptlets were removed in 6d066acbb16452e1befc2f384d2f14bab9f54361:
'UsersAndGroups: Use %sysusers_create_compat macro', 2020-12-10.
That explanation was left behind, but it doesn't make sense without
the scriptlets, and the variables like USERNAME/GROUPNAME/HOMEDIR
are not used anywhere either.

---

diff --git a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
index 1ea737e..2461f54 100644
--- a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
+++ b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
@@ -192,51 +192,6 @@ To create users and groups in packages with an allocated UID/GID, add a sysusers
 that specifies the ID for the given user and/or group and follow the same steps as in
 the dynamic allocation section above.
 
-=== Values given to useradd and groupadd
-
-* `+HOMEDIR+` should usually be a directory created and owned by the package,
-  with appropriately restrictive permissions.
-  One good choice for the location of the directory
-  is the package's data directory in case it has one.
-* `+USERNAME+` and `+GROUPNAME+` are the symbolic names used by your package.
-  Be aware that all code in the package should use these names,
-  not the UID or GID.
-  If this is not possible, please mention it within the ticket
-  so that the FPC can see if this is a different type of problem than we usually encounter.
-* `+ALLOCATED_UID+` and `+ALLOCATED_GID+` are the UID and GID
-  that FPC tells you has been allocated for use by your package.
-* User accounts created by packages are rarely used for interactive logons,
-  and should thus generally use `+/sbin/nologin+` as the user's shell.
-
-=== Rationale for some of the implementation choices
-
-* We run `+getent+` before `+groupadd+` and `+useradd+`
-  to check whether the user/group we're about to create
-  already exists and skip the creation if they do.
-  This is what allows the local system administrators
-  to customize the users and groups beforehand
-  in case they wish to get a predefined static UID/GID mapping for those users.
-  Similarly, we verify whether the ID values
-  allocated in the "setup" package
-  aren't already allocated by the local system administrators.
-* We want to invoke `+groupadd+` explicitly
-  instead of relying on `+useradd+` to create the group for us.
-  This is because `+useradd+` alone would fail
-  if the group it tries to create already existed.
-* We run the `+groupadd+`/`+useradd+` always
-  -- both on initial installs and upgrades -- in `+%pre+`.
-  This is made possible by the `+getent+` checks above,
-  and should fix things up if the user/group has disappeared
-  after the package to be upgraded was initially installed
-  (just like file permissions get reset on upgrades etc).
-* The `+exit 0+` at the end will result in the `+%pre+` scriptlet
-  passing through even if the user/group creation fails for some reason.
-  This is suboptimal but has less potential for system wide breakage
-  than allowing it to fail.
-  If the user/group aren't available
-  at the time the package's payload is unpacked,
-  rpm will fall back to setting those files owned by root.
-
 === List of statically allocated UID/GID and corresponding package
 
 The list of statically allocated accounts is maintained in the `setup` package:

From b85d6de4858b9a826c69ca531d1c2ec2813f141e Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek 
Date: Feb 13 2025 17:15:51 +0000
Subject: [PATCH 219/232] UsersAndGroups: switch to sysusers.d for F42+


https://fedoraproject.org/wiki/Changes/RPMSuportForSystemdSysusers simplifies
the creation of system users and groups: the package only has to provide a
sysusers.d config file as part of the payload and rpm will implement this
configuration before the package is installed.

Before this patch, %sysusers_create_compat was the only documented way to
create users and groups. The traditional approach with getent/useradd/groupadd
was dropped a few years ago (6d066acbb16452e1befc2f384d2f14bab9f54361:
'UsersAndGroups: Use %sysusers_create_compat macro', 2020-12-10). So what this
patch effectively does is to drop the requirement for the sysusers file to be a
separate Source and to call %sysusers_create_compat in F42+.

Some packages still use the old old approach of manual getent/useradd/groupadd
scriptlets. This hasn't been documented for the last four years. We generally
do not require packages to update when packaging guidelines are changed, so
those packages are "fine", but we want them to switch to provide sysusers
files.

The transition plan is:
- spec files only for F42+ only need to provide a sysusers file
- spec files for F42- or compatible with both are recommended to use
  the previously-described approach with %sysusers_create_compat.
- spec files which use the old old approach can switch to
  %sysusers_create_compat (if a single spec file is to be used in
  multiple branches), or just switch to the new approach in the
  rawhide branch.

While packages that create users via scriptlets will continue to work, we want
to switch all packages to the new scheme. We have dependencies between packages
that create and use system accounts. Rpm will automatically create dependencies
on user and group accounts for files that are the package payload. Currently
those dependencies are weak (Recommends), and the first attempt to switch to
strong dependencies caused installability issues. But once we have sysusers.d
definitions for all users/groups used by packages, we can switch those
dependencies to strong (Requires). Thus we need to provide full sysusers.d
coverage of users to allow robust sorting of packages during install.

Once this is merged, I'll change the %sysusers_create_compat and
%sysusers_requires_compat to be empty.

---

diff --git a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
index 2461f54..6dc7b87 100644
--- a/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
+++ b/guidelines/modules/ROOT/pages/UsersAndGroups.adoc
@@ -135,15 +135,35 @@ In these cases, apply only the `+groupadd+` parts of the below recipes.
 
 === Dynamic allocation
 
-To create users and groups in packages using dynamic allocation, do the following:
+To create system users and groups in packages using dynamic allocation,
+the package shall install a `sysusers.d/.conf` file.
+If it is not provided by the upstream,
+the maintainer *should* provide one either as a separate `+Source+`
+or otherwise create it during the package build.
 
-Create a `.sysusers` file with the user definition and add it to the specfile as a source.
-For example for the `munge` package, this file contains:
+For example for the `munge` package, this file may contain:
 ```
 #Type Name   ID  GECOS                        Home directory  Shell
-u     munge  -   "Runs Uid 'N' Gid Emporium"  /run/munge      /sbin/nologin
+u     munge  -   "Runs Uid 'N' Gid Emporium"  /run/munge      -
 ```
 
+(The shell is not specified, so the default of `nologin` shall be used.)
+
+When a package with a sysusers.d file is built,
+a virtual `Provides` for `+user(…)+` and `+group(…)+` is automatically generated.
+When `rpm` installs a package with such `Provides`,
+it shall create the users and groups according to those definitions.
+
+Use `+rpm -q --qf='[%{SYSUSERS}\n]' …+` to view the definitions of users and groups
+decoded from the virtual `Provides`.
+
+=== Creation of users and groups with scriptlets
+
+For Fedora releases before 42,
+manual creation of users and groups is required.
+
+The sysusers file must be a separate `Source` file.
+
 In the specfile, add a BuildRequires for systemd-rpm-macros, install the sysusers file,
  use the `%sysusers_create_compat` macro to consume it in the `%pre` section
 (in this example the sysusers config file is `Source3` of the specfile), and the
@@ -168,6 +188,11 @@ install -p -D -m 0644 %{SOURCE3} %{buildroot}%{_sysusersdir}/munge.conf
 [...]
 ```
 
+This form is compatible with Fedora 42+,
+and the same spec file may be used for older and newer releases.
+In F42+, the `%sysusers_requires_compat` and `%sysusers_create_compat`
+macros will evaluate as empty.
+
 === Soft static allocation
 
 To allocate a UID and/or GID,
@@ -188,9 +213,22 @@ or the one used by other distributions).
 We will try to accommodate on a first-come-first serve basis
 if the UID/GID is available from within the Fedora system UID/GID range.
 
-To create users and groups in packages with an allocated UID/GID, add a sysusers file
-that specifies the ID for the given user and/or group and follow the same steps as in
-the dynamic allocation section above.
+To create users and groups in packages with an allocated UID/GID,
+follow the steps in the dynamic allocation section above,
+but add the UID or GID in the `ID` column.
+
+=== Sharing of users or groups between packages
+
+The package that provides the definition of the user or group account
+has automatically-generated virtual `Provides`.
+Other packages which want to ensure that users or groups exist,
+*may* use `Requires` on the user or group names.
+
+For example, `+Requires: user(mock)+` or `+Requires: group(man)+`.
+
+`rpm` automatically creates weak dependencies (`Recommends`)
+for packages which contain files owned by users and groups.
+In the future, those depencencies will be changed to `Requires`.
 
 === List of statically allocated UID/GID and corresponding package
 

From f151ef77212aa214fdccb117a46164d2a4236679 Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Feb 25 2025 09:36:00 +0000
Subject: [PATCH 220/232] Document %pyproject_save_files -M


---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index a03084d..fe651a7 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1547,6 +1547,12 @@ to avoid accidentally losing the file in a future version.
 When the `%license` file is manually listed in `%files`,
 packagers can use this flag to ensure future compatibility
 in case the `-l` behavior eventually becomes a default.
+** `+-M+`: Do not list any modules.
+When the package has no Python modules in it
+or when you need to list the modules in `+%files+` manually,
+this option allows to save just the non-module files
+(such as the `+.dist-info+` metadata directory).
+This option cannot be combined with `MODNAME`s.
 
 [#pyproject_files]
 * `+%{pyproject_files}+`

From 939a978bb4610b09cbf45d8f1f2a0dee97c9ef47 Mon Sep 17 00:00:00 2001
From: Marian Koncek 
Date: Mar 06 2025 17:07:41 +0000
Subject: [PATCH 221/232] Java: update BuildRequires to mention versioned Java bindings


---

diff --git a/guidelines/modules/ROOT/pages/Java.adoc b/guidelines/modules/ROOT/pages/Java.adoc
index d6d8604..bf13589 100644
--- a/guidelines/modules/ROOT/pages/Java.adoc
+++ b/guidelines/modules/ROOT/pages/Java.adoc
@@ -78,11 +78,10 @@ the split packaging SHOULD be preferred.
 
 == BuildRequires and Requires
 
-Java packages MUST BuildRequire their respective build system:
+Java packages MUST BuildRequire their respective build system (or a versioned binding thereof):
 
-* `+BuildRequires: maven-local+` for packages built with Maven
-* `+BuildRequires: ant+` for packages built with ant
-* `+BuildRequires: java-devel+` for packages built with javac
+* `+BuildRequires: maven-local+` or `+maven-local-openjdk${N}+` for packages built with Maven
+* `+BuildRequires: javapackages-local+` or `+javapackages-local-openjdk${N}+` for packages not built with Maven
 
 Java applications or their dependencies MUST have `+Requires+` on:
 

From bafd389e405043f20d6a71b0d26468503c173c75 Mon Sep 17 00:00:00 2001
From: Marian Koncek 
Date: Mar 06 2025 17:07:41 +0000
Subject: [PATCH 222/232] Java: update guidelines related to runtime Requires


---

diff --git a/guidelines/modules/ROOT/pages/Java.adoc b/guidelines/modules/ROOT/pages/Java.adoc
index bf13589..2d4a7d4 100644
--- a/guidelines/modules/ROOT/pages/Java.adoc
+++ b/guidelines/modules/ROOT/pages/Java.adoc
@@ -83,14 +83,11 @@ Java packages MUST BuildRequire their respective build system (or a versioned bi
 * `+BuildRequires: maven-local+` or `+maven-local-openjdk${N}+` for packages built with Maven
 * `+BuildRequires: javapackages-local+` or `+javapackages-local-openjdk${N}+` for packages not built with Maven
 
-Java applications or their dependencies MUST have `+Requires+` on:
+Java applications SHOULD have `+Requires+` on an appropriate Java runtime package:
 
-* `+java-headless+` or `+java-headless >= 1:minimal_required_version+`
-* `+javapackages-filesystem+`
-
-If a `+java-headless+` requirement is insufficient,
-then the package MUST have `+Requires+` for
-`+java+` or `+java >= 1:minimal_required_version+`.
+* `+java-headless+` for applications not requiring graphical interface
+* `+java+` for applications requiring graphical interface
+* `+java-devel+` for applications requiring additional content related to Java development
 
 == Javadoc installation
 

From cddb3f7b1bb595bc17d29c693be3135172a6c032 Mon Sep 17 00:00:00 2001
From: Tim Landscheidt 
Date: Mar 24 2025 15:09:26 +0000
Subject: [PATCH 223/232] Fix typo


---

diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 279c6d7..04e4abf 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -1175,7 +1175,7 @@ index 5c77064c03..efcd53a61c 100644
 ----
 
 When the package is built, an appropriate changelog entry will be generated.
-It can be previewed with `rpmautospec generate-chagengelog`:
+It can be previewed with `rpmautospec generate-changelog`:
 
 [console]
 ----

From c13c5d737d24c3577f51fd3cc0f4adc51c6f7e9e Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Mar 28 2025 11:05:53 +0000
Subject: [PATCH 224/232] RPM_Source_Dir: Semantic newlines, no other changes


---

diff --git a/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc b/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc
index 07533e3..40b8a3a 100644
--- a/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc
+++ b/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc
@@ -1,8 +1,14 @@
 = $RPM_SOURCE_DIR or %\{_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.
+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.
 
-This is done to ensure that Fedora SRPMS are properly generated. If a Source# item is renamed, a spec which refers to its old name may succeed locally (because the file is still in %\{_sourcedir} along with the new file), but the proper file will not be included in the SRPM.
+This is done to ensure that Fedora SRPMS are properly generated.
+If a Source# item is renamed,
+a spec which refers to its old name may succeed locally
+(because the file is still in %\{_sourcedir} along with the new file),
+but the proper file will not be included in the SRPM.
 
 *Incorrect Use:*
 
@@ -34,7 +40,9 @@ sed -e "s/@PHP_APIVER@/%{apiver}/;s/@PHP_ZENDVER@/%{zendver}/;s/@PHP_PDOVER@/%{p
 
 === Exceptions
 
-When there is an available list of supplementary source files, it is permissible to use this list in conjunction with %\{sourcedir} to simplify operations on those supplementary source files.
+When there is an available list of supplementary source files,
+it is permissible to use this list in conjunction with %\{sourcedir}
+to simplify operations on those supplementary source files.
 
 An example of this from the kde-l10n package:
 
@@ -45,4 +53,7 @@ for i in $(cat %{SOURCE1000}) ; do
 done
 ....
 
-where Source1000: subdirs-kde-l10n is a list provided by upstream of all the languages supported, and there are ~50 SourceN: tags, which can vary from version from version, but match the languages listed in Source1000, for the tarballs provided by upstream.
+where Source1000: subdirs-kde-l10n is a list provided by upstream of all the languages supported,
+and there are ~50 SourceN: tags, which can vary from version from version,
+but match the languages listed in Source1000,
+for the tarballs provided by upstream.

From 376306077df1f534d94090e6c37ab73a5e9f92b7 Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Mar 28 2025 11:07:10 +0000
Subject: [PATCH 225/232] RPM_Source_Dir: Fix macro name


---

diff --git a/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc b/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc
index 40b8a3a..fe30f39 100644
--- a/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc
+++ b/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc
@@ -2,7 +2,7 @@
 
 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.
+and must not use $RPM_SOURCE_DIR or %\{_sourcedir} to refer to those files.
 
 This is done to ensure that Fedora SRPMS are properly generated.
 If a Source# item is renamed,
@@ -41,7 +41,7 @@ sed -e "s/@PHP_APIVER@/%{apiver}/;s/@PHP_ZENDVER@/%{zendver}/;s/@PHP_PDOVER@/%{p
 === Exceptions
 
 When there is an available list of supplementary source files,
-it is permissible to use this list in conjunction with %\{sourcedir}
+it is permissible to use this list in conjunction with %\{_sourcedir}
 to simplify operations on those supplementary source files.
 
 An example of this from the kde-l10n package:

From 80b5cd13a8d4d75fe8cc55924e758883f321b56f Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Mar 28 2025 11:11:41 +0000
Subject: [PATCH 226/232] RPM_Source_Dir: Formatting


---

diff --git a/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc b/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc
index fe30f39..d8d28ea 100644
--- a/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc
+++ b/guidelines/modules/ROOT/pages/RPM_Source_Dir.adoc
@@ -1,13 +1,13 @@
-= $RPM_SOURCE_DIR or %\{_sourcedir}
+= `+$RPM_SOURCE_DIR+` or `+%{_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.
+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.
 
 This is done to ensure that Fedora SRPMS are properly generated.
-If a Source# item is renamed,
+If a `+Source#+` item is renamed,
 a spec which refers to its old name may succeed locally
-(because the file is still in %\{_sourcedir} along with the new file),
+(because the file is still in `+%{_sourcedir}+` along with the new file),
 but the proper file will not be included in the SRPM.
 
 *Incorrect Use:*
@@ -41,7 +41,7 @@ sed -e "s/@PHP_APIVER@/%{apiver}/;s/@PHP_ZENDVER@/%{zendver}/;s/@PHP_PDOVER@/%{p
 === Exceptions
 
 When there is an available list of supplementary source files,
-it is permissible to use this list in conjunction with %\{_sourcedir}
+it is permissible to use this list in conjunction with `+%{_sourcedir}+`
 to simplify operations on those supplementary source files.
 
 An example of this from the kde-l10n package:
@@ -53,7 +53,7 @@ for i in $(cat %{SOURCE1000}) ; do
 done
 ....
 
-where Source1000: subdirs-kde-l10n is a list provided by upstream of all the languages supported,
-and there are ~50 SourceN: tags, which can vary from version from version,
-but match the languages listed in Source1000,
+where `+Source1000: subdirs-kde-l10n+` is a list provided by upstream of all the languages supported,
+and there are ~50 `+SourceN:+` tags, which can vary from version from version,
+but match the languages listed in `+Source1000+`,
 for the tarballs provided by upstream.

From 224d8554c53a3c2c0de1ed56c380dde1ec8c96e2 Mon Sep 17 00:00:00 2001
From: Miro Hrončok 
Date: Mar 28 2025 21:44:48 +0000
Subject: [PATCH 227/232] Get rid of all %patchN usage


Fixes https://pagure.io/packaging-committee/issue/1442

---

diff --git a/guidelines/modules/ROOT/pages/Python_Appendix.adoc b/guidelines/modules/ROOT/pages/Python_Appendix.adoc
index 73ed4ba..ac1b8e3 100644
--- a/guidelines/modules/ROOT/pages/Python_Appendix.adoc
+++ b/guidelines/modules/ROOT/pages/Python_Appendix.adoc
@@ -123,10 +123,10 @@ Some things to watch out for:
 
 ....
 %prep
-%setup -qc
+%autosetup -N -c
 mv %{srcname}-%{version} python2
 pushd python2
-%patch0 -p1 -b .testfix
+%autopatch -p1
 
 find -name '*.txt' | xargs chmod -x
 # copy common doc files to top dir
diff --git a/guidelines/modules/ROOT/pages/Ruby.adoc b/guidelines/modules/ROOT/pages/Ruby.adoc
index 4d15aa1..c1ddbc3 100644
--- a/guidelines/modules/ROOT/pages/Ruby.adoc
+++ b/guidelines/modules/ROOT/pages/Ruby.adoc
@@ -283,11 +283,9 @@ A sample spec for building gems would look like this:
 
 ....
 %prep
-%setup -q -n  %{gem_name}-%{version}
+%autosetup -p1 -n  %{gem_name}-%{version}
 
 # Modify the gemspec if necessary
-# Also apply patches to code if necessary
-%patch0 -p1
 
 %build
 # Create the gem as gem install only works on a gem file
diff --git a/guidelines/modules/ROOT/pages/SourceURL.adoc b/guidelines/modules/ROOT/pages/SourceURL.adoc
index 7b3ea90..28903e8 100644
--- a/guidelines/modules/ROOT/pages/SourceURL.adoc
+++ b/guidelines/modules/ROOT/pages/SourceURL.adoc
@@ -319,12 +319,13 @@ Patch1: oldpatch.patch
 Patch2: ngpatch.patch
 ...
 %prep
+%autosetup -N
 ...
 %if 0%{?fedora} < 35
 tar xf %{SOURCE1}
-%patch1 -p1
+%patch 1 -p1
 %else
 tar xf %{SOURCE2}
-%patch2 -p1
+%patch 2 -p1
 %endif
 ```
diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 04e4abf..4eb42fa 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -494,7 +494,7 @@ from being used to apply patches
 when some of those patches apply only to certain architectures.
 The best solution is to write patches
 which simply work on all architectures.
-If that is not possible, then simply use `+%setup+`
+If that is not possible, then simply use `+%autosetup -N+`
 and to use the `+%patch+` macro to apply each patch
 using `+%ifarch+` or `+%ifnarch+` as appropriate.
 For example:
@@ -502,9 +502,9 @@ For example:
 [source, rpm-spec]
 ----
 %prep
-%setup -q
+%autosetup -N
 %ifarch s390x
-%patch0 -p1
+%patch 0 -p1
 %endif
 ----
 

From 786e56a8441d2a3d41a2d7089ac87fdaede80fca Mon Sep 17 00:00:00 2001
From: Tim Landscheidt 
Date: Apr 02 2025 23:08:30 +0000
Subject: [PATCH 228/232] Fix formatting in Alternatives


---

diff --git a/guidelines/modules/ROOT/pages/Alternatives.adoc b/guidelines/modules/ROOT/pages/Alternatives.adoc
index f1ec3d5..31a3a87 100644
--- a/guidelines/modules/ROOT/pages/Alternatives.adoc
+++ b/guidelines/modules/ROOT/pages/Alternatives.adoc
@@ -136,7 +136,7 @@ touch %{buildroot}%{_mandir}/man8/sendmail.8
 
 %postun
 if [ "$1" -ge "1" ]; then
-    if [ "`+readlink %{_sysconfdir}/alternatives/mta+`" == "%{_bindir}/sendmail.sendmail" ]; then
+    if [ "`readlink %{_sysconfdir}/alternatives/mta`" == "%{_bindir}/sendmail.sendmail" ]; then
         %{_bindir}/alternatives --set mta %{_bindir}/sendmail.sendmail
     fi
 fi

From 0e6ca4261d3bb1aec6c8cb49c705ef5b06dd59e6 Mon Sep 17 00:00:00 2001
From: James Antill 
Date: Apr 10 2025 16:12:25 +0000
Subject: [PATCH 229/232] Merge #1448 `Get rid of all %patchN usage`


---

diff --git a/guidelines/modules/ROOT/pages/Python_Appendix.adoc b/guidelines/modules/ROOT/pages/Python_Appendix.adoc
index 73ed4ba..ac1b8e3 100644
--- a/guidelines/modules/ROOT/pages/Python_Appendix.adoc
+++ b/guidelines/modules/ROOT/pages/Python_Appendix.adoc
@@ -123,10 +123,10 @@ Some things to watch out for:
 
 ....
 %prep
-%setup -qc
+%autosetup -N -c
 mv %{srcname}-%{version} python2
 pushd python2
-%patch0 -p1 -b .testfix
+%autopatch -p1
 
 find -name '*.txt' | xargs chmod -x
 # copy common doc files to top dir
diff --git a/guidelines/modules/ROOT/pages/Ruby.adoc b/guidelines/modules/ROOT/pages/Ruby.adoc
index 4d15aa1..c1ddbc3 100644
--- a/guidelines/modules/ROOT/pages/Ruby.adoc
+++ b/guidelines/modules/ROOT/pages/Ruby.adoc
@@ -283,11 +283,9 @@ A sample spec for building gems would look like this:
 
 ....
 %prep
-%setup -q -n  %{gem_name}-%{version}
+%autosetup -p1 -n  %{gem_name}-%{version}
 
 # Modify the gemspec if necessary
-# Also apply patches to code if necessary
-%patch0 -p1
 
 %build
 # Create the gem as gem install only works on a gem file
diff --git a/guidelines/modules/ROOT/pages/SourceURL.adoc b/guidelines/modules/ROOT/pages/SourceURL.adoc
index 7b3ea90..28903e8 100644
--- a/guidelines/modules/ROOT/pages/SourceURL.adoc
+++ b/guidelines/modules/ROOT/pages/SourceURL.adoc
@@ -319,12 +319,13 @@ Patch1: oldpatch.patch
 Patch2: ngpatch.patch
 ...
 %prep
+%autosetup -N
 ...
 %if 0%{?fedora} < 35
 tar xf %{SOURCE1}
-%patch1 -p1
+%patch 1 -p1
 %else
 tar xf %{SOURCE2}
-%patch2 -p1
+%patch 2 -p1
 %endif
 ```
diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc
index 04e4abf..4eb42fa 100644
--- a/guidelines/modules/ROOT/pages/index.adoc
+++ b/guidelines/modules/ROOT/pages/index.adoc
@@ -494,7 +494,7 @@ from being used to apply patches
 when some of those patches apply only to certain architectures.
 The best solution is to write patches
 which simply work on all architectures.
-If that is not possible, then simply use `+%setup+`
+If that is not possible, then simply use `+%autosetup -N+`
 and to use the `+%patch+` macro to apply each patch
 using `+%ifarch+` or `+%ifnarch+` as appropriate.
 For example:
@@ -502,9 +502,9 @@ For example:
 [source, rpm-spec]
 ----
 %prep
-%setup -q
+%autosetup -N
 %ifarch s390x
-%patch0 -p1
+%patch 0 -p1
 %endif
 ----
 

From a709c6f6e141fc842c5aec8a60f7fa0061c563b6 Mon Sep 17 00:00:00 2001
From: Pavol Žáčik 
Date: Apr 30 2025 10:40:23 +0000
Subject: [PATCH 230/232] Rust: Update rust2rpm examples to use --path


Paths are no longer accepted as positional arguments.

---

diff --git a/guidelines/modules/ROOT/pages/Rust.adoc b/guidelines/modules/ROOT/pages/Rust.adoc
index 9e43ae4..337d343 100644
--- a/guidelines/modules/ROOT/pages/Rust.adoc
+++ b/guidelines/modules/ROOT/pages/Rust.adoc
@@ -770,7 +770,7 @@ but _not_ published on https://crates.io[crates.io].
 
 https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
 has basic support for generating spec files for this type of package
-by running `rust2rpm path/to/Cargo.toml` in unpacked upstream sources.
+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}`,
 i.e. they cannot ship `-devel` subpackages
@@ -812,7 +812,7 @@ but not published on https://crates.io[crates.io].
 
 https://pagure.io/fedora-rust/rust2rpm[rust2rpm]
 has basic support for generating spec files for this type of package
-by running `rust2rpm path/to/Cargo.toml` in unpacked upstream sources,
+by running `rust2rpm --path path/to/Cargo.toml` in unpacked upstream sources,
 (where `./Cargo.toml` must be the path to the "workspace root",
 i.e. the `Cargo.toml` file that contains the `[workspace]` table).
 

From 961a700b107383bd09ea3d5ae43b1d84bf6da9fa Mon Sep 17 00:00:00 2001
From: Fabio Valentini 
Date: May 01 2025 16:26:07 +0000
Subject: [PATCH 231/232] ReviewGuidelines: SemBR treatment and cleaned up formatting


---

diff --git a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
index 0988b09..5de7e3e 100644
--- a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
+++ b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
@@ -1,69 +1,260 @@
 = Package Review Guidelines
 
-This is a set of guidelines for Package Reviews. Note that a complete list of things to check for would be impossible, but every attempt has been made to make this document as comprehensive as possible. Reviewers and contributors (packagers) should use their best judgement whenever items are unclear, and if in doubt, ask on the https://lists.fedoraproject.org/admin/lists/packaging.lists.fedoraproject.org/[Fedora packaging list] .
+This is a set of guidelines for Package Reviews.
+Note that a complete list of things to check for would be impossible,
+but every attempt has been made
+to make this document as comprehensive as possible.
+Reviewers and contributors (packagers)
+should use their best judgement
+whenever items are unclear,
+and if in doubt,
+ask on the https://lists.fedoraproject.org/admin/lists/packaging.lists.fedoraproject.org/[Fedora packaging list] .
 
 == Package Review Process
 
-Contributors and reviewers MUST follow the https://docs.fedoraproject.org/en-US/package-maintainers/Package_Review_Process/[Package Review Process], with the following exceptions:
+Contributors and reviewers
+MUST follow the https://docs.fedoraproject.org/en-US/package-maintainers/Package_Review_Process/[Package Review Process],
+with the following exceptions:
 
-* FPC grants an explicit exemption from the process, as indicated https://fedoraproject.org/wiki/Packaging_Committee#Review_Process_Exemption_Procedure[here].
-* The package is being created so that multiple versions of the same package can coexist in the distribution (or coexist between EPEL and RHEL). The package MUST be properly named according to the xref:Naming.adoc#_multiple_packages_with_the_same_base_name[naming guidelines] and MUST NOT conflict with all other versions of the same package.
-* The package exists in both Fedora and RHEL, but the packager wants to ship it in EPEL under an alternative name (as required by https://fedoraproject.org/wiki/EPEL/GuidelinesAndPolicies#Policy[EPEL policy]) to provide a subpackage that exists in Fedora but does not exist (or is not shipped) in RHEL.
+* FPC grants an explicit exemption from the process,
+  as indicated https://fedoraproject.org/wiki/Packaging_Committee#Review_Process_Exemption_Procedure[here].
+* The package is being created
+  so that multiple versions of the same package can coexist in the distribution
+  (or coexist between EPEL and RHEL).
+  The package MUST be properly named
+  according to the xref:Naming.adoc#_multiple_packages_with_the_same_base_name[naming guidelines]
+  and MUST NOT conflict with all other versions of the same package.
+* The package exists in both Fedora and RHEL,
+  but the packager wants to ship it in EPEL
+  under an alternative name
+  (as required by https://fedoraproject.org/wiki/EPEL/GuidelinesAndPolicies#Policy[EPEL policy])
+  to provide a subpackage that exists in Fedora
+  but does not exist (or is not shipped) in RHEL.
 
 == Things To Check On Review
 
-There are many many things to check for a review. This list is provided to assist new reviewers in identifying areas that they should look for, but is by no means complete. Reviewers should use their own good judgement when reviewing packages. The items listed fall into two categories: *SHOULD* and *MUST*.
+There are many many things to check for a review.
+This list is provided to assist new reviewers
+in identifying areas that they should look for,
+but is by no means complete.
+Reviewers should use their own good judgement
+when reviewing packages.
+The items listed fall into two categories:
+*SHOULD* and *MUST*.
 
-* [[rpmlint]]*MUST*: rpmlint must be run on the source rpm and all binary rpms the build produces. The output should be posted in the review. See xref:index.adoc#_use_rpmlint[Packaging Guidelines: Use rpmlint] +
-* [[naming]] *MUST*: The package must be named according to the xref:Naming.adoc[Package Naming Guidelines] . +
-* [[spec-fie-name]] *MUST*: The spec file name must match the base package `+%{name}+`, in the format `+%{name}.spec+` unless your package has an exemption. See xref:index.adoc#_spec_file_naming[Packaging Guidelines: Spec File Naming] . +
-* [[packaging-guidelines]] *MUST*: The package must meet the xref:index.adoc[Packaging Guidelines] . +
-* [[approved-license]] *MUST*: The package must be licensed with a Fedora approved license and meet the xref:LicensingGuidelines.adoc[Licensing Guidelines] . +
-* [[license-field]] *MUST*: The License field in the package spec file must match the actual license. See xref:LicensingGuidelines.adoc#_valid_license_short_names[Licensing Guidelines: Valid License Short Names] +
-* [[license-file]] *MUST*: If (and only if) the source package includes the text of the license(s) in its own file, then that file, containing the text of the license(s) for the package must be included in `+%license+`. See xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text] +
-* [[spec-in-american-english]] *MUST*: The spec file must be written in American English. See xref:index.adoc#_summary_and_description[Packaging Guidelines: Summary and description] +
-* [[legible-spec]] *MUST*: The spec file for the package *MUST* be legible. See xref:index.adoc#_spec_legibility[Packaging Guidelines: Spec Legibility] +
-* [[build-sources]] *MUST*: The sources used to build the package must match the upstream source, as provided in the spec URL. Reviewers should use sha256sum for this task as it is used by the `+sources+` file once imported into git. If no upstream URL can be specified for this package, please see the xref:SourceURL.adoc[Source URL Guidelines] for how to deal with this. +
-* [[successful-build]] *MUST*: The package *MUST* successfully compile and build into binary rpms on at least one primary architecture. See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support] +
-* [[exclude-arch]] *MUST*: If the package does not successfully compile, build or work on an architecture, then those architectures should be listed in the spec in `+ExcludeArch+`. Each architecture listed in `+ExcludeArch+` *MUST* have a bug filed in bugzilla, describing the reason that the package does not compile/build/work on that architecture. The bug number *MUST* be placed in a comment, next to the corresponding `+ExcludeArch+` line. See xref:index.adoc#_architecture_build_failures[Packaging Guidelines: Architecture Build Failures] +
-* [[build-dependencies]] *MUST*: All build dependencies must be listed in `+BuildRequires+`. See xref:index.adoc#buildrequires[Packaging Guidelines: Build-Time Dependencies (BuildRequires)] +
-* [[locales]] *MUST*: The spec file MUST handle locales properly. This is done by using the `+%find_lang+` macro. Using `+%{_datadir}/locale/*+` is strictly forbidden. See xref:index.adoc#_handling_locale_files[Packaging Guidelines: Handling Locale Files] +
-* [[bundling]] *MUST*: Packages must NOT bundle copies of system libraries. See xref:index.adoc#bundling[Packaging Guidelines: Bundling and Duplication of System Libraries] +
-* [[relocatable-package]] *MUST*: If the package is designed to be relocatable, the packager must state this fact in the request for review, along with the rationalization for relocation of that specific package. Without this, use of Prefix: /usr is considered a blocker. See xref:index.adoc#_relocatable_packages[Packaging Guidelines: Relocatable Packages] +
-* [[directory-ownership]] *MUST*: A package must own all directories that it creates. If it does not create a directory that it uses, then it should require a package which does create that directory. See xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File And Directory Ownership] +
-* [[file-listed-once]] *MUST*: A Fedora package must not list a file more than once in the spec file's %files listings. (Notable exception: license texts in specific situations)See xref:index.adoc#_duplicate_files[Packaging Guidelines: Duplicate Files] +
-* [[premissions]] *MUST*: Permissions on files must be set properly. Executables should be set with executable permissions, for example. See xref:index.adoc#_file_permissions[Packaging Guidelines: File Permissions] +
-* [[consistent-macros]] *MUST*: Each package must consistently use macros. See xref:index.adoc#_macros[Packaging Guidelines: Macros] +
-* [[permisible-content]] *MUST*: The package must contain code, or permissible content. See xref:what-can-be-packaged.adoc[What Can Be Packaged] +
-* [[large-documentation]] *MUST*: Large documentation files must go in a -doc subpackage. (The definition of large is left up to the packager's best judgement, but is not restricted to size. Large can refer to either size or quantity). See xref:index.adoc#_documentation[Packaging Guidelines: Documentation] +
-* [[doc-runtime]] *MUST*: If a package includes something as %doc, it must not affect the runtime of the application. To summarize: If it is in %doc, the program must run properly if it is not present. See xref:index.adoc#_documentation[Packaging Guidelines: Documentation] +
-* [[static-libraries]] *MUST*: Static libraries must be in a -static package. See xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries] +
-* [[devel-subpackage]] *MUST*: Development files must be in a -devel package. See xref:index.adoc#_devel_packages[Packaging Guidelines: Devel Packages] +
-* [[versioned-devel-require]] *MUST*: In the vast majority of cases, devel packages must require the base package using a fully versioned dependency: `+Requires: %{name}%{?_isa} = %{version}-%{release}+` See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package] +
-* [[la-archives]] *MUST*: Packages must NOT contain any .la libtool archives, these must be removed in the spec if they are built. See xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries] +
-* [[desktop-file]] *MUST*: Packages containing GUI applications must include a %\{name}.desktop file, and that file must be properly installed with desktop-file-install in the %install section. If you feel that your packaged GUI application does not need a .desktop file, you must put a comment in the spec file with your explanation. See xref:index.adoc#_desktop_files[Packaging Guidelines: Desktop files] +
-* [[file-directory-ownership]] *MUST*: Packages must not own files or directories already owned by other packages. The rule of thumb here is that the first package to be installed should own the files or directories that other packages may rely upon. This means, for example, that no package in Fedora should ever share ownership with any of the files or directories owned by the `+filesystem+` or `+man+` package. If you feel that you have a good reason to own a file or directory that another package owns, then please present that at package review time. See xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File and Directory Ownership] +
-* [[utf-8]] *MUST*: All filenames in rpm packages must be valid UTF-8. See xref:index.adoc#_non_ascii_filenames[Packaging Guidelines: Non-ASCII Filenames] +
-* [[deprecated-packages]] *MUST*: Packages being added to the distribution MUST NOT depend on any packages which have been marked as being deprecated. See xref:deprecating-packages.adoc[Deprecating Packages] +
+* [[rpmlint]] *MUST*:
+  rpmlint must be run on the source rpm and all binary rpms the build produces.
+  The output should be posted in the review.
+  See xref:index.adoc#_use_rpmlint[Packaging Guidelines: Use rpmlint].
+* [[naming]] *MUST*:
+  The package must be named according to the xref:Naming.adoc[Package Naming Guidelines].
+* [[spec-fie-name]] *MUST*:
+  The spec file name must match the base package `+%{name}+`,
+  in the format `+%{name}.spec+`
+  unless your package has an exemption.
+  See xref:index.adoc#_spec_file_naming[Packaging Guidelines: Spec File Naming].
+* [[packaging-guidelines]] *MUST*:
+  The package must meet the xref:index.adoc[Packaging Guidelines].
+* [[approved-license]] *MUST*:
+  The package must be licensed with a Fedora approved license
+  and meet the xref:LicensingGuidelines.adoc[Licensing Guidelines].
+* [[license-field]] *MUST*:
+  The License field in the package spec file
+  must match the actual license.
+  See xref:LicensingGuidelines.adoc#_valid_license_short_names[Licensing Guidelines: Valid License Short Names].
+* [[license-file]] *MUST*:
+  If (and only if) the source package includes the text of the license(s) in its own file,
+  then that file, containing the text of the license(s) for the package
+  must be included in `+%license+`.
+  See xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text].
+* [[spec-in-american-english]] *MUST*:
+  The spec file must be written in American English.
+  See xref:index.adoc#_summary_and_description[Packaging Guidelines: Summary and description].
+* [[legible-spec]] *MUST*:
+  The spec file for the package *MUST* be legible.
+  See xref:index.adoc#_spec_legibility[Packaging Guidelines: Spec Legibility].
+* [[build-sources]] *MUST*:
+  The sources used to build the package
+  must match the upstream source,
+  as provided in the spec URL.
+  Reviewers should use sha256sum for this task
+  as it is used by the `+sources+` file once imported into git.
+  If no upstream URL can be specified for this package,
+  please see the xref:SourceURL.adoc[Source URL Guidelines] for how to deal with this.
+* [[successful-build]] *MUST*:
+  The package *MUST* successfully compile and build into binary rpms
+  on at least one primary architecture.
+  See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support].
+* [[exclude-arch]] *MUST*:
+  If the package does not successfully compile,
+  build or work on an architecture,
+  then those architectures should be listed in the spec in `+ExcludeArch+`.
+  Each architecture listed in `+ExcludeArch+` *MUST* have a bug filed in bugzilla,
+  describing the reason that the package does not compile/build/work on that architecture.
+  The bug number *MUST* be placed in a comment,
+  next to the corresponding `+ExcludeArch+` line.
+  See xref:index.adoc#_architecture_build_failures[Packaging Guidelines: Architecture Build Failures].
+* [[build-dependencies]] *MUST*:
+  All build dependencies must be listed in `+BuildRequires+`.
+  See xref:index.adoc#buildrequires[Packaging Guidelines: Build-Time Dependencies (BuildRequires)].
+* [[locales]] *MUST*:
+  The spec file MUST handle locales properly.
+  This is done by using the `+%find_lang+` macro.
+  Using `+%{_datadir}/locale/*+` is strictly forbidden.
+  See xref:index.adoc#_handling_locale_files[Packaging Guidelines: Handling Locale Files].
+* [[bundling]] *MUST*:
+  Packages must NOT bundle copies of system libraries.
+  See xref:index.adoc#bundling[Packaging Guidelines: Bundling and Duplication of System Libraries].
+* [[relocatable-package]] *MUST*:
+  If the package is designed to be relocatable,
+  the packager must state this fact in the request for review,
+  along with the rationalization for relocation of that specific package.
+  Without this, use of Prefix: /usr is considered a blocker.
+  See xref:index.adoc#_relocatable_packages[Packaging Guidelines: Relocatable Packages].
+* [[directory-ownership]] *MUST*:
+  A package must own all directories that it creates.
+  If it does not create a directory that it uses,
+  then it should require a package
+  which does create that directory.
+  See xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File And Directory Ownership].
+* [[file-listed-once]] *MUST*:
+  A Fedora package must not list a file more than once
+  in the spec file's %files listings.
+  (Notable exception: license texts in specific situations)See xref:index.adoc#_duplicate_files[Packaging Guidelines: Duplicate Files].
+* [[premissions]] *MUST*:
+  Permissions on files must be set properly.
+  Executables should be set with executable permissions, for example.
+  See xref:index.adoc#_file_permissions[Packaging Guidelines: File Permissions].
+* [[consistent-macros]] *MUST*:
+  Each package must consistently use macros.
+  See xref:index.adoc#_macros[Packaging Guidelines: Macros].
+* [[permisible-content]] *MUST*:
+  The package must contain code,
+  or permissible content.
+  See xref:what-can-be-packaged.adoc[What Can Be Packaged].
+* [[large-documentation]] *MUST*:
+  Large documentation files must go in a -doc subpackage.
+  (The definition of large is left up to the packager's best judgement,
+  but is not restricted to size.
+  Large can refer to either size or quantity).
+  See xref:index.adoc#_documentation[Packaging Guidelines: Documentation].
+* [[doc-runtime]] *MUST*:
+  If a package includes something as %doc,
+  it must not affect the runtime of the application.
+  To summarize: If it is in %doc,
+  the program must run properly if it is not present.
+  See xref:index.adoc#_documentation[Packaging Guidelines: Documentation].
+* [[static-libraries]] *MUST*:
+  Static libraries must be in a -static package.
+  See xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries].
+* [[devel-subpackage]] *MUST*:
+  Development files must be in a -devel package.
+  See xref:index.adoc#_devel_packages[Packaging Guidelines: Devel Packages].
+* [[versioned-devel-require]] *MUST*:
+  In the vast majority of cases,
+  devel packages must require the base package
+  using a fully versioned dependency:
+  `+Requires: %{name}%{?_isa} = %{version}-%{release}+`.
+  See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package].
+* [[la-archives]] *MUST*:
+  Packages must NOT contain any .la libtool archives,
+  these must be removed in the spec if they are built.
+  See xref:index.adoc#packaging-static-libraries[Packaging Guidelines: Packaging Static Libraries].
+* [[desktop-file]] *MUST*:
+  Packages containing GUI applications must include a %\{name}.desktop file,
+  and that file must be properly installed
+  with `desktop-file-install` in the `+%install+` section.
+  If you feel that your packaged GUI application
+  does not need a .desktop file,
+  you must put a comment in the spec file
+  with your explanation.
+  See xref:index.adoc#_desktop_files[Packaging Guidelines: Desktop files].
+* [[file-directory-ownership]] *MUST*:
+  Packages must not own files or directories
+  that are already owned by other packages.
+  The rule of thumb here is
+  that the first package to be installed
+  should own the files or directories
+  that other packages may rely upon.
+  This means, for example,
+  that no package in Fedora should ever share ownership
+  with any of the files or directories
+  owned by the `+filesystem+` or `+man+` package.
+  If you feel that you have a good reason
+  to own a file or directory that another package owns,
+  then please present that at package review time.
+  See xref:index.adoc#_file_and_directory_ownership[Packaging Guidelines: File and Directory Ownership].
+* [[utf-8]] *MUST*:
+  All filenames in rpm packages must be valid UTF-8.
+  See xref:index.adoc#_non_ascii_filenames[Packaging Guidelines: Non-ASCII Filenames].
+* [[deprecated-packages]] *MUST*:
+  Packages being added to the distribution
+  MUST NOT depend on any packages
+  which have been marked as being deprecated.
+  See xref:deprecating-packages.adoc[Deprecating Packages].
 
 '''
 
-* [[upstream-license-file]] *SHOULD*: If the source package does not include license text(s) as a separate file from upstream, the packager SHOULD query upstream to include it. See xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text] +
-* [[builds-in-mock]] *SHOULD*: The reviewer should test that the package builds in mock. See https://fedoraproject.org/wiki/Using_Mock_to_test_package_builds[Using Mock to test package builds] +
-* [[supports-all-architectures]] *SHOULD*: The package should compile and build into binary rpms on all supported architectures. See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support] +
-* [[functions-as-described]] *SHOULD*: The reviewer should test that the package functions as described. A package should not segfault instead of running, for example. +
-* [[sane-scriplets]] *SHOULD*: If scriptlets are used, those scriptlets must be sane. This is vague, and left up to the reviewers judgement to determine sanity. See xref:index.adoc#_scriptlets[Packaging Guidelines: Scriptlets] +
-* [[subpackage-versioned-requires]] *SHOULD*: Usually, subpackages other than devel should require the base package using a fully versioned dependency. See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package] +
-* [[pkgconfig-in-devel]] *SHOULD*: The placement of pkgconfig(.pc) files depends on their usecase, and this is usually for development purposes, so should be placed in a -devel pkg. A reasonable exception is that the main pkg itself is a devel tool not installed in a user runtime, e.g. gcc or gdb. See xref:index.adoc#_pkgconfig_files_foo_pc[Packaging Guidelines: Pkgconfig Files] +
-* [[man-pages]] *SHOULD*: your package should contain man pages for binaries/scripts. If it doesn't, work with upstream to add them where they make sense. See xref:index.adoc#_manpages[Packaging Guidelines: Manpages] +
+* [[upstream-license-file]] *SHOULD*:
+  If the source package does not include license text(s)
+  as a separate file from upstream,
+  the packager SHOULD query upstream to include it.
+  See xref:LicensingGuidelines.adoc#_license_text[Licensing Guidelines: License Text].
+* [[builds-in-mock]] *SHOULD*:
+  The reviewer should test that the package builds in mock.
+  See https://fedoraproject.org/wiki/Using_Mock_to_test_package_builds[Using Mock to test package builds].
+* [[supports-all-architectures]] *SHOULD*:
+  The package should compile and build into binary rpms
+  on all supported architectures.
+  See xref:index.adoc#_architecture_support[Packaging Guidelines: Architecture Support].
+* [[functions-as-described]] *SHOULD*:
+  The reviewer should test that the package functions as described.
+  A package should not segfault instead of running, for example.
+* [[sane-scriplets]] *SHOULD*:
+  If scriptlets are used, those scriptlets must be sane.
+  This is vague, and left up to the reviewers judgement to determine sanity.
+  See xref:index.adoc#_scriptlets[Packaging Guidelines: Scriptlets].
+* [[subpackage-versioned-requires]] *SHOULD*:
+  Usually, subpackages other than devel should require the base package
+  using a fully versioned dependency.
+  See xref:index.adoc#_requiring_base_package[Packaging Guidelines: Requiring Base Package].
+* [[pkgconfig-in-devel]] *SHOULD*:
+  The placement of pkgconfig(.pc) files depends on their usecase,
+  and this is usually for development purposes,
+  so should be placed in a -devel pkg.
+  A reasonable exception is that the main pkg itself
+  is a devel tool not installed in a user runtime,
+  e.g. gcc or gdb.
+  See xref:index.adoc#_pkgconfig_files_foo_pc[Packaging Guidelines: Pkgconfig Files].
+* [[man-pages]] *SHOULD*:
+  Your package should contain man pages for binaries/scripts.
+  If it doesn't, work with upstream to add them where they make sense.
+  See xref:index.adoc#_manpages[Packaging Guidelines: Manpages].
 
 == A note on dependencies
 
-It is often useful to submit a package for review along with its dependencies in separate tickets. As long as the submitter sets up the Depends on: and Blocks: fields in bugzilla properly, this is not an issue, and it is perfectly possible to review these packages before the full dependency chain is in the distribution (by maintaining a local repository, building and installing the packages locally, or maintaining a Copr).
+It is often useful to submit a package for review
+along with its dependencies in separate tickets.
+As long as the submitter sets up the _Depends on:_ and _Blocks:_ fields in BugZilla properly,
+this is not an issue,
+and it is perfectly possible to review these packages
+before the full dependency chain is in the distribution
+(by maintaining a local repository,
+building and installing the packages locally,
+or maintaining a COPR).
 
-However, please keep in mind that you cannot do koji builds if all of the build dependencies are not met (because you cannot provide additional dependencies to koji) and when the time comes to build these packages, they must be built in order and you must wait between builds for the dependencies to make it into the appropriate branch of the distribution.
+However, please keep in mind that you cannot do koji builds
+unless all of the build dependencies are met
+(because you cannot provide additional dependencies to koji)
+and when the time comes to build these packages,
+they must be built in order
+and you must wait between builds for the dependencies
+to make it into the appropriate branch of the distribution.
 This can be automated using side tags and chain builds.
 
-Please also note that while you may actually be able to build a package because all of its build-time dependencies are met, the package may still be non-installable (and thus useless) if its _runtime_ dependencies are not met. A package *MUST* not be built if any of its runtime dependencies are unsatisfied.
-
-== References to the Fedora Packaging Guidelines
+Please also note that while you may actually be able to build a package
+because all of its build-time dependencies are met,
+the package may still be non-installable (and thus useless)
+if its _runtime_ dependencies are not met.
+A package *MUST* not be built
+if any of its runtime dependencies are unsatisfied.

From 0e84bad929349eeb7ced0a11d995c6aafce12cec Mon Sep 17 00:00:00 2001
From: Fabio Valentini 
Date: May 01 2025 16:26:07 +0000
Subject: [PATCH 232/232] ReviewGuidelines: rules for new packages for existing components


---

diff --git a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
index 5de7e3e..e15cbe8 100644
--- a/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
+++ b/guidelines/modules/ROOT/pages/ReviewGuidelines.adoc
@@ -10,7 +10,7 @@ whenever items are unclear,
 and if in doubt,
 ask on the https://lists.fedoraproject.org/admin/lists/packaging.lists.fedoraproject.org/[Fedora packaging list] .
 
-== Package Review Process
+== Package Review Exceptions
 
 Contributors and reviewers
 MUST follow the https://docs.fedoraproject.org/en-US/package-maintainers/Package_Review_Process/[Package Review Process],
@@ -31,6 +31,28 @@ with the following exceptions:
   to provide a subpackage that exists in Fedora
   but does not exist (or is not shipped) in RHEL.
 
+== Relaxed rules for existing components
+
+Some guidelines that apply to "new" packages
+do not need to be applied when reviewing packages
+that are only _"added"_ to the distribution
+in the sense that the name of the _source package_ is "new"
+but the component was already available
+from an existing package, i.e. when
+
+* renaming an existing package,
+* moving a subcomponent from an existing package
+  into a separate source package,
+* adding an alternative version ("compat package")
+  of an existing package, or
+* adding an EPEL-only alternative version
+  of an existing package.
+
+For example, it is allowed for a _"new"_ package like this
+to depend on packages marked as `+deprecated()+`
+because no _actually new_ component
+will depend on the deprecated package.
+
 == Things To Check On Review
 
 There are many many things to check for a review.