[doc] contributing guidelines #111
Conversation
|
ah yes this is perfect! I literally just sent an email to a collaborator at Berkeley saying "we really need to make a contributing guide + CoC for jupyter book" :-) One thing that we should add once this PR gets merged is a short description of the repository itself, the tools used, etc, in order to help people get situated. What do you think? (I'll hold off on reviewing until this is no longer in "draft" mode |
|
Ah, sorry, I had it in draft since it's an RFC ! Having your feedback would be great. Re description: yes, absolutely ! I think we just need to figure out the "shortest path" way that folks get started and recommend that :) |
| * [][link_enhancement] *These issues are asking for enhancements to be added to the project.* | ||
|
|
||
| Please try to make sure that your enhancement is distinct from any others that have already been requested or implemented. | ||
| If you find one that's similar but there are subtle differences please reference the other request in your issue. |
There was a problem hiding this comment.
What are your thoughts on "good first issue" @emdupre ? I like the idea of having a relatively small number of total issue tags, so don't wanna suggesting adding a new one if it'll just add noise!
There was a problem hiding this comment.
I think that's a great tag ! It's nice to demarcate that some issues are looking for new contributors of any experience level vs ones where you specifically think a newcomer could easily hop on. Will add it here.
CONTRIBUTING.md
Outdated
| * **[WIP]** for changes which are not yet ready to be merged | ||
|
|
||
| Pull requests should be submitted early and often! | ||
| If your pull request is not yet ready to be merged, please also include the **[WIP]** prefix. |
There was a problem hiding this comment.
For this one maybe we should start instructing folks to use the github "draft PR" feature?
There was a problem hiding this comment.
I still have confusion around its uses myself, clearly ! 😆
But I can definitely update these guidelines to use it which will hopefully resolve some(one else's) ambiguity.
| ## Recognizing contributors | ||
|
|
||
| We welcome and recognize all contributions from documentation to testing to code development. | ||
| You can see a list of current contributors in the [contributors tab][link_contributors]. |
There was a problem hiding this comment.
What's the process by which somebody becomes a contributor? I think I'm fine with just growing the list very liberally (e.g. after someone has been a regular commentor, or after one or two PRs). What do you think about this?
There was a problem hiding this comment.
Right now I have it just pointing to the contributor github tab. The downside to this is that it doesn't actually recognize any contributions that aren't code or docs !
If we create a separate humans.txt (or zenodo or something similar), I'd say that it's hard to come up with firm guidelines across all the different possible contribution types, so maybe encourage folks to add their name after some sustained or significant engagement ? TBD what that means to you.
There was a problem hiding this comment.
fair enough - how about we cross the bridge of "offically listing contributors" later on...I think that's a complex topic and I don't want it to block this big improvement in suggesting to folks how they can get involved!
|
a couple quick comments! For the CoC, I think we should also abide by the Jupyter CoC |
|
Thanks for the review, @choldgraf ! I've updated to address your comments (at least the ones I felt like I could address at this point). Always happy for another look through :) |
I just realized that one other tag that might be useful is "question"
|
hey @emdupre , it looks great to me. I added one extra point in your PR to include the "question" tag, but other than this I think it looks good! I added you as an admin on the project, so if you are happy with my changes please feel free to self-merge this one! Or I'll merge a bit later today if you haven't gotten to it :-) |
|
Perfect, thanks ! One last question before merging: do you want contributors to also post on the Jupyter discourse page ? Or restrict to github issues ? |
|
for now let's keep it to github issues (though I'm fine with people posting on discourse, it is technically just for jupyterhub / binder right now since it is in a pilot phase. I'd love for the broader jupyter community to use it but that's a community decision :-) |
|
Amazing -- merging then ! 🚀 |
* adding edit buttons * adding baseurl docs * fixing broken links in pdf build
Closes #99.
This is an initial commit of contributing guidelines, based largely on guidelines we use in tedana.
As a non-core developer, it'd be great to make sure this contributing process actually aligns with your expectations ! There's also some missing information here, which I'm not sure if jupyter-book yet has answers to:
Do we have a recommended testing process? I'm working on making a Dockerfile today and was planning to recommend that. But if there are other, better suggestions, it'd be great to have those !EDIT: pending discussion in Explore using another SSG (Nikola, Hugo, Gatsby?) to build the site #83Thanks ! ✨