I'd like Fedora and FPC in general to agree to a general layout for rpm macros and their associated material like templates, so people can focus on writing actual macros and their documentation, and not on how the result is shipped to users.

The reason being I'm currently wrapping up three sets of rpm macros for Fedora⁰. The coding and first-pass testing for each macro set is mostly done, the next step is packaging, documenting, and guideline-ing.

I'd like to do the documenting and guideline-ing for each macro set via standard templates. Wiki (or the new docs site) is a huge time sink to write and update, and most packagers do not read the result, so it's mostly a waste of time. OTOH templates are operational and do work. Thus with hindsight, a short paragraph in guidelines that points to a package of templates, works loads better than a wall of wiki text

Here is how I understand today's Fedora best practices. To my knowledge, they are mostly unwritten packager lore. (obviously stuff in redhat-rpm-config is a special case)

%<--

A. A single project hosts macros, templates, documentation, and other helpers in packaging <foo> material, and keeps everything in sync.

• the project SHOULD be named <foo>-rpm-macros
• it SHOULD be hosted on Fedora infra, or a cross-distribution hosting site
  (ie pagure.io, even if I find it severely limiting from a forge POW).
• Fedora infra makes it easy to assign/reassign ownership to SIG members

B. The project SHOULD be packaged in a <foo>-rpm-macros source package

• the source package MAY buildrequire anything
  • however, it SHOULD be solely composed of macros, docs, scripts, that do not need much building
  • anything requiring a binary build SHOULD be packaged separately then required by the appropriate <foo>-rpm-macros subpackage

C. The <foo>-rpm-macros spec file SHOULD generate at least some of the following subpackages

• using -n, to avoid human-unfriendly package names

C.1 A package named <foo>-srpm-macros

• this package MUST exist if the macro set defines anything needed by rpmbuild -bs to create source packages that include <foo> code or content
• it MUST be in the default build root (buildsys group)
• it MUST NOT require anything and be small
  • we want builds to be fast and efficient, and only pull ecosystem-specific buildrequires in the build roots that actually need them
• it SHOULD define a pivot macro expected to be present in every <foo> spec file
• this macro SHOULD generate a buildrequires on <foo>-rpm-macros

C.2 A package named <foo>-rpm-macros

• this package MUST provide any remaining rpm macro or constant needed by rpmbuild -ba to create deployment (sub)packages that include <foo> material
  • typically at least the constants defining standard file system locations for <foo> material
• it MUST NOT assume it will exist in the default build root. It will be pulled in:
  • by the pivot macro if in <foo> spec files if <foo>-srpm-macros exists,
  • by direct buildrequires otherwise
• it SHOULD require any other package typically needed to build <foo> (sub)packages.
  • require restrictions are limited to <foo>-srpm-macros, not <foo>-rpm-macros
  • for example: the Go compiler for Go packages, fontconfig for fonts packages,
• it MUST require <foo>-filesystem if this package exists
• it SHOULD NOT be necessary to <foo> packages once built, nor be required by those packages

C.3 A package named <foo>-filesystem

• this package MUST materialize and own the file system locations defined in <foo>-rpm-macros
• it MUST NOT require anything except other filesystem-style packages
• it SHOULD be depended on by <foo> packages whenever they make use of those locations

C.4 A package named <foo>-rpm-templates

• this package SHOULD depend on rpmdevtools
• it SHOULD provide at least one template in %{_spectemplatedir} showing how <foo> macros are supposed to be used
• it SHOULD contain any other documentation file, necessary to understand those templates
• it SHOULD NOT be necessary to <foo> packages once built, nor be required by those packages

C.5 A package named <foo>-rpm-tools

• it SHOULD provide anything not strictly necessary to execute the macros or to understand the templates, but can be useful to some packagers, typically convenience scripts
• it SHOULD NOT be necessary to <foo> packages once built, nor be required by those packages

%<--

Did I get this right or did I forget something important?

Regards,

⁰

1. "forge macros" v2 (v1 was merged in redhat-rpm-config 9 months ago)

macros to map <url,version,tag,commit,branch> metadata to classical rpm Source, URL, %setup, %dist, etc verbs, when a project is hosted on Gitlab, GitHub, etc (not Pagure because Pagure is missing needed functionality). There are hundreds if not thousands of packages in the distro that can make use of this.

v2 adds the ability to process multiple archives in a single source rpm.¹

2 "go macros" v2 (v1 was merged in go-compilers and go-srpm macros about the same time as the forge macros)

automation for packaging software written in the Go language (Go language). Go is getting huge nowadays, it's the language in which kubernetes, docker, and a lot of cloud infra software is being written today. This is really why I'm doing all this, the forge macros are just a spinoff of generic non-Go-specific functionality that Go macros need.

v2 add the ability to process multiple archives in a single source rpm, and Go BuildRequires automation (one of the huge missing bits in the v1)²

3 font macros v2 (v1 + associated guidelines were written by myself around a decade ago)

Another spinoff of 1. and 2. Mostly because golang-x-image is the upstream of the Go fonts, which has caused me to revisit the subject.

With the framework code written for 1., ten years of hindsight, experience, and rpm improvements, I can and did write macros that remove known problems in the current set, add missing functionalities like appstream handling, and are generally more convenient to use (took me about a week-end of hacking)³

¹ A first version has already been completed and merged in redhat-rpm-config 9 months ago. Thanks to everyone involved.

https://src.fedoraproject.org/rpms/redhat-rpm-config/c/7c4cd330850ee228ca727b80516e187cf87f30c7

It worked and still works fine, you can use it today in your packages, but it has a huge limitation: it assumes you only need to process a single source archive in the specfile. People rightly pointed out in the review that, while it's the general and preferred case, some packages do need to mix source archives (esp. on EL given the hard constrains EL has on not touching existing package layout).

Therefore I've prepared a new version that can process multiple sources. It's backwards-compatible, multi-source is achieved via new flags, in the absence of those flags it will assume a single source like the current merged code does.

https://src.fedoraproject.org/rpms/redhat-rpm-config/pull-request/35

It adds a huge level of complexity macro-side, rpm does not really provide the framework to do this kind of multiplexing, the framework had to be coded from scratch in lua macro code. However, the framework has been coded now, it's generic, and rightly belongs in a generic package like redhat-rpm-config

² Currently in the final stages of technical testing before I document it and send a PR
https://github.com/nim-nim/go-macros/commits/dev

³ Currently past the technical testing, need to document it, send myself a PR, send the result to FPC and the Fonts SIG to switch existing packaging guidelines