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:
> 2. 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/%{githubname} to open the repo, I need to do
the substitution… Firefox doesn't understand the macro either.)
> 3. 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
_______________________________________________
python-devel mailing list -- python-devel@lists.fedoraproject.org
To unsubscribe send an email to python-devel-le...@lists.fedoraproject.org
Fedora Code of Conduct:
https://docs.fedoraproject.org/en-US/project/code-of-conduct/
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives:
https://lists.fedoraproject.org/archives/list/python-devel@lists.fedoraproject.org
Do not reply to spam on the list, report it:
https://pagure.io/fedora-infrastructure
