Fix: Update scope document and also fix a few sphinx bugs #162
Conversation
| @@ -18,8 +18,6 @@ Currently, the packages that pyOpenSci reviews also need to fall into the | |||
| technical and applied scope of our organization. This scope may expand over time | |||
| as the organization grows. | |||
|
|
|||
|
|
|||
|
|
|||
| ## Is Your Package in Scope For pyOpenSci Review? | |||
There was a problem hiding this comment.
@eriknw @NickleDave @arianesasso @cmarmo @sneakers-the-rat @Batalex i'd LOVE your input on these changes. this page is really the only one you have to look at in this review. the rest of the changes are just link fixes and cleanup.
Many thanks in advance for this!
Co-authored-by: Alex Batisse <[email protected]>
Co-authored-by: Alex Batisse <[email protected]>
Co-authored-by: Alex Batisse <[email protected]>
|
TODO: There are still two COC broken links: External link https://www.pyopensci.org/software-peer-review/CODE_OF_CONDUCT.html failed (status code 404)
all COC links should go to governance/CODE_OF_CONDUCT.html now |
| may not be in-scope today. We strive for consistency in our peer review process. However, we also evaluate packages on a case-by-case basis. | ||
| In some cases exceptions are made. | ||
| ``` | ||
|
|
There was a problem hiding this comment.
NOTE: i think we should add a policy around telemetry in packages. a current review has it. i think we should discourage against it but if it's required make it opt in rather than opt out preferred?
We should also evaluate whether we want to review general data manipulation and coding tools. ROS does not review these tools. but defining what that means is tricky.
There was a problem hiding this comment.
Perhaps start with a narrower scope? It's easy to broaden it later, but not the other way around.
There was a problem hiding this comment.
good point! is this a specific comment related to our scope as defined now or just to that statement above? I added that given Ropensci has similar language and it just allows us to adjust in the future in case we realize we are headed down a rabbit hole that doesn't work for us! (kind of like a legal disclaimer :) in case we need to modify scope)
We've had the same scope for the past 4 years BUT of course we are being more specific now about each category given all of the questions we've gotten :)
about/package-scope.md
Outdated
|
|
||
| ### Data processing & munging | ||
|
|
||
| Data munging tools are tools that support processing data discussed above. This |
There was a problem hiding this comment.
Is it worth giving a definition of munging here, or linking to one? (like https://en.wikipedia.org/wiki/Data_wrangling) Something like "transforming data in a way that makes further analysis possible" (e.g. Physcraper updating local phylogenies with publicly available data)
There was a problem hiding this comment.
absolutely - want to fix inline please?
about/package-scope.md
Outdated
| considering whether open-source options exist. | ||
|
|
||
| <!-- TODO: need an example for this category --> | ||
| * Examples: We don't have a package in this category yet - *Could be your package?* |
There was a problem hiding this comment.
Isn't pyGMT an example? Because it wraps GMT.
There was a problem hiding this comment.
i think so. pyGMT actually fits into several of our categories i think i just placed it in one. but if we implement your suggestion above then we demonstrate that a package can be in several categories. i'm fine with that!
Co-authored-by: David Nicholson <[email protected]>
Co-authored-by: David Nicholson <[email protected]>
Co-authored-by: David Nicholson <[email protected]>
Co-authored-by: David Nicholson <[email protected]>
Co-authored-by: David Nicholson <[email protected]>
Co-authored-by: David Nicholson <[email protected]>
Co-authored-by: David Nicholson <[email protected]>
Co-authored-by: David Nicholson <[email protected]>
Co-authored-by: Yuvi Panda <[email protected]>
Co-authored-by: Stefan van der Walt <[email protected]>
|
@all-contributors please add @yuvipanda for code, design, review |
|
I've put up a pull request to add @yuvipanda! 🎉 |
|
✏️ second round of feedback is welcome on this PR by 20 feb 2023 at midnight mountain time (for those in other time zones that will be in the morning for ya!). i'll plan to merge around 21 feb 2023 (depending on how long it takes to work through edits!). Many thanks y'all. i think our policies are coming together nicely. |
about/package-scope.md
Outdated
| data lifecycle. Packages submitted to pyOpenSci should fit into one or | ||
| more of the categories below and should be within our technical scope. | ||
|
|
||
| ```{admonition} Package Use Metrics Are Not a Requirement for Review |
There was a problem hiding this comment.
This suggests "we don't need you to go and measure your package use (but we may consider how much it is used)". Rather: "Widespread package usage is not required for review", "We review independent of popularity", or similar?
There was a problem hiding this comment.
many thanks @stefanv fixing. @NickleDave i think had similar feedback here and i haven't been able to get it right!
There was a problem hiding this comment.
is this any better :
Your Package Does Not Need to Have Widespread Use to be Reviewed
:class: important
We review packages across a spectrum of small to large user bases. The popularity of your package is not a consideration in our review process!
There was a problem hiding this comment.
Sounds good to me!
nit: would maybe say it like "Your Package Does Not Need to Be In Widespread Use Yet to be Reviewed" or "Your Package Does Not Need to Be Widely Used to be Reviewed"? ("in use" not "have use")
There was a problem hiding this comment.
this was merged a few hours ago... would you be open to creating a PR for this - i'm fine with cleaner wording.
There was a problem hiding this comment.
Yup, sorry, was catching up with replies
about/package-scope.md
Outdated
| As such, the number of GitHub stars or PyPI / Conda | ||
| downloads is NOT considered as a part of our scope evaluation. |
There was a problem hiding this comment.
This is very explicit, but unsure it adds much content.
There was a problem hiding this comment.
If you're worried about users being confused at this point already, perhaps it's worth clarifying WHY you are reviewing in the first place. It's not to establish how useful a package is, but how well it is put together. This is a subtle change of emphasis on the "we only consider" clause above.
There was a problem hiding this comment.
ok and now i'm here -
We review packages with the goal of improving package quality and usability for scientists.
As such, we review packages across a spectrum of small to large user bases. The popularity of your package is not a consideration in our review process!
When we evaluate whether you package is within our scope, we only consider:
- how the package is developed and
- how the package relates to and supports the broader scientific ecosystem
We welcome young packages that are just entering the scientific Python
ecosystem to apply for review if they are relevant to the science community and
fit into at least one scope category below. We also welcome mature packages with
a growing or established community!
| may not be in-scope today. We strive for consistency in our peer review process. However, we also evaluate packages on a case-by-case basis. | ||
| In some cases exceptions are made. | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Perhaps start with a narrower scope? It's easy to broaden it later, but not the other way around.
|
|
||
| ## Domain areas | ||
|
|
||
| In addition, our scope includes focused domain areas. These areas are based on |
There was a problem hiding this comment.
The "computational library" class, described here, seems to be missing from the previous section, when it's arguably the first category included?
There was a problem hiding this comment.
Say a little bit more about what you mean?
I think you're suggesting that there should be another category above that's like "general library or framework for a domain or research area"?
E.g. python-graphblas would be such a library (in addition to being a wrapper)
There was a problem hiding this comment.
ugh... i missed a few comments here! i will make sure these are added in a separate PR. i am not sure how i missed this
|
|
||
| ## Domain areas | ||
|
|
||
| In addition, our scope includes focused domain areas. These areas are based on |
There was a problem hiding this comment.
Say a little bit more about what you mean?
I think you're suggesting that there should be another category above that's like "general library or framework for a domain or research area"?
E.g. python-graphblas would be such a library (in addition to being a wrapper)
Co-authored-by: David Nicholson <[email protected]>
Co-authored-by: David Nicholson <[email protected]>
Co-authored-by: Stefan van der Walt <[email protected]>
Co-authored-by: David Nicholson <[email protected]>
about/package-scope.md
Outdated
| ``` | ||
|
|
||
| ### Telemetry & user-informed consent |
There was a problem hiding this comment.
I am going to pull this into it's own PR so we can link it explicitly to the open issues and discussion.
|
ok y'all... merging this and will open a NEW pr with telemetry in it. we can always edit this further as we need to - even in the other PR on telemetry when i open it!! many thanks for all of the feedback!!! |
This pr does a few things
I would love to merge this by 9 feb 2023 if possible.