-
Notifications
You must be signed in to change notification settings - Fork 1.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Update pyproject.toml #204
Conversation
- extend descriptions of build-system table - add useful links - edit other comments
- be more clear that the values in [build-system] may be generated by the command line interface of the build backend, so the [build-system] table is not required - reorganize comments to better correspond to their sections
add the changes authored by thomasbbrunner in pypa#197
@VladimirFokow almost everything you changed is really optional. Also, I recommend making small atomic changes so that they could be reviewed more easily and accepted faster, without implying countless rounds of reviews. |
@di could you approve the CI run? I don't have that privilege in this repo. |
Thanks for the reviews! Sorry for so many changes.. The total file isn't large though; if people now add their commits on top, we can all move closer towards a good final file.
|
Yes, which may mean months in-between reviews. Each asking to change one line. And the entire patch not being acceptable for a year. It's not about the size of the patch but semantically different changes. Does this PR mean to apply arbitrary updates that aren't related to each other? That doesn't sound like a sustainable strategy to me. Combining formatting and functional changes in the same patch usually makes it way easier for the reviewers to get lost in what's happening, which in turn prompts them to postpone doing reviews or delegate to somebody brave. I have a few collections or links related to contributing PRs. Perhaps, you'll find some of them useful: https://gist.github.com/webknjaz/2aa9c7a43b51c1385260ff87e0cbb9e3 / https://gist.github.com/webknjaz/a7362787a80067af8621a85a71746ca1 / https://gist.github.com/webknjaz/cb7d7bf62c3dda4b1342d639d0e78d79 (and https://gist.github.com/webknjaz/a5a4fb374b7579de827e6bedb93a5220 which is mostly dedicated to advanced Git usage, so maybe isn't applicable to you).
I don't know. Other people may have opinions. I only wanted 9 bytes removed from this file. |
It is setuptools. This is legacy behavior that originates in the history of these fields — Edit: However, if build isolation is used (the default in pip) and
The build frontend should raise an error. No build backend is invoked. General feedback:
For this very reason, I would honestly just remove the descriptions of the fields and only put a link to a subheading on the |
I remembered I was updating a related explanation in pip docs recently (pypa/pip#12449) and here's exactly what it does: https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/#fallback-behaviour. The exact implementation of the decision tree is @ https://github.com/pypa/pip/blob/811beab/src/pip/_internal/pyproject.py#L29-L179. |
This has its ins and outs. My understanding is that people may use this repo as a starting point and would be filling out the files as templates. In such a case, keeping the context close and not sending them on the round trip to the external docs has the least mental overhead. OTOH, keeping the descriptions in sync and up-to-date causes a burden for the maintainers. I'm not going to make a judgement call, but as this repo doesn't get a lot of activity, it does feel like reducing said maintenance burden would be beneficial in the long run. |
I actually didn't mean that the descriptions in this file were a burden - I think the descriptions here are good. That said, I also don't mind removing them completely if there is a specification link at the start with them all. Thinking about the larger picture - I think in this file specifically, there can be quick comments about why we decided to include these specific keys for the example project, even though they are optional, they are good to have, because |
You're talking from the PoV of a consumer / end-user. We're taking a point of a maintainer who ends up having to update those description regularly. It's a kind of a responsibility that tends to pile up and contribute to people burning out. |
To sum up:1. done✅ : I can create a commit to:
2. [optional]Create new SEPARATE issues to: - choose the set of keys as a default quick start - have only those descriptions here that are already in the docs (or summarise the docs) (so if we want to add something new here - add it to the docs first, then to here)
Does everyone agree for me to do these 2 actions? Should some min. version of "setuptools" be specified - which one? |
I don't think we need a PR to change the spelling of "behaviour". There's no policy that American spelling should be used over British spelling, so leave existing spellings alone (although I thought the spelling correction was just a change to something you'd added in this PR, not a change to existing text?) As for the second action, I have the same reservations as @webknjaz - I don't think it will add enough benefit to justify the maintenance effort. Simply reading the discussion on this PR has been more work on this repository than I've otherwise done in months - this project is supposed to be (very) low maintenance. But I'm largely indifferent to the idea, if you want to make a PR and someone wants to merge it, I won't object. I just don't personally think it's that important. |
@pfmoore (yes, I've introduced "behaviour" here, then "behavior" was suggested) I just want to improve the current |
Thanks a lot @VladimirFokow for working on this pull request :) |
- separate links to guide and specification - remove text that can already be found by following the provided links - more accurate comment about the `build-backend` key
Implemented the suggestion✅ Should some min. version of "setuptools" be specified? If so, which one? |
Same tests issue happens here that was in #197..
Any ideas what the next steps should be? |
The deprecated entry point interfaces for |
Is this the issue?:
Unfortunately, I don't have the technical skills now to figure out a solution to this. Python 3.7 has reached its end-of-life What if we just drop support for Python 3.7? |
Yes, but in a separate PR I'd suggest. For now, it's mostly about pinning the Line 28 in 3fb1461
|
I would say no. It might trigger a whole (long) discussion of its own, so I would not push too hard on this topic within this pull request if I were you. |
IMHO, this is easy to answer: the setuptools documentation does not have a bound, so this sample shouldn't either. |
The same considerations should be applied as with normal software deps. If a project uses a specific feature from a lib, it's natural to declare that a minimum version of that lib is required. Similarly, if there are features used in the packaging config that setuptools only supports starting with a certain version, it's good to communicate that. I recommend pairing that with an explanatory comment like But outside of such context, when the features used are implemented by any version of a dependency, then the dependency declaration should communicate exactly that — an unbound requirement specifier. Upper bounds are more complicated and shouldn't generally be used most of the time. |
pyproject.toml
is outdated. I have:moved the
[build-system]
to the start of the file (because this setting is pretty important, and I saw this everywhere in examples in the docs)simplified & updated the
[build-system]
tableremoved all
# Optional
comments (because the majority of keys are optional by default) - it's better to mark only the# REQUIRED
onesadded useful explanations and links
(plus, integrated the changes from pull request #197)
Explanations:
click: Explanations
How I changed the
[build-system]
table:The
[build-system]
parameters that I used here are:setuptools
? - it is the default build backendPros of these new
[build-system]
parameters:the assumed default build requirements from pip
:Cons of these new
[build-system]
parameters:setuptools
is not recent enough. -- (Is this a big problem?) Maybe some min. version should be specified - which one?so mentioning them in this sample project (which is a recommendation for NEW projects) is not necessary.
The only required keys are:
name
andversion
. All the other ones are optional.So it's better to not mark every key as Optional but instead only to mark these 2 as
# REQUIRED
.Other quotes and proofs
# REQUIRED
comment next to the[build-system]
table:
✅Please correct this if it's wrongdoneWhat comment is suitable if the
build-backend
parameter is missing?About the
build-backend
parameter:I've found this in only one place - in a note in parenthesis; I have doubts: if
pyproject.toml
exists andrequires = NOT setuptools
butbuild-backend
isn't defined, willsetuptools
still be used? - or the chosen backend?On the other page, I've seen:
So the other build backend chooses what to do? - then it's not
setuptools
in this case?You can just remove this line please:
"# If not defined, then the fall-back behaviour is to use setuptools."
and maybe give this key a "# REQUIRED" comment.. or not?
Plus, maybe add this as well?