-
Notifications
You must be signed in to change notification settings - Fork 0
Reordering and renaming sections in pyproject.toml (and unfortunately a bunch more) #6
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
Conversation
Co-authored-by: Jeremy Paige <ucodery@gmail.com>
cdfd0c6
to
ae4a4aa
Compare
@sneakers-the-rat the highlighting looks cool. i'll go through all of the suggestions first. You will need to rebase this before i can look at it. hopefully the dif then is easier for me to parse! it looks like some files are totally rewritten but i don't think that is actually the case if a rebase happens. |
Lol what on earth happened here. Ok ill rebase in a minute |
…-package-guide into license-pyproject # Conflicts: # tutorials/add-license-coc.md # tutorials/add-readme.md # tutorials/intro.md # tutorials/pyproject-toml.md
…pyproject-toml-sectioning # Conflicts: # tutorials/intro.md # tutorials/pyproject-toml.md
OK Rebased. It looks like more changes than it is because i reordered some sections:
|
huh there's something weird going on here where i rebased off yours just now and it's still not matching a lot of stuff. you know what nevermind. |
i'll just make another one. there is still some stuff that i think is worth tidying but don't rly care if it happens in this PR or not :) |
Part of: pyOpenSci#181
Sorry this has so much in it, basically pick and choose what you want :)
ToC structure
Main thing is restructuring ToC to have a section for each field we are adding to the file so they are plainly visible as a group and can be scanned quickly. The ToC gives context to individual sections, so while we are in the "adding fields to our pyproject.toml" section, the subsections are basically a list of the fields we are adding, so we can abbreviate section headings to make them easier to scan.
Previously:
This PR:
So making top-level sections: what is pyproject, adding sections, done!, publish, appendix.
Ordering
I also
pyproject.toml
to be part of the appendix since it is itself an example.Version pinning
I haven't really seen a package in the wild that leaves most of its versions wide open without even a lower bound, and I think it is an important concept to introduce as like "you need to know when and why to use these" rather than "don't use these." I wrote a few paras that should be a relatively uncontroversial take on lower bounds being the default, and then made the admonition more specific about pinning exact versions being bad to do.
Additionally, i understand the term "pinning" to mean specifying a single or very narrow range of versions, like you usually say that a lockfile pins exact versions, or refer to a package's dependencies as being "pinned" when they are narrower than you want them to be. So changed languaged to reflect that: "pydantic pins versions by default" -> "pydantic sets an upper bound by default." I could be wrong about that but ya as with the rest of this, take it or leave it!
Updating example
pyproject.toml
throughout sectionsI added an "in progress"
pyproject.toml
to most sections, and enabled theattrs_block
extension to highlight the sections we just added, eg:toml formatting
I tried to demonstrate clear TOML formatting throughout, and that could be something to be consolidated in the "what is toml" section, but i sort of like introducing the concepts when they are applicable (eg. multiline strings for long descriptions, arrays of tables for authors, etc.)