Final series lessons - pyproject, code of conduct & license files #181
Conversation
lwasser
changed the title
tutorials/intro.md
Outdated
|
|
||
| :::{toctree} | ||
| :hidden: | ||
| :caption: Citation, License & Project metadata |
There was a problem hiding this comment.
I thought citation was covered under the README lesson.
There was a problem hiding this comment.
it is! The navigation now looks like this:
i suspect that i hadn't rebased this PR on top of the readme pr maybe? but if i'm missing a change that you're suggesting, please let me know!
There was a problem hiding this comment.
is the language used confusing for the section header relative to the page link names perhaps?
There was a problem hiding this comment.
Maybe:
Project information files & metadata
- Add README file
- Add a citation
- Add a license
- Add a Code of Conduct
- Update metadata in pyproject.toml
There was a problem hiding this comment.
yes yes, particularly the last thing adding specific mention of pyproject.toml, i suggested some ToC stuff here lwasser#6
There was a problem hiding this comment.
ok perfect y'all. these are good suggestions.
is this suggesting adding the code of conduct as a separate (short) tutorial? Because as is i don't believe we can create links to sections within a document and the COC page is combined with the license given they are short. we could separate them however and just have short succint lessons on each page.
| "Source" = "https://github.com/pyopensci/pyosmeta/" | ||
| ``` | ||
|
|
||
| ## Putting it all together - your completed pyproject.toml file |
There was a problem hiding this comment.
I'm not sure how much value this is adding immediately before the Appendix, where another, different, full pyproject.toml is shown.
There was a problem hiding this comment.
i hear you. so one of them is fully commented and the other is just a cleaned file. i find it hard to look at a file with a lot of comments personally. but if you're modifying it the comments might help.
What do you think about adding one of them as a drop down example which users can optionally open? and we'd want to make them the same just one is commented and the other isnt.
There was a problem hiding this comment.
I like the idea of a drop down. I think at least I'd add a heavy dividing header. But maybe better to hear from someone who is new to this.
There was a problem hiding this comment.
Since this guide is intended for newbies (i think elsewhere we have a more reference-style guide?) i think it would be helpful to have a running pyproject.toml that highlights the changed sections, suggested one version here: lwasser#6
so then at the end we have the completed pyproject.toml file as a continuation of that, and then the annotated version can be moved down to the bottom as an appendix where it won't be in the way of scrolling <3
There was a problem hiding this comment.
@sneakers-the-rat can you please rebase that pr? there are a lot of changes from the review
|
@all-contributors please add @xmnlab for code, review, tutorial |
|
I've put up a pull request to add @xmnlab! 🎉 |
lwasser
force-pushed
the
license-pyproject
branch
from
c09d5cc to
8afe183
Compare
There was a problem hiding this comment.
First of all let me say that as always I love reading @lwasser 's writing, there's just this certain sense of exuberance that permeates the whole thing. I get the feeling of "please let me tell you everything you need to know however you want to know it," like as a reader i feel a great deal of care, and i love it!
My biggest comment here is that the pyproject.toml page coming at the end of the tutorial is odd to me - it's discussed in the first pages, and so the detail coming at the end seems out of order. I like the "quickstart" nature of the "make a package, don't worry too much about pyproject.toml" for now, but then maybe this should come after "make your code installable" as like a "now you have your package, what else can you do in its metadata?
I'm going to make a few more PRs with some cleanup stuff, these comments are just the things that i have questions/comments about <3
Thanks as always for everyone's work here
| 1. How to select and add a `LICENSE` file to your package repository with a focus on the GitHub interface. | ||
| 2. How to add a `CODE_OF_CONDUCT` file to your package repository. | ||
| 3. How you can use the Contributors Covenant website to add generic language as a starting place for your `CODE_OF_CONDUCT`. |
There was a problem hiding this comment.
I like this structure! Can we consolidate the "choose a license" parts at the top, and then in the rest of the tutorial we can simplify like "now that you know what your license is going to be, here are the ways you can add it"
tutorials/add-license-coc.md
Outdated
| [We discuss licenses for the scientific Python ecosystem in more detail here in our guidebook.](permissive-license) | ||
| ::: | ||
|
|
||
| ### Where should the LICENSE file live & how do you add it? |
There was a problem hiding this comment.
I think we should probably start with an overview of where the license is set
- the
LICENSEfile is the literal license attached to your project pyproject.tomldefines the license metadata as an OSI abbreviation
then the sections go
- select a license
- get the text of the license and its abbreviation
- adding license to repository through GH/manually
- adding license to pyproject.toml
There was a problem hiding this comment.
i like this. thank you! i feel like explaining what a license is first however is important. I did reorganize things however but kept that overview first!
There was a problem hiding this comment.
totally yes, "what is a license," "select a license" "implement a license" sounds like a good order
There was a problem hiding this comment.
ok great. i'm going through this one last time, i'll merge and then those 6 pr's you opened - i don't want to lose that work. so if you can open them against main here rather than in my fork that would be super awesome!
| ::: | ||
|
|
||
|
|
||
| ### About the .toml format |
There was a problem hiding this comment.
are we giving a brief .toml tutorial here? this seems like something that should come at the first mention of pyproject.toml if we want it, and then we might want to give some side-by-side comparison of a TOML table and how it might look as a python dict (assuming ppl making packages will have seen a python dict) to ground intuition?
There was a problem hiding this comment.
This is directly after the section :
what is a pyproject.toml file.
The goal of the section isn't to provide a tutorial on toml, but rather help users understand what the format is.
we then link to the toml website which has some nice detailed information about the format.
There was a problem hiding this comment.
nice! got it. sorry above i meant "first mention" as in the 1-installable-code tutorial, but what you say about ppl landing on different pages is totally correct, my bad :)
There was a problem hiding this comment.
ahhhhh ok i follow now. no worries. it's not bad or good i just am hopeful that we can capture folks and help direct them regardless of where they enter the lessons. but this is a work in progress. if as we use them and read them more we want to reorganize we totally can! i REALLY appreciate all of your feedback and thought on this!
| @@ -0,0 +1,527 @@ | |||
| # Make your Python package PyPI ready - pyproject.toml | |||
There was a problem hiding this comment.
Predictably, i want to make some adjustments to the ToC structure here - i'll make a PR, but yes! make ToC easy to scan and use hierarchy to group ideas. i rly like this page i just want to make it easier to see how good it is!!!
There was a problem hiding this comment.
of course. i'll read through your comments below and see what i can implement now vs later when you submit a pr!!
tutorials/pyproject-toml.md
Outdated
| If you wish to learn more about the `pyproject.toml` format, [check out this page. ](../package-structure-code/pyproject-toml-python-package-metadata.md) | ||
| ::: | ||
|
|
||
| :::{dropdown} Click for lesson highlights |
There was a problem hiding this comment.
I was sort of expecting a summary of the page contents here for 'lesson highlights', but this seems to be a guide to the project and build-system sections?
I would expect something like:
- Background on
pyproject.toml(link to first sections) - Project metadata (link to project metadata section)
- Classifiers (flavor description and link).
- Dependencies (...)
etc.
There was a problem hiding this comment.
ahhhh... that idea of this section was the quick take aways for the lesson rather than the outline of sections which is on the right hand side of the page. so the take aways. Would writing lesson take aways make that more clear. i figured a small list of bullet points for people to understand the important elements of that file that they should focus on.
and really the project and build systems at this point are the critical 2 pieces. does that make sense? or how does that land?
tutorials/pyproject-toml.md
Outdated
| :::{admonition} Author names & emails | ||
| :class: note | ||
|
|
||
| There is a quirk with PyPI for authors that have names but not emails in the pyproject.toml. If you don't have emails for everyone, we suggest that you only add names. |
There was a problem hiding this comment.
i'm not sure what this means! you mean like if you have some authors with emails and some without, then there is a problem? what is the problem? maybe an example here too?
There was a problem hiding this comment.
oh yes - i found this with stravalib. i didn't have emails for all maintainers and if you list one maintainer with an email and others without it doesn't render properly. or atleast it didn't when i was playing with it. i'll try to clarify
There was a problem hiding this comment.
ok i've updated with examples!!
Co-authored-by: Jeremy Paige <ucodery@gmail.com>
lwasser
force-pushed
the
license-pyproject
branch
from
cdfd0c6 to
ae4a4aa
Compare
lwasser
changed the title
|
ok y'all. i've made a bunch of changes. @sneakers-the-rat the plan is to merge this today. IF you are busy and can't rebase those other pr's then what we can do is i can merge it and you can submit the pr directly to this repo to the main branch and we can review next week!! i'll leave this open until the end of the day with the plan of merging this evening sometime after 5pm mountain time! |
|
ok friends. i made a lot of structural changes to the content (including adding that amazing highlighting mst plugin - wow !!). so things are much more organized now. i'll let this sit (i have a meeting to go to in just a bit) for a few hours with the plan of merging it this evening after my last meetings. @sneakers-the-rat i will look at the pr's - i just noticed there are a bunch in my fork. we can either rebase or submit directly to the main branch here for easier merging. i suspect some of them might have been before i rebased my branch but i could be wrong there too! i did integrate some of your suggestions - like the code highlighting in the pyproject.toml file here already!! it's SO MUCH BETTER with that - adding to the file in each step. wow. |
|
Oh ya i was PR'ing to |
| maintainers = [{ name = "Firstname lastname", email = "email@pyopensci.org" }, { name = "Firstname lastname", email = "email@pyopensci.org" }] | ||
| ``` | ||
|
|
||
| :::{dropdown} Learn More: What's the difference between author and maintainer in open source? |
There was a problem hiding this comment.
I had this in my PR, but i feel like this should come right after the bullet point list of description, authors and maintainers. since it's a dropdown, if they dont care they can cruise past it, but otherwise it's like "idk what those are" until the end of the section
|
|
||
| ### What license should you use? | ||
|
|
||
| We suggest that you use a permissive license that accommodates the other most commonly used licenses in the scientific Python ecosystem (MIT[^mit] and BSD-3[^bsd3]). If you are unsure, use MIT given it's the generally recommended |
There was a problem hiding this comment.
I know that this is a guide for beginners, and probably not for this PR, but i also feel like we would be sorta remiss in not at least talking about why copyleft licenses exist and why they are important, particularly given the historical moment. We are pretty strongly selecting for audience, and also steering newbies towards "make sure your code can be gobbled up by corporations easily" without providing the alternative. I'll make a separate PR to the main repo about this, but I think it's important to cultivate a new generation that understands the importance of the free part of free and open source software
There was a problem hiding this comment.
this sounds great! we have a license guide type of page in the guidebook as well and this type of content might also be really useful there and we could link to it from a tutorial. but yes a separate pr would be great about copyleft and what licenses mean in terms of corporate / for profit vs open use / FOSS
i'm really sorry about that @sneakers-the-rat i think what happened is i didn't see those pr's at all and i'm not used to that workflow with this community. not that it isn't ok i just didn't think to look at my fork. i was so focused on the comments in this pr that i wasn't paying attention to my fork. When you mentioned pr's i just thought perhaps they would pop up here. that is my mistake in missing those. i do want your feedback so please don't think i was ignoring the work you did there. i just literally missed it amid everything else going on. please know that i feel really bad about that but would love pr's directly here! |
Co-authored-by: Jonny Saunders <sneakers-the-rat@protonmail.com>
|
@lwasser you are all good - i should have flagged those more clearly. I split them up and redid them, and if you want to merge this now then np we can change the base discuss them separately :) edit to avoid the same problem again lmao those are |
|
ok friends. i am going to MERGE this pr!! This is a huge milestone as it's the final touches to the first set of pyOpenSci tutorials!! We can improve / fix / enhance from here. i'll also create a new release of the guidebook in the upcoming week or two that should include all of the new contributors. Please stay tuned for that. |
|
ok @sneakers-the-rat yes let's look at this here via pr's to the main branch. thank you so so much for this work. i just wanted to get this big pr merged and then we can look at all of the changes you have suggested together. many many thanks!! |
|
Nice job team ♥ |
This is the last in the first packaging series of lessons to review. once these are merged we will need to run through the entire set to ensure it's coherent! especially with the move to hatch :)