Add an initial specification doc for Dependency Groups #1623
Conversation
|
May I suggest adding the PEP "as is" first. In a separate PR. This would allow seeing the diff between that and simplification. Alternatively, put it in here in a separate commit, leaving the changes out so they'd only show up in the second commit. |
|
Sure, that's a good idea to make the diff more readable! I'll have to come back to this and rewrite the commit history to be
I'm not able to do it right now, but maybe tomorrow. |
|
@sirosen ack |
|
Oops! I forgot about this PR! I'll make an update this week. Thanks for the ping! |
This content is copied from the PEP, with the following characteristics: - the initial overview and examples are new - the "History" footer is new - all of the other sections are copied from the PEP verbatim
This is a significant revision from the PEP content to make the content appropriate for the packaging specs. In particular, the following changes are made: - references to "this PEP" are all removed - "Dependency Object Specifiers" are a layer of indirection around includes, and are removed from the documentation -- instead, the doc jumps straight to the (only) specific case now: the includes - the section on install UX and extras has been rewritten for brevity, removing the hypothetical example `pip` interface and folding together the install notes and the notes about extras - the section on validation/linting has been reorganized around an example, and the note on linters has been moved to a `note` admonition block
sirosen
force-pushed
the
dependency-groups
branch
from
6d6992c to
bb6f6cc
Compare
|
It's slightly embarrassing to have forgotten again, but that's what happened. I just checked my open PRs and saw this. I got it done by grabbing PEP text, rewriting my commit, and then checking out my rewrite over the top of it. Most of the edits are mild but I also see that some of the line break positions changed -- I can't recall the exact process by which I did the original work, but I may have been copying from a rendered copy of the PEP at times. As a result, there's some noise in the diff, but I hope it's still easier to review. |
|
@sirosen Added to the merge queue. Once it's live, you can submit the changes over in the PEPs repo to link to the canonical spec location. |
github-merge-queue
bot
removed this pull request from the merge queue due to failed status checks
|
I'm a little unclear if the merge-queue signal means that I should rebase, or just wait? (Sorry, not familiar with this GitHub feature!) |
|
Urgh... It's #1744. It needs to be fixed before merging can succeed. (merge queue failure https://github.com/pypa/packaging.python.org/actions/runs/12367078036/job/34514776165#step:5:849) |
|
@sirosen oh, and no, you don't need to rebase. Merge Queues make a temporary branch with your PR merged into When it doesn't fail because of some external circumstances (like in this case, with PyPI changing things), it is able to catch cases when two PRs have green CI but when they are merged together, it would fail (which isn't evident separately). Something like https://bors.tech/essay/2017/02/02/pitch/ but built-in (and more limited). |
|
#1767 has been posted with the PyPI link check workaround |
This is a first draft doc, based off of the original spec + reading the surrounding specs for examples of what's desirable.
I have in some cases reworded things from the original PEP document to try to simplify and clarify, but we can hew closer to the original spec text if that's preferable.
For example, I simplified the section which defines Dependency Group Includes: the spec defines
Dependency Object Specifiers, the class of tables inside of dependency groups, and then defines one type ofDependency Object Specifier: aDependency Group Include. I think that phrasing is good for the original PEP, which wants to lay out the idea that we could define other table types in the future, but not necessarily useful for someone who wants to just read and implement the spec as it currently stands.In many cases, I very intentionally lifted-and-shifted original PEP text, since we worked hard on it and it's quite good.
Unlike the original PEP, there are not that many examples given here.
I also was uncertain if I should link out to the
dependency-groupspackage instead of or in addition to the smaller and simpler reference implementation from the PEP.📚 Documentation preview 📚: https://python-packaging-user-guide--1623.org.readthedocs.build/en/1623/