Bug 2123167

Summary: Multiple places document %pyproject_buildrequires options, each differently
Product: [Fedora] Fedora Reporter: Otto Liljalaakso <otto.liljalaakso>
Component: pyproject-rpm-macrosAssignee: Miro Hrončok <mhroncok>
Status: CLOSED UPSTREAM QA Contact: Fedora Extras Quality Assurance <extras-qa>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: rawhideCC: mhroncok, pviktori, python-sig
Target Milestone: ---   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2022-09-05 16:53:20 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Otto Liljalaakso 2022-08-31 20:23:26 UTC 
Description of problem:

I have found the following places documenting the options accepted by %pyproject_buildrequires:

1. Packaging guidelines: https://docs.fedoraproject.org/en-US/packaging-guidelines/Python/#_build_macros
2. pyproject-rpm-macros README: https://src.fedoraproject.org/rpms/pyproject-rpm-macros/blob/b2bb5439dce2639363618f898d238b8d4e2bc8a5/f/README.md?text=True#_64
3. Source of macro implementation: https://src.fedoraproject.org/rpms/pyproject-rpm-macros/blob/b2bb5439dce2639363618f898d238b8d4e2bc8a5/f/pyproject_buildrequires.py#_425

As expected, these are not all identical.
In particular, as short as the Packaging Guidelines' variant is,
it manages to refer to '-r' option without defining it.
README suffers from the same problem,
but it is not as obvious since it is much longer.

Could at least the Packaging guidelines be improved in this regard?
It is quite confusing for people just starting with Python packaging.

In my opinion, the packaging guidelines could just refer to the other docs for the options,
and only have content like "in situation X, use option -Y".

Version-Release number of selected component (if applicable):

pyproject-rpm-macros commit b2bb5439dce2639363618f898d238b8d4e2bc8a5
Packaging guidelines commit 7e625c2cd17f14fde2a284268811f754cde2a239
Comment 1 Miro Hrončok 2022-08-31 21:04:36 UTC 
For one, I think that packaging guidelines should not need to mention `-r` at all. The "Implies -r" thing should have been removed when -r was made the default.
Comment 2 Miro Hrončok 2022-09-01 07:46:11 UTC 
(In reply to Miro Hrončok from comment #1)
> For one, I think that packaging guidelines should not need to mention `-r`
> at all. The "Implies -r" thing should have been removed when -r was made the
> default.

Proposed change of wording: https://pagure.io/packaging-committee/pull-request/1206
Comment 3 Miro Hrončok 2022-09-01 07:57:57 UTC 
Proposed change for the README: https://src.fedoraproject.org/rpms/pyproject-rpm-macros/pull-request/323
Comment 4 Otto Liljalaakso 2022-09-01 11:28:27 UTC 
Both proposals look fine to me, thank you for the quick response!
Comment 5 Miro Hrončok 2022-09-05 16:53:20 UTC 
(In reply to Miro Hrončok from comment #2)
> (In reply to Miro Hrončok from comment #1)
> > For one, I think that packaging guidelines should not need to mention `-r`
> > at all. The "Implies -r" thing should have been removed when -r was made the
> > default.
> 
> Proposed change of wording:
> https://pagure.io/packaging-committee/pull-request/1206

Merged.

(In reply to Miro Hrončok from comment #3)
> Proposed change for the README:
> https://src.fedoraproject.org/rpms/pyproject-rpm-macros/pull-request/323

Merged.

I'm now closing this. The updated README will be part of the next update.