diff --git a/how-to/author-guide.md b/how-to/author-guide.md index 4bb4387a..0c13867a 100644 --- a/how-to/author-guide.md +++ b/how-to/author-guide.md @@ -6,7 +6,6 @@ Author Guide Reviewer Guide -Editor Guide Editor-in-Chief Guide Triage Team Guide Peer Review Lead @@ -14,10 +13,13 @@ Peer Review Lead ```{toctree} :hidden: -:caption: Onboarding Editors & Reviewers +:caption: Editor Guide +Position Description Finding & Onboarding Editors -Finding & Onboarding Reviewers +Review Process +Finding Reviewers +Onboarding Reviewers ``` Are you considering submitting a package for review with pyOpenSci? You've diff --git a/how-to/editor-description.md b/how-to/editor-description.md new file mode 100644 index 00000000..517ea661 --- /dev/null +++ b/how-to/editor-description.md @@ -0,0 +1,108 @@ +# pyOpenSci Software Review Editor + +Thank you for your time in serving as an editor for a pyOpenSci package! Below, you will find some +information about the role that editors have in the +pyOpenSci Python open peer review process. + +## Experience needed to become an editor + +Editors generally should: + +- Have completed a review for _at least_ 1 package for pyOpenSci. +- Have some experience with open-source software that supports the scientific + Python community. This experience could be maintaining or contributing to packages. It could also be experience related to usability of open-source software and/or documentation, tutorials, etc. Alternatively, it could involve participation in the broader scientific Python community in another capacity. + +## Two types of editors + +There are two types of editors involved in our open peer review process: + +- Guest editors and +- Full editors + +Both types of editors are considered a part of the editorial board for +pyOpenSci. The significant differences between guest and full editors are: + +- A guest editor may only join the board for a single review. +- A guest editor may be new to pyOpenSci's review process and thus require a bit more support in their first review. + +### Guest editors + +A guest editor is invited to lead a review in the +case where we need specific expertise for a single review. We also consider editors who are +performing their first review as guest editors, as they may require more +guidance or mentorship to complete the review (if they are new to our organization). + +New editors who wish to continue as full editors for pyOpenSci may do so +as long as both parties (pyOpenSci and the guest editors) feel like it is a +healthy fit for them and the organization. + +### "Full" editors + +A full editor is most often someone who has experience with the +pyOpenSci open package review process. A full editor ideally: + +- has completed a review for _at least_ 1 package for pyOpenSci +- and/or has submitted and gone through the pyOpenSci package review process +- and/or has experience reviewing for an organization such as JOSS or rOpenSci. + +We also appreciate when editors have experience working with or in the +Python open source software community, be it maintaining packages, contributing to +packages, or supporting the community. This is +not a requirement, however if you are interested in getting involved with +pyOpenSci! + +```{note} +There could be certain situations when an editor is onboarded with less experience! The above are simply guidelines that we like to follow. +``` + +## What does an editor do? (Responsibilities) + +An editor is usually recruited by the Editor in Chief, other editors on the +board, or the software review lead. [More on recruiting editors can be found here](onboarding-guide.md). + +An editor is responsible for: + +- Leading the review process for 3-4 packages a year +- Weighing in on group editorial decisions such as whether a package is in scope, and making updates to the pyOpenSci policies. + +```{note} +Decisions surrounding policy, updates to peer review guides, and decisions +on package review are generally made in the private `editorial-board` channel in the pyOpenSci Slack organization. Please make sure that you +are comfortable with checking Slack regularly. +``` + +## Editor support of other reviews + +Editors are not charged with tracking other submissions that they are +not leading. However, if you are serving as an editor and notice an +issue with another review, please raise that issue either directly with +the editor for that review. Or you can raise the issue in the `private-editorial-team` Slack +channel. + +## Editor-in-Chief rotation + +The editorial board normally participates in the Editor in Chief rotation. +You are eligible to enter this rotation after 3 months of serving on the editorial board +and/or after your first review as it makes sense. [Read more about the roles +and responsibilities of the Editor in Chief, here.](editor-in-chief-guide.md) + +If the Editor in Chief role feels like too much responsibility, an editor can also decline being a part of this rotation. + +## How long does an editor serve on the editorial board? + +Ideally, an editor can commit to serving for **at least** one year as an editor +for pyOpenSci. During that year, we expect that you will lead the review of 3-4 packages. However, we understand that in certain situations, an editor +may need to step down before the 1 year time period has ended. + +We also understand that life gets busy. You are always welcome to "say no" +to a review during a busy time. + +We welcome +editors staying on for longer as long as they are happy serving with us and +they get along well with other members of the editorial board, the software +review lead and the current Editor in Chief. + +## Closing notes about the editorial process + +- If the package raises a new issue for pyOpenSci policy, create an issue on [pyOpenSci's handbook repo](https://github.com/pyOpenSci/handbook). +- If the package review raises a new issue in our peer review process, please [open an issue in our peer review guide repo.](https://github.com/pyOpenSci/peer-review-guide). diff --git a/how-to/editor-in-chief-guide.md b/how-to/editor-in-chief-guide.md index 9550407e..3c55df4e 100644 --- a/how-to/editor-in-chief-guide.md +++ b/how-to/editor-in-chief-guide.md @@ -213,7 +213,7 @@ Follow the [onboarding guide](onboarding-guide.md), and complete the full [Share this document with any new editor to help them get started.](https://docs.google.com/document/d/1UfG1Fe5wSiEAObvqNMT4etZ5sx7QXzW0f8mozKyK1NE/edit?tab=t.0) -See the [editor guide](editors-guide.md) for more on an editor’s responsibilities. Once the editor is assigned, your +See the [editor description](editor-description.md) for more on an editor’s responsibilities. Once the editor is assigned, your work on the review is complete, and they will now begin identifying reviewers. ::: diff --git a/how-to/finding-reviewers.md b/how-to/finding-reviewers.md index 41f1bcfb..702a5e43 100644 --- a/how-to/finding-reviewers.md +++ b/how-to/finding-reviewers.md @@ -46,6 +46,26 @@ website, social media profiles). * Some domain experience in the field of the package or data source. * No [conflicts of interest](coi). +Each review should have at least two reviewers. + +- One reviewer should have expertise in both Python and the scientific domain related to the package submitted. +- The second reviewer can be more generally focused on the package's usability, accessibility, and packaging infrastructure. This allows people who are newer to review to get involved while also providing a critical usability check for the package. + +A review consisting of a domain expert and a Pythonista is ideal as it provides two distinct perspectives for review. Furthermore, it can often be challenging to find individuals with both the specific domain expertise and packaging expertise. + +### Timeline for finding reviewers + +If you can, try to find two people to serve as reviewers within **two weeks +of responding to the issue as the editor**. If it takes longer, as +often does, make a point to keep the author posted on the issue +as you continue your search. You may add language such as: + +> Hey, @authorGithubHandle I just wanted to drop in to let you know that I'm searching for reviewers for your package. It may take a bit more time. + +This type of communication just lets the author know that the process is +moving forward. Even if it takes longer to find reviews, authors generally +appreciate the communication and understand it's a volunteer-led process. + (reviewer-diversity)= ### Reviewer Diversity Should Be Prioritized @@ -69,28 +89,3 @@ the package functionality. It is ok and even welcome if one reviewer has more technical knowledge and the other focuses on usability and is less technical. Read through the [Guidelines for Reviewers Section](reviewer-guide-sphinx) to learn more about finding and selecting reviewers. - -(review-mentorship)= -## Peer Review Mentorship - -pyOpenSci encourages those who are newer to review to become involved in our -open peer review process. As such, we offer a reviewer mentorship program -where we pair a new reviewer with someone in the community who has previous -review experience. - -It is useful for reviewers to not only review the technical content of a -package, but also to review the documentation and package installation process -for usability. - -If a new reviewer is interested in becoming a reviewer but would like some -support, do the following: - -1. The Editor can lead the effort to find mentors for the new reviewers by posting in the `#software-review` Slack channel for help. -2. If the Editor needs support in finding a mentor, they can contact the **EiC** or **peer review lead** for guidance. - -### Once a Mentor is Identified - -1. Invite the new reviewer to our pyOpenSci Slack. -2. Start a private DM group chat with the new reviewer and the mentor(s) so - they are introduced. -3. Let the review proceed from there. diff --git a/how-to/onboarding-guide.md b/how-to/onboarding-guide.md index ce20422e..96ee64cf 100644 --- a/how-to/onboarding-guide.md +++ b/how-to/onboarding-guide.md @@ -5,7 +5,7 @@ and reviewers. Finding new volunteers to take on editorial and reviewer roles can sometimes be the trickiest part of the review process. However, we have resources available to help you in that effort! -Below, we discuss processes for finding, onboarding, and offboarding volunteers in our +Below, we discuss processes for finding, onboarding, and offboarding editors in our peer review process. ## About the Editorial Board diff --git a/how-to/onboarding-reviewers.md b/how-to/onboarding-reviewers.md new file mode 100644 index 00000000..d53b2fcc --- /dev/null +++ b/how-to/onboarding-reviewers.md @@ -0,0 +1,48 @@ +# Onboarding Reviewers + +The pyOpenSci open peer review process is driven and led by volunteer editors +and reviewers. Finding new volunteers to take on editorial and reviewer roles +can sometimes be the trickiest part of the review process. However, we have +resources available to help you in that effort! + +For finding reviewers please look at the [finding-reviewers](finding-reviewers.md) guide + +Below, we discuss processes for onboarding reviewers and making sure they are supported during the peer review process. + +## Inviting Reviewers + +If you'd like to, you can use the email template below to invite reviewers. + +```{include} ../appendices/reviewer-request-template.md + +``` + +When inviting reviewers, include something like "If I don't hear from +you in a week, I'll assume you are unable to review," to give a clear +deadline when you'll move on to looking for someone else to keep the processing +moving. + +(review-mentorship)= +## Peer Review Mentorship + +pyOpenSci encourages those who are newer to review to become involved in our +open peer review process. As such, we offer a reviewer mentorship program +where we pair a new reviewer with someone in the community who has previous +review experience. + +It is useful for reviewers to not only review the technical content of a +package, but also to review the documentation and package installation process +for usability. + +If a new reviewer is interested in becoming a reviewer but would like some +support, do the following: + +1. The Editor can lead the effort to find mentors for the new reviewers by posting in the `#software-review` Slack channel for help. +2. If the Editor needs support in finding a mentor, they can contact the **EiC** or **peer review lead** for guidance. + +### Once a Mentor is Identified + +1. Invite the new reviewer to our pyOpenSci Slack. +2. Start a private DM group chat with the new reviewer and the mentor(s) so + they are introduced. +3. Let the review proceed from there. diff --git a/how-to/peer-review-lead.md b/how-to/peer-review-lead.md index dfc5a21b..dd92f568 100644 --- a/how-to/peer-review-lead.md +++ b/how-to/peer-review-lead.md @@ -60,7 +60,7 @@ If a review has been quiet for over a month, it's a good idea to check in on thi Also, check out the days open column. Keep an eye out for reviews that have been open for longer than 6 months. In some cases, you may want to check in with the editor to see how things are going and whether there is a way to move the review forward. -In some cases a review hasn't moved forward because the editor is struggling to find reviewers. [This page](finding-reviewers) will help you with some tips on helping an editor find reviewers. Sometimes this is as easy as posting in our pyOpenSci #software-review channel. Other times we might need to run a call for reviewers. +In some cases a review hasn't moved forward because the editor is struggling to find reviewers. [This page](finding-reviewers.md) will help you with some tips on helping an editor find reviewers. Sometimes this is as easy as posting in our pyOpenSci #software-review channel. Other times we might need to run a call for reviewers. ### 4. Check the reviews seeking editors section diff --git a/how-to/editors-guide.md b/how-to/review-process.md similarity index 68% rename from how-to/editors-guide.md rename to how-to/review-process.md index 5da9e207..b5daf215 100644 --- a/how-to/editors-guide.md +++ b/how-to/review-process.md @@ -1,106 +1,6 @@ -# pyOpenSci Software Review Editor Guide +# Review Process -Thank you for your time in serving as an editor for a pyOpenSci package! Below, you will find some -information about the role that editors have in the -pyOpenSci Python open peer review process. - -## Experience needed to become an editor - -Editors generally should: - -- Have completed a review for _at least_ 1 package for pyOpenSci. -- Have some experience with open-source software that supports the scientific - Python community. This experience could be maintaining or contributing to packages. It could also be experience related to usability of open-source software and/or documentation, tutorials, etc. Alternatively, it could involve participation in the broader scientific Python community in another capacity. - -## Two types of editors - -There are two types of editors involved in our open peer review process: - -- Guest editors and -- Full editors - -Both types of editors are considered a part of the editorial board for -pyOpenSci. The significant differences between guest and full editors are: - -- A guest editor may only join the board for a single review. -- A guest editor may be new to pyOpenSci's review process and thus require a bit more support in their first review. - -### Guest editors - -A guest editor is invited to lead a review in the -case where we need specific expertise for a single review. We also consider editors who are -performing their first review as guest editors, as they may require more -guidance or mentorship to complete the review (if they are new to our organization). - -New editors who wish to continue as full editors for pyOpenSci may do so -as long as both parties (pyOpenSci and the guest editors) feel like it is a -healthy fit for them and the organization. - -### "Full" editors - -A full editor is most often someone who has experience with the -pyOpenSci open package review process. A full editor ideally: - -- has completed a review for _at least_ 1 package for pyOpenSci -- and/or has submitted and gone through the pyOpenSci package review process -- and/or has experience reviewing for an organization such as JOSS or rOpenSci. - -We also appreciate when editors have experience working with or in the -Python open source software community, be it maintaining packages, contributing to -packages, or supporting the community. This is -not a requirement, however if you are interested in getting involved with -pyOpenSci! - -```{note} -There could be certain situations when an editor is onboarded with less experience! The above are simply guidelines that we like to follow. -``` - -## What does an editor do? (Responsibilities) - -An editor is usually recruited by the Editor in Chief, other editors on the -board, or the software review lead. [More on recruiting editors can be found here](onboarding-guide.md). - -An editor is responsible for: - -- Leading the review process for 3-4 packages a year -- Weighing in on group editorial decisions such as whether a package is in scope, and making updates to the pyOpenSci policies. - -```{note} -Decisions surrounding policy, updates to peer review guides, and decisions -on package review are generally made in the private `editorial-board` channel in the pyOpenSci Slack organization. Please make sure that you -are comfortable with checking Slack regularly. -``` - -## Editor support of other reviews - -Editors are not charged with tracking other submissions that they are -not leading. However, if you are serving as an editor and notice an -issue with another review, please raise that issue either directly with -the editor for that review. Or you can raise the issue in the `private-editorial-team` Slack -channel. - -## Editor-in-Chief rotation - -The editorial board normally participates in the Editor in Chief rotation. -You are eligible to enter this rotation after 3 months of serving on the editorial board -and/or after your first review as it makes sense. [Read more about the roles -and responsibilities of the Editor in Chief, here.](editor-in-chief-guide.md) - -If the Editor in Chief role feels like too much responsibility, an editor can also decline being a part of this rotation. - -## How long does an editor serve on the editorial board? - -Ideally, an editor can commit to serving for **at least** one year as an editor -for pyOpenSci. During that year, we expect that you will lead the review of 3-4 packages. However, we understand that in certain situations, an editor -may need to step down before the 1 year time period has ended. - -We also understand that life gets busy. You are always welcome to "say no" -to a review during a busy time. - -We welcome -editors staying on for longer as long as they are happy serving with us and -they get along well with other members of the editorial board, the software -review lead and the current Editor in Chief. +Below will go through the process of a review for pyOpenSci ## Editor checklist: Get Started With Leading a Package Review @@ -184,28 +84,10 @@ Authors may opt to submit to JOSS after a successful PyOpenSci submission. If th ### ✔️ 3. Identify reviewers for the Python package -Each review should have at least two reviewers. - -- One reviewer should have expertise in both Python and the scientific domain related to the package submitted. -- The second reviewer can be more generally focused on the package's usability, accessibility, and packaging infrastructure. This allows people who are newer to review to get involved while also providing a critical usability check for the package. - -A review consisting of a domain expert and a Pythonista is ideal as it provides two distinct perspectives for review. Furthermore, it can often be challenging to find individuals with both the specific domain expertise and packaging expertise. - -#### Finding package reviewers +There are more details in the [finding reviewers](finding-reviewers.md) page. In general: -Oftentimes, finding reviewers for a package can be the trickiest part -of the review process. Expect this step to take time and patience. [Check out this page for tips related to finding and onboarding reviewers.](finding-reviewers) - -If you can, try to find two people to serve as reviewers within **two weeks -of responding to the issue as the editor**. If it takes longer, as -often does, make a point to keep the author posted on the issue -as you continue your search. You may add language such as: - -> Hey, @authorGithubHandle I just wanted to drop in to let you know that I'm searching for reviewers for your package. It may take a bit more time. - -This type of communication just lets the author know that the process is -moving forward. Even if it takes longer to find reviews, authors generally -appreciate the communication and understand it's a volunteer-led process. +- Each review should have at least two reviewers, one with Python and scientific domain expertiese, and one with focused on package's usability, accessibility, and packaging infrastructure. +- find two people to serve as reviewers within **two weeks of responding to the issue as the editor** ```{admonition} Diversity in the editorial & reviewer team is important :class: important @@ -215,21 +97,8 @@ editorial team comprised of an editor + 2 reviewers from diverse backgrounds. In your search for reviewers, please ensure that there is diversity in the team supporting package review. Reviewers should have [different backgrounds and different gender identities](reviewer-diversity) whenever possible. pyOpenSci [supports mentoring new reviewers if needed!](review-mentorship) - -[Read our finding reviewers guide for more on finding reviewers.](finding-reviewers) -``` - -If you'd like to, you can use the email template below to invite reviewers. - -```{include} ../appendices/reviewer-request-template.md - ``` -When inviting reviewers, include something like "If I don't hear from -you in a week, I'll assume you are unable to review," to give a clear -deadline when you'll move on to looking for someone else to keep the processing -moving. - - Once you have assigned reviewers to the review, you will update the editor response above with: 1. Reviewer GitHub handles and @@ -249,6 +118,8 @@ Make sure to ask the reviewers for their preferred means of contact or a reliabl ### ✔️ 4. Onboard reviewers +See [onboarding-reviewers](onboarding-reviewers.md) to learn more about inviting reviewers and providing support. + Once reviewers have been identified: - Tag issue with `3/reviewer(s)-assigned` tag. @@ -385,11 +256,6 @@ This is the final version as presented after all feedback from the reviews has been considered and implemented. ``` -## Closing notes about the editorial process - -- If the package raises a new issue for pyOpenSci policy, create an issue on [pyOpenSci's handbook repo](https://github.com/pyOpenSci/handbook). -- If the package review raises a new issue in our peer review process, please [open an issue in our peer review guide repo.](https://github.com/pyOpenSci/peer-review-guide). - ## ✔️ OPTIONAL: Instructions for Submitting to JOSS If the package fits within the JOSS Scope, once the package has been approved diff --git a/how-to/review-triage-team.md b/how-to/review-triage-team.md index d324fab4..dc08430d 100644 --- a/how-to/review-triage-team.md +++ b/how-to/review-triage-team.md @@ -165,7 +165,7 @@ Finally, delete the branch associated with the PR. ## How to know when the package was accepted -In our peer review guide, we have a [template that editors should use](https://www.pyopensci.org/software-peer-review/how-to/editors-guide.html) to accept a package into our ecosystem. In an issue, you can look for this comment and use the date that the comment was posted as the date the package was accepted. +In our peer review guide, we have a [template that editors should use](https://www.pyopensci.org/software-peer-review/how-to/review-process.html) to accept a package into our ecosystem. In an issue, you can look for this comment and use the date that the comment was posted as the date the package was accepted. There are cases when editors forget to use this template. But ideally, you can figure this out by searching for "accepted" in the review. OR you can simply just ask the editor in the `private-editorial` channel on our Slack. diff --git a/index.md b/index.md index 3dcecb2f..a0d12353 100644 --- a/index.md +++ b/index.md @@ -60,7 +60,7 @@ Learn how to submit a package for peer review with pyOpenSci. :::: ::::{grid-item-card} {octicon}`pencil;1.5em;sd-mr-1` Editors Guide -:link: how-to/editors-guide +:link: how-to/editor-description :link-type: doc :class-header: bg-light diff --git a/our-process/review-timeline.md b/our-process/review-timeline.md index 9eafcdb4..5e88df83 100644 --- a/our-process/review-timeline.md +++ b/our-process/review-timeline.md @@ -100,7 +100,7 @@ Learn more » ::: :::{grid-item-card} {octicon}`pencil;1.5em;sd-mr-1` Editor Guide -:link: /how-to/editors-guide +:link: /how-to/editor-description :link-type: doc :class-header: bg-light +++