Skip to content

Commit 06722d7

Browse files
lwasserarianesasso
andcommitted
Edits on massive overhaul of peer review guide
Update software-peer-review-guide/editors-guide.md Co-authored-by: David Nicholson <[email protected]> Update software-peer-review-guide/editors-guide.md Co-authored-by: David Nicholson <[email protected]> Apply suggestions from code review Co-authored-by: David Nicholson <[email protected]> Update about-peer-review/how-peer-review-works.md Co-authored-by: Alexandre Batisse <[email protected]> Update about-peer-review/code-of-conduct.md Co-authored-by: Ariane Sasso <[email protected]> Update about-peer-review/how-peer-review-works.md Co-authored-by: Ariane Sasso <[email protected]> Update about-peer-review/how-peer-review-works.md Co-authored-by: Ariane Sasso <[email protected]> Update about-peer-review/how-peer-review-works.md Co-authored-by: Ariane Sasso <[email protected]> Update about-peer-review/intro.md Co-authored-by: Ariane Sasso <[email protected]> Apply suggestions from code review Co-authored-by: Alexandre Batisse <[email protected]> Co-authored-by: Ariane Sasso <[email protected]> Update about-peer-review/pyopensci-related-joss-ropensci.md Update about-peer-review/pyopensci-related-joss-ropensci.md Co-authored-by: Alexandre Batisse <[email protected]> Update about-peer-review/pyopensci-related-joss-ropensci.md Co-authored-by: Ariane Sasso <[email protected]> Update about-peer-review/pyopensci-related-joss-ropensci.md Co-authored-by: Ariane Sasso <[email protected]> Update about-peer-review/pyopensci-related-joss-ropensci.md Co-authored-by: Ariane Sasso <[email protected]> Update about-peer-review/pyopensci-related-joss-ropensci.md Update about-peer-review/pyopensci-related-joss-ropensci.md Co-authored-by: Alexandre Batisse <[email protected]> Update about-peer-review/pyopensci-related-joss-ropensci.md Co-authored-by: Ariane Sasso <[email protected]> Edits to peer review guide on massive reorganization of guide Edits to peer review guide Co-authored-by: Ariane Sasso <[email protected]> Update appendices/editor-in-chief-checks.md Co-authored-by: Ariane Sasso <[email protected]> Update appendices/pre-review-package-requirements.md Co-authored-by: Ariane Sasso <[email protected]> Update appendices/pre-review-package-requirements.md Co-authored-by: Ariane Sasso <[email protected]> Update appendices/reviewer-request-template.md Co-authored-by: Alexandre Batisse <[email protected]> Update appendices/reviewer-request-template.md Co-authored-by: Ariane Sasso <[email protected]> Update appendices/reviewer-request-template.md Co-authored-by: Alexandre Batisse <[email protected]> Apply suggestions from code review Co-authored-by: Ariane Sasso <[email protected]> Update appendices/package-approval-template.md Co-authored-by: Ariane Sasso <[email protected]> Apply suggestions from code review Co-authored-by: Ariane Sasso <[email protected]> Co-authored-by: Alexandre Batisse <[email protected]> Apply suggestions from code review Co-authored-by: Ariane Sasso <[email protected]> Update software-peer-review-guide/editor-in-chief-guide.md Co-authored-by: Ariane Sasso <[email protected]> Update software-peer-review-guide/editor-in-chief-guide.md Co-authored-by: Ariane Sasso <[email protected]> Update software-peer-review-guide/editor-in-chief-guide.md Co-authored-by: Ariane Sasso <[email protected]> Update software-peer-review-guide/editor-in-chief-guide.md Co-authored-by: Ariane Sasso <[email protected]> Apply suggestions from code review Co-authored-by: Ariane Sasso <[email protected]> Update software-peer-review-guide/intro.md Co-authored-by: Ariane Sasso <[email protected]> Update software-peer-review-guide/reviewer-guide.md Co-authored-by: Ariane Sasso <[email protected]> Apply suggestions from code review Co-authored-by: Ariane Sasso <[email protected]>
1 parent aa83dd9 commit 06722d7

16 files changed

+91
-90
lines changed

about-peer-review/code-of-conduct.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ go there now.](https://www.pyopensci.org/governance/code-of-conduct)
77
## NOTE: we are in the process of moving this file to our governance documentation and making significant changes to our code of conduct.
88

99

10-
- We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, or similar personal characteristic.
10+
- We are committed to providing a friendly, safe and welcoming environment for all, regardless of gender, sexual orientation, disability, ethnicity, religion, age, or any personal characteristics.
1111
- Please avoid using openly sexual nicknames or other nicknames that might detract from a friendly, safe and welcoming environment for all.
1212
- Please be kind and courteous. There’s no need to be mean or rude.
1313
- Respect that people have differences of opinion and that every design or implementation choice carries a trade-off and numerous costs. There is seldom a right answer.

about-peer-review/how-peer-review-works.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ high quality tools
1010
that supports scientists across domains with a suite of different data
1111
types and structures.
1212

13-
### Who reviews pyOpenSci packages ?
13+
### Who reviews pyOpenSci packages?
1414

1515
Our peer review process is run by volunteer members of the Python scientific
1616
community:
@@ -30,22 +30,22 @@ Our entire peer review process occurs on GitHub in the
3030

3131
We use GitHub because:
3232

33-
* It is free to create an account
34-
* Anyone can read the review discussion without an account making the process entirely open
35-
* It facilitates collaboration and supports community around a package
36-
* It facilitates open discussion between reviewers and package maintainers and the pyOpenSci volunteers
37-
* Numerous packages store their code bases on GitHub
33+
* It is free to create an account,
34+
* Anyone can read the review discussion without an account, making the process entirely open,
35+
* It facilitates collaboration and supports the community around a package,
36+
* It facilitates an open discussion between reviewers, package maintainers and the pyOpenSci volunteers,
37+
* Numerous packages store their code bases on GitHub.
3838

3939
### We use GitHub issue templates and labels to organize the review steps
4040

4141
* We use GitHub issue templates as submission templates for new reviews and pre-submission review questions.
42-
* We label issues to track every step of the package submission and review progress (e.g. [1/initial-editor-checks, 2/reviewers-needed, 6/pyopensci-approved](https://github.com/pyOpenSci/software-review/labels)
42+
* We label issues to track every step of the package submission and review progress (e.g. [1/initial-editor-checks, 2/reviewers-needed, 6/pyopensci-approved](https://github.com/pyOpenSci/software-review/labels)).
4343

4444
```{note}
4545
[Click here to read the review thread from a December 2022
4646
pyOpenSci pre-submission issue.](https://github.com/pyOpenSci/software-review/issues/65) Note the conversational
4747
tone of the pre-review. In this case the package was improved
48-
Before the formal review even began.
48+
before the formal review even began.
4949
5050
In the actual review process, two external reviews are important milestones. The editor will also provide the author with some feedback.
5151
```

about-peer-review/intro.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Software peer review refers to a peer-review process that focuses on open source
1010
* Code quality,
1111
* Documentation quality,
1212
* Package usability,
13-
* Test coverage that supports both maintenance of code function. Test coverage also makes it easier for contributors to see how their contributions impacts other parts of the code,
13+
* Test coverage that supports the maintenance of code function. Test coverage also makes it easier for contributors to see how their contributions impact other parts of the code,
1414
* Evaluation of infrastructure such as continuous integration to run rest suites and check code linters, that supports automated checks on pull requests. This infrastructure supports software quality and reliability.
1515

1616
## What types of packages does pyOpenSci review?
@@ -20,7 +20,7 @@ pyOpenSci reviews higher level software packages that support scientific workflo
2020

2121
<img src="../images/python-stack-jupyter-earth.png" alt="Image showing the tiers of software in the python ecosystem starting with Python itself and as you move out packages become more domain specific. In this image packages like xarray and numpy are considered core to scientific python. Packages and distributions like astropy, simpeg and metpy are considered to be domain specific." width="700px">
2222

23-
Diagram showing the tiers of software in the python ecosystem starting with Python itself and as you move out packages become more domain specific. In this image packages like xarray and numpy are considered core to scientific python. Packages and distributions like astropy, simpeg and metpy are considered to be domain specific.. pyOpenSci's review
23+
Diagram showing the tiers of software in the python ecosystem starting with Python itself and as you move out packages become more domain specific. In this image packages like xarray and numpy are considered core to scientific python. Packages and distributions like astropy, simpeg and metpy are considered to be domain specific. pyOpenSci's review
2424
process focuses on domain specific packages rather than core packages as
2525
these packages tend to have more variability in long term maintenance and
2626
package infrastructure and quality compared to established core packages. **Source: ["Jupyter meets earth" project](https://jupytearth.org/jupyter-resources/introduction/ecosystem.html)**
@@ -54,7 +54,7 @@ faced within the scientific Python community are broader in scale given the
5454
numerous and diverse applications that the Python programming language is used for.
5555

5656
```{note}
57-
[This blog post](https://www.numfocus.org/blog/how-ropensci-uses-code-review-to-promote-reproducible-science/) written by editors from our partner organization, rOpenSci, is a good introduction to pyOpenSci software peer review
57+
[This blog post](https://www.numfocus.org/blog/how-ropensci-uses-code-review-to-promote-reproducible-science/) written by editors from our partner organization, rOpenSci, is a good introduction to pyOpenSci software peer review.
5858
```
5959

6060
### Peer review of open source software helps maintain consistent quality

about-peer-review/policies-guidelines.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,11 @@ documentation and usability. The review process
77
is similar to a manuscript review, however it has a stronger
88
focus on Python packaging best practices.
99

10-
Unlike a manuscript review, our peer review process is be an ongoing conversation. Once all major issues and questions are addressed, the review editor package will make a decision to accept, hold, or reject the package.
10+
Unlike a manuscript review, our peer review process is an ongoing conversation. Once all major issues and questions are addressed, the review editor package will make a decision to accept, hold, or reject the package.
1111

1212
Rejections are usually done early in the process, before the review process begins. In rare cases a package may also not be on-boarded into the pyOpenSci ecosystem after review & revision.
1313

14-
It is ultimately editor’s decision on whether or not to reject the package based on how the reviews are addressed.
14+
It is ultimately the editor’s decision on whether or not to reject the package based on how the reviews are addressed.
1515

1616
## Review communication approach
1717

about-peer-review/pyopensci-related-joss-ropensci.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -11,26 +11,26 @@ The JOSS review process is about publication. A review from JOSS will provide
1111
you with a citable, [Crossref digital object identifier (DOI)](https://www.crossref.org/).
1212
pyOpenSci aligns closely with the broad mission of
1313
JOSS to provide maintainers with credit for their open source work. However,
14-
our mission is also more focused. pyOpenSci not open source maintainers getting academic credit for their work. We also support:
14+
our mission is also more focused. pyOpenSci is not just about open source maintainers getting academic credit for their work. We also support:
1515

16-
* the Python tools that drive scientific open reproducible science workflows;
17-
* enforcement and encouragement of Python-specific packaging standards across tools;
18-
* and curated lists of peer reviewed, and maintained Python scientific software.
16+
* the Python tools that drive scientific open reproducible science workflows;
17+
* Enforcement and encouragement of Python-specific packaging standards across tools;
18+
* Curated lists of peer reviewed, and maintained Python scientific software.
1919

2020
## How is review at pyOpenSci different from the JOSS review process?
2121

2222
We are not a typical publisher or journal. Rather we are a community that provides support for both a diverse group of software maintainers and long term maintenance of our packages.
2323

2424
The pyOpenSci review process is different from that of JOSS in a few ways:
2525

26-
1. Our review is specifically design to enforce modern, community-accepted best practices for Python packaging.
26+
1. Our review is specifically designed to enforce modern, community-accepted best practices for Python packaging.
2727
1. We place heavy emphasis on documentation and usability in our reviews and associated standardization of both.
2828
1. We build community around and visibility for its tools.
2929
1. We will promote packages and package maintainers once they are accepted into our ecosystem.
30-
1. We support long term maintenance of packages. If the maintainer needs to step down, we will ensure a new maintainer takes over OR sunset and remove the package from our ecosystem.
30+
1. We support long term maintenance of packages. If the maintainer needs to step down, we will ensure a new maintainer takes over or sunset and remove the package from our ecosystem.
3131
1. We provide a welcoming forum for you to ask questions and get help with maintaining your package as needed.
3232

33-
JOSS reviews are also [more limited in scope](https://joss.readthedocs.io/en/latest/review_criteria.html)
33+
JOSS reviews are also [more limited in scope](https://joss.readthedocs.io/en/latest/submitting.html?highlight=scope#submission-requirements)
3434
compared to pyOpenSci. Some of the
3535
[JOSS submission criteria](https://joss.readthedocs.io/en/latest/review_criteria.html)
3636
are, in places, less stringent or less specific to the Python programming
@@ -41,8 +41,8 @@ language than those of pyOpenSci.
4141
You don't have to chose between pyOpenSci and JOSS; You can submit your package to both.
4242

4343
pyOpenSci and JOSS are complementary, partner organizations. You don't have
44-
to chose one or the other! After a package to pyOpenSci has been reviewed and
45-
accepted by pyOpenSci you can also choose to register it with JOSS.
44+
to choose one or the other! After a package to pyOpenSci has been reviewed and
45+
accepted you can also choose to register it with JOSS.
4646

4747
JOSS has [more limited scope](https://joss.readthedocs.io/en/latest/review_criteria.html)
4848
for packages that it will review. For instance, while pyOpenSci will review
@@ -56,5 +56,5 @@ You do not need to go through two reviews!
5656
Once accepted by JOSS, you now have both a pyOpenSci acceptance and one by JOSS.
5757

5858
* JOSS will give you a Crossref DOI for citation.
59-
* And you can display that and your pyOpenSci peer reviewed badge at the top of your package's README.md file.
59+
* You can display that and your pyOpenSci peer reviewed badge at the top of your package's README.md file.
6060

appendices/editor-in-chief-checks.md

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,20 @@ review. Below are the basic checks that your package needs to pass
66
to begin our review. If some of these are missing, we will ask you
77
to work on them before the review process begins.
88

9-
- [ ] **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)
10-
- [ ] The package imports properly into a standard Python environment `import package-name`
11-
- [ ] **Fit**: The package meets criteria for [fit](https://www.pyopensci.org/peer-review-guide/about-peer-review/aims-and-scope.html#package-scope) and [overlap](https://www.pyopensci.org/peer-review-guide/about-peer-review/aims-and-scope.html#package-overlap).
12-
- [ ] **Documentation** The package has sufficient documentation available online (README, sphinx docs) to allow us to evaluate package function and scope *without installing the package*. This includes:
9+
- [ ] **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).
10+
- [ ] The package imports properly into a standard Python environment `import package-name`.
11+
- [ ] **Fit** The package meets criteria for [fit](https://www.pyopensci.org/peer-review-guide/about-peer-review/aims-and-scope.html#package-scope) and [overlap](https://www.pyopensci.org/peer-review-guide/about-peer-review/aims-and-scope.html#package-overlap).
12+
- [ ] **Documentation** The package has sufficient online documentation (README, sphinx docs) to allow us to evaluate package function and scope *without installing the package*. This includes:
1313
- [ ] Short tutorials or [vignettes](https://kbroman.org/pkg_primer/pages/vignettes.html) that help a user understand how to use the package and what it can do for them (often these have a name like "Getting started")
14-
- [ ] API documentation: this includes clearly written docstrings with variables defined using a standard docstring format. *We suggest using the [Numpy](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) docstring format.*
15-
- [ ] **README:** The package has a `README.md` file with clear explanation of what the package does, instructions on how to install it, and a link to development instructions.
16-
- [ ] **Contributing File:** The package has a `CONTRIBUTING.md` file that details how to install and contribute to the package.
17-
- [ ] **Issue Submission Documentation**: All of the information is filled out in the `YAML` header of the issue (located at the top of the issue template).
18-
- [ ] **Automated tests:** Package has a testing suite and is tested via GitHub actions or another Continuous Integration service.
19-
- [ ] **License:** The package has an [OSI approved license](https://opensource.org/licenses)
20-
- [ ] **Repository:** The repository link resolves correctly
21-
- [ ] **Package overlap:** That package doesn't fully overlap with functionality of other packages that have already been submitted to pyOpenSci
22-
- [ ] **Archive** (JOSS only, may be post-review): The repository DOI resolves correctly
14+
- [ ] API documentation: this includes clearly written docstrings with variables defined using a standard docstring format. *We suggest using the [Numpy](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard) docstring format*.
15+
- [ ] **README** The package has a `README.md` file with clear explanation of what the package does, instructions on how to install it, and a link to development instructions.
16+
- [ ] **Contributing File** The package has a `CONTRIBUTING.md` file that details how to install and contribute to the package.
17+
- [ ] **Issue Submission Documentation** All of the information is filled out in the `YAML` header of the issue (located at the top of the issue template).
18+
- [ ] **Automated tests** Package has a testing suite and is tested via GitHub actions or another Continuous Integration service.
19+
- [ ] **License** The package has an [OSI approved license](https://opensource.org/licenses).
20+
- [ ] **Repository** The repository link resolves correctly.
21+
- [ ] **Package overlap** The package doesn't entirely overlap with the functionality of other packages that have already been submitted to pyOpenSci.
22+
- [ ] **Archive** (JOSS only, may be post-review): The repository DOI resolves correctly.
2323
- [ ] **Version** (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?
2424

2525
---

appendices/package-approval-template.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,15 @@
55
There are a few things left to do to wrap up this submission:
66
- [ ] Activate [Zenodo](https://zenodo.org/) watching the repo if you haven't already done so.
77
- [ ] Tag and create a release to create a Zenodo version and DOI.
8-
- [ ] Add the badge for pyOpenSci peer-review to the README.md of <package-name-here>. The badge should be `[![pyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/issue-number)`
9-
- [ ] Add <package-name> to the pyOpenSci website. <maintainer-name>, please open a pr to update [this file](https://github.com/pyOpenSci/pyopensci.github.io/blob/main/_data/packages.yml): to add your package and name to the list of contributors
8+
- [ ] Add the badge for pyOpenSci peer-review to the README.md of <package-name-here>. The badge should be `[![pyOpenSci](https://tinyurl.com/y22nb8up)](https://github.com/pyOpenSci/software-review/issues/issue-number)`.
9+
- [ ] Add <package-name> to the pyOpenSci website. <maintainer-name>, please open a pr to update [this file](https://github.com/pyOpenSci/pyopensci.github.io/blob/main/_data/packages.yml): to add your package and name to the list of contributors.
1010
- [ ] <reviewers-and-maintainers> if you have time and are open to being listed on our website, please add yourselves to [this file](https://github.com/pyOpenSci/pyopensci.github.io/blob/main/_data/contributors.yml) via a pr so we can list you on our website as contributors!
1111

1212
<IF JOSS SUBMISSION>
1313
It looks like you would like to submit this package to JOSS. Here are the next steps:
1414

1515
- [ ] Login to the JOSS website and fill out the JOSS submission form using your Zenodo DOI. **When you fill out the form, be sure to mention and link to the approved pyOpenSci review.** JOSS will tag your package for expedited review if it is already pyOpenSci approved.
16-
- [ ] Wait for a JOSS editor to approve the presubmission (which includes a scope check)
16+
- [ ] Wait for a JOSS editor to approve the presubmission (which includes a scope check).
1717
- [ ] Once the package is approved by JOSS, you will be given instructions by JOSS about updating the citation information in your README file.
1818
- [ ] When the JOSS review is complete, add a comment to your review in the pyOpenSci software-review repo that it has been approved by JOSS.
1919

0 commit comments

Comments
 (0)