In general, I agree that the docs could use a short "tl;dr — the common case" section at the top. This also applies to the "simplified" versioning guidelines with full version info the the Version field. I wrote a chunk of the latest text and I'm having trouble finding the right paragraph in all that prose. The descriptions that we have are correct, but just not very easy to consume casually. This is part of a bigger problem: docs have regularly been coming up in various surveys as the number one problem in Fedora.
IMO, one of the causes is that we've been keeping the descriptions of older workflows. In case of Versioning it's because some ancient RHEL baggage doesn't support the new stuff, and also because some people just *like* the old approach. In case of Python macros, it's because not all packages can use the new build systems, etc. But I think this isn't working, and we should just settle on the best version and prune the rest or move to appendices. People can look at archived versions of the docs if they want to do technoarcheology.
Right now, rpmdevtools recommends 'rm -rf $RPM_BUILD_ROOT' and outdated python macros. Almost no guides have been updated for rpmautospec. (Though thankfully at least fedora-review has been fixed not to warn about %autorelease.) Etc, etc. Experienced packagers know what to ignore, but new packagers are very likely to fall into the numerous traps we set out for them.
On Sun, Dec 19, 2021 at 02:26:15PM -0500, Matthew Miller wrote:
- You mentioned in the review request — and Zbyszek said something similar — that it'd be better to repeat the package name throughout the spec
file in the various place it's needed. That doesn't feel right to me.
I know the macros replace a lot of boilerplate, which is a good direction, but having the name be different in every file _throughout_ the file makes it harder to pick up when something is different from standard. It seems that a lot of python packages could be identical _except_ for the header. (And maybe then all of that eventually hidden completely with just some thing near the top that indicates "standard python package".)
I find 'pywaffle' easier to read that '%{pypi_name}'. When I see e.g. '%{_bindir}/%{pypi_name}', I *can* do the substitutions in my head and arrive at '/usr/bin/pywaffle', but it's certainly a bit of an overhead.
Using macros for things that *change* is reasonable: we certainly wouldn't want to search&replace the version string when it changes during version upgrades, and we can't hardcode the library path, because it changes between architectures. But for things that *never change* during the lifetime of the package, what is the point of using macros? When you create a package for a different python module, you're going to start afresh. The spec file should be as readable as possible for _that particular package_. This also means not using unnecessary macros and making the spec file as short as is reasonable.
It seems that a lot of python packages could be identical _except_ for the header.
Not really. There's still a lot of variation between packages: even Python packages have different build systems, various workarounds and required, etc. The spec files have been becoming shorter, but right now it isn't practical to completely hide all the details. If the technology improves, _and_ upstreams clean up their metadata, maybe we'll be able to handle common Python packaging scenarios with a one-line boilerplate.
But right now we're not there yet. In your spec file, we have 'pywaffle', '%{pypi_name}', and '%{githubname}' used in various places. When reading the spec file, I need to jump up to the header to check the definition of the macros to remember which one is which.
(There's also the tiny annoyance that I can't ctrl-click on https://github.com/gyli/%%7Bgithubname%7D to open the repo, I need to do the substitution… Firefox doesn't understand the macro either.)
- The machinery to make every package be python-... while generating an actual python3-... subpackage is awkward. Are we stuck with that forever?
Yes, I think we'll have this for the foreseeable future. On EPEL, you can have multiple python versions, so we *need* the subpackages there. Maybe we'll be able to hide the binary package name once we have package generators (https://github.com/rpm-software-management/rpm/issues/329).
Zbyszek