PAGE: how to submit a package to pyOS #424
Conversation
|
pre-commit.ci autofix |
|
it looks like lychee is unhappy with the link for the website not existing yet. I know we fixed it for htmlproofer, and it is working on my latest blog post: #425 I'm wondering if the fix was somehow only applied to blog posts? |
|
nice job with this pr @kierisi !! i see lychee found 2 url issues.
i believe there is a |
_pages/how-to-submit.md
Outdated
| @@ -0,0 +1,212 @@ | |||
| --- | |||
| layout: splash | |||
There was a problem hiding this comment.
@kierisi i lied - one more comment outside of a content review - you mentioned the TOC... can you try one more thing. i suspect the TOC isn't available for the splash page layout. this is because that layout is a flowing layout not intended to have indexable sections. Try to make this a "single" layout page and see what happens. you can always use the wide class like we do with blogs.
There was a problem hiding this comment.
@lwasser that did it! I commit those changes and it should be formatted now.
Co-authored-by: Leah Wasser <leah@pyopensci.org>
There was a problem hiding this comment.
ok @kierisi this needs some work. a few high level points:
- please only use h2-h4/5 tags. from a SEO perspective and a markdown perspective this is preferred.
- This is more a how to fill out the form mixed with some tutorial elements rather than a how to that provides context for the sections in terms of our values and mission and the peer review program goals. id like to see more of our values and mission threaded in to the explanation of each section.
- the overall organization is difficult to follow. i think it would be nice to have steps - and maybe clump sections of the template together if they are related. i kept reading from the top and wanted the "how to" to begin. but it feels like ths structure dives into tutorial mode in some places (the markdown and labels for example) and how to mode (when you talk about check boxes). I think we want to lean into how-to here vs tutorial.
- finally i think it's worth rethinking the header structure overall so it's a bit more clear. the top could provide context about peer review and then link to resources that we have on peer review. but then quickly we want to get to the x steps for submitting. maybe 5-7 steps total?
for the last item - i'd suggest pulling together a single outline in another doc that helps structure the entire page given the feedback i've provided here and below.
_pages/how-to-submit.md
Outdated
|
|
||
| > Looking for help creating a Python package? Check out [the pyOpenSci Package Guide](https://www.pyopensci.org/python-package-guide/), which will walk you through the process, start to finish. | ||
|
|
||
| # <i class="fa-solid fa-circle-chevron-down"></i> Why you should submit to pyOpenSci's open peer review process |
There was a problem hiding this comment.
I suspect this content came from our website (which now that i'm reading it could be updated). please correct me if i'm wrong.
i would grab info from here on the why
https://www.pyopensci.org/software-peer-review/about/our-goals.html
this doesn't really cover why peer review is important.
it's about helping scientists find vetted maintained and well documented software and also increasing the quality of that software and standardization over time.The our goals page i think breaks things down in a more meaningful way. if you got this information from the website it could be worth opening an issue and potentially a pullr equest to update the website so it too is more. meaningful in terms of explaining the "why submit" part.
|
|
||
| # <i class="fa-solid fa-circle-chevron-down"></i> Why you should submit to pyOpenSci's open peer review process | ||
|
|
||
| pyOpenSci's peer review process is run by a team of dedicated volunteers, and provides the opportunity for package maintainers to have their code, documentation, and infrastructure vetted by both domain experts as well as Python experts. Because pyOpenSci invests in recruiting a diverse team of editors and reviewers, our review process provides and enhanced feedback experience. |
There was a problem hiding this comment.
This paragraph is nice - but it really should be in the context of
our open peer review process is community run or community lead. so focusing on the fact that it's not just volunteers. its people who care deeply about scientific Python and better software and who are actually leading the peer review process. Please ask questions if my comments aren't clear!
|
|
||
| pyOpenSci's peer review process is run by a team of dedicated volunteers, and provides the opportunity for package maintainers to have their code, documentation, and infrastructure vetted by both domain experts as well as Python experts. Because pyOpenSci invests in recruiting a diverse team of editors and reviewers, our review process provides and enhanced feedback experience. | ||
|
|
||
| In addition, pyOpenSci's partnership with the [Journal of Open Source Software](https://www.pyopensci.org/software-peer-review/partners/joss.html) means that if your package is accepted by pyOpenSci and in scope for JOSS, it will be fast-tracked through JOSS’ review process. |
There was a problem hiding this comment.
This is great but i think we can describe this as... the other benefit is if you submit you can get a publication too through our partnership with JOSS. so lead with the beneft to the author which is publication. and maybe we can make that a subheading.
So this entire section i think we could rework to have something more like 5 benefits of submitting your package to pyOpenSci or something where the benefits are clearly stated and then explained as bullet points. And the language focuses on the benefit to both the author and another scientist who might want to use their package (but also may not know about it).
i also suggest using the graphic that i created for the scipy / open planetary meeting that shows the partnership and joss outputs in a diagram form!
| When submitting to pyOpenSci, there are several criteria we use to evaluate if the package is in-scope for our review process: | ||
| 1. Package maintenance: we understand that life happens, but we ask that you commit to maintaining your package for at least 1-2 years after the pyOpenSci review process is complete. | ||
| 2. Your package should meet all of the initial Editor checks, which include: | ||
| - **Installation:** the package can be installed from a community repository such as PyPI (preferred), and/or a community channel on conda (e.g. conda-forge, bioconda). |
There was a problem hiding this comment.
I like that this checklist is here for reader convenience but i think we should remove it because it will become a maintenance burden. If we make small changes to our pre-review checks, then we will have to remember to update it here too.
i suggest that instead your broadly summarize what the pre-review checks are (we are callign them pre-review now rather than EIC checks. then link to the list of checks so we have one location that is always up to date that a reader can trust vs two locations that are bound to be out of sync at some point
| - **Version** (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)? | ||
| - **Survey:** the initial onboarding survey was filled out. | ||
|
|
||
| You can get more details about each of these criteria in our [Authors Guide](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html). |
There was a problem hiding this comment.
that checklist is in the author guide too and this is a great link to have here! just double check that it is :)
in that guide i was able to use includes of a single md file. If we can use an eternal include file in jekyll (i have no idea if this works) we could try that.
https://github.com/pyOpenSci/software-peer-review/blob/main/appendices/editor-in-chief-checks.md
BUT, an include also may not work so a link with a brief text summary if fine!
also i suggest a short explanation of why we have these checks
- the checks are about slowly standardizing the quality of packaging in our ecosystem. So once a package meets these initiaul checks, it's very likely they will pass review. they are a baseline that we want to see with the goal of making packages more maintainable (better infra), usable (better docs), and discoverable (after we accept it into our ecosystem its promoted here)
|
|
||
| ### Are you OK with Reviewers Submitting Issues and/or pull requests to your Repo Directly? | ||
|
|
||
| You'll notice that the section on having reviewers submit requested changes as issues to your package repositories is already checked. You do have the option of un-checking it, but we consider the benefits of this to be that people can contribute to your review repos. Open issues, PRs, etc. all help you as a maintainer, while also giving you the opportunity to address any issues via PR links. |
There was a problem hiding this comment.
Can you please re-read and reword a bit? id lead with the benefits / the why this section is there. Then tell them if they don't want issues and pr's they can uncheck it. as written it seems to combine these messages in a hard to digest way.
we like to use the open source approach to github where ever we can. so linking issues and pr's to a review just makes the entire process more transparent in the spirit of our values. it also can help the maintianer directly if a pr is submitted!
|
|
||
| ### Please fill out our survey | ||
|
|
||
| We know that surveys aren't necessarily your favorite thing to do, but completing the [pyOpenSci pre-review survey](https://forms.gle/F9mou7S3jhe8DMJ16) is a huge help to our team of volunteers, future package authors, and pyOpenSci as an organization. It helps us track submissions as well as continuously improve our peer review process. |
There was a problem hiding this comment.
Id lead with the positive. pyOpenSci is a non profit organization that deeply cares about improving our volunteer lead peer review process. Your feedback both before and after the review helps us.... more here...
Then thank them for their timing in helping us.
|
|
||
| ### Editor and Review templates | ||
|
|
||
| This isn't a section that you need to worry about! In fact, this is a great time to read through your issue one last time, and hit submit. |
There was a problem hiding this comment.
You could describe briefly why there are there as these are just links for editors and reviewers.
|
|
||
| ## <i class="fa-solid fa-hourglass"></i> What’s next: what happens after you submit your package for review | ||
|
|
||
| Now that you've submit your package to pyOpenSci's peer review process, you can relax for a bit. Our Editor-in-Chief will review your submission for both its scope and infrastructure, and determine whether or not it's a good fit for pyOpenSci. This process generally takes about two weeks, but may be shorter or longer depending on how many packages pyOpenSci currently has in review. The Editor-in-Chief will also use this time to ask for any necessary changes that may need to be made to your package, as well as give you time to implement them. |
There was a problem hiding this comment.
| Now that you've submit your package to pyOpenSci's peer review process, you can relax for a bit. Our Editor-in-Chief will review your submission for both its scope and infrastructure, and determine whether or not it's a good fit for pyOpenSci. This process generally takes about two weeks, but may be shorter or longer depending on how many packages pyOpenSci currently has in review. The Editor-in-Chief will also use this time to ask for any necessary changes that may need to be made to your package, as well as give you time to implement them. | |
| Now that you've submit your package to pyOpenSci's peer review process, you can relax for a bit. Our current Editor-in-Chief will review your submission for both its scope and infrastructure, and determine whether or not it's a good fit for pyOpenSci. This process generally takes about two weeks, but may be shorter or longer depending on how many packages pyOpenSci currently has in review. The Editor-in-Chief will also use this time to ask for any necessary changes that may need to be made to your package, as well as give you time to implement them. |
There was a problem hiding this comment.
it would be nice to add links to the EiC page in the guidebook here.
|
|
||
| Now that you've submit your package to pyOpenSci's peer review process, you can relax for a bit. Our Editor-in-Chief will review your submission for both its scope and infrastructure, and determine whether or not it's a good fit for pyOpenSci. This process generally takes about two weeks, but may be shorter or longer depending on how many packages pyOpenSci currently has in review. The Editor-in-Chief will also use this time to ask for any necessary changes that may need to be made to your package, as well as give you time to implement them. | ||
|
|
||
| Once the Editor-in-Chief has decided to move ahead with your package, we begin the review process with both editors and reviewers. On average, this takes approximately three months, but this timeframe can vary considerably depending on the package. You can read the detailed steps of what happens during the peer review process in the [pyOpenSci Peer Review Guide for Python Open Source Authors](https://www.pyopensci.org/software-peer-review/how-to/author-guide.html). |
There was a problem hiding this comment.
thanks for the feedback! for reference, this was the outliner document I had created and incorporated your initial feedback on, and this is what I used to build out the page. it seems like things have shifted quite a bit, so I'll work on re-structuring, re-organizing, and re-writing this. I anticipate this taking me until about September 6th to get a revised draft up. |
|
That sounds good. I suspect that we will see very different outcomes when we each look at that outline. I look forward to the next update. |
|
converted to a draft while I work on updates! I'll flag for re-review once ready. |
Hey, there, @kierisi, I am checking in on the progress of this PR. How are things going? |
@lwasser OK, I think I sorted things out on my end - thanks for walking me through that! and let me know if things are still wonky 🥹
I've got the header image working (yay!) but the TOC isn't showing. I'm guessing there's something under the hood to enable it, or if there's another way to get the same effect, I'm happy to implement it!