General feedback about python packager guidelines: [main] guidelines/modules/ROOT/pages/Python.adoc #1547
Labels
No labels
announce
bootstrap
Closed As
accepted
Closed As
duplicate
Closed As
exceptionexpired
Closed As
fixed
Closed As
invalid
Closed As
nothingtodo
Closed As
permanentexception
Closed As
rejected
Closed As
temporaryexception
Closed As
wontfix
cmake
committee
draftneeded
hasdraft
meeting
meson
needinfo
Priority
In Committee
Priority
Needs Review
Priority
Waiting For Reporter
rust
writeup
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
packaging/guidelines#1547
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
A very general feedback about the python packager guidelines (just using them for the first time):
They are good, I can work with that. Thank you very much for providing them!
But it could be made clearer when importable modules are elaborated, and when not, and when both are treated the same, and when not. In the end, it can be derived, but it could be simplified.
Another thing that could be interesting, especially for people who are new to rpm: a link to the upstream documentation for, e.g., macros that are not elaborated within this guide, maybe even at the very places. E.g., it has proven very useful to me to have always the very https://rpm-software-management.github.io/rpm/manual/* pages open in another tab. Again, people would find out themselves I think. But the simpler and clearer it is at first glance, the more likely it is that people finish what they start :)
Feel free to close this, it's just for your general consideration at your discretion.
I don't post about the general guidelines: I expect they are to be written from scratch anyway.
Update based on a discussion of today in #devel:fedoraproject.org -> it might occur that the (or some)
https://rpm-software-management.github.io/rpm/manual/*pages are to be deleted/replaced.Apologies, but I have trouble understanding this sentence. Could you please rephrase it?
We can do that, if there is a place to link to. Noted.
I don't think so :)
Sorry, my bad :) I try to elaborate ...
So, the implications for importable module and applications are not equal. Sometimes both are elaborated separately due to different implications. Sometimes it is not explicitly differentiated (which makes the reader assume that part refers to both, if not indicated otherwise).
However, parts of the guide refer only to importable modules, while the situation for applications is not elaborated separately. This includes elaborations and examples (e.g., the spec examples refer only to importable modules when they contain a reference). So far, I have found all information I needed, also for applications. But it needs some skimming back and forth to be sure that some parts refer to both.
The issue can be that some parts only reference (or, elaborate) importable modules (when they contain one/many reference(s)/examples) but are applicable to importable modules AND applications, e.g., ...
-> Large parts of "Files to include" and later parts.
... but the issue can be also that at some parts only importable modules are elaborated and these parts are also meant only for importable modules, but when it becomes generic again in a subsequent paragraph (generic = applicable to importable modules AND applications), it is not immediately clear that this paragraph is no longer only about importable modules but also about applications. E.g., ...
-> I think a good example to illustrate (although it is one most readers will likely solve quickly themselves): there is a lot of elaboration of importable modules, culminating in the pello library spec file. This is followed by a generic spec file. It needs a short skim forth and back to be sure that this is not only a spec template for libraries.
A related complication is that the definition/differentiation of libraries and modules are introduced after the terms have been already used in some parts ("A Python library is a package meant to be imported in Python, such as with ..."). Maybe it's also useful to consolidate the definitions, as the elaboration that one package can have multiple modules is relevant for the definitions and differentiations.
Again, these are minor issues, and the reader can make sense of it without asking. It's already a great document! It's just some parts in which it can maybe improved from some readers' perspectives, in order to further reduce the needs for skimming back and forth (while I think in such a document it can never be fully avoided to skim back and forth ^^) :)
Yeah, I had mostly some chats from Flock in mind :) And some hope that someone will have the time at some point :D Everybody I talked to who had some experience with that document expected a full rewrite is more likely than more updates. My feeling was also that the many updates from different people with different assumptions and different perspectives (plus re-orderings of paragraphs that lead some paragraphs to assume the reader to know what is elaborated later^^) are the origin of it being no longer immediately comprehensible for newcomers. So I thought it has little sense to create a ticket for improvements, as even more partial updates might make things worse :)
Hope that makes some sense, and again, thanks for providing these documentations :) Much appreciated to have them!