diff --git a/conf.py b/conf.py index 85324fdf..bb2ff965 100644 --- a/conf.py +++ b/conf.py @@ -57,21 +57,15 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = "pydata_sphinx_theme" +html_theme = "pyos_sphinx_theme" html_title = "Software Peer Review Guide" html_logo = "_static/logo.png" html_static_path = ["_static"] html_js_files = ["matomo.js"] +html_favicon = 'https://www.pyopensci.org/images/favicon.ico' # Theme options html_theme_options = { - "favicons": [ - { - "rel": "icon", - "sizes": "16x16", - "href": "https://www.pyopensci.org/images/favicon.ico", - }, - ], "announcement": "

Submit Your Python Package for Peer Review!

", "external_links": [ { @@ -133,6 +127,8 @@ ".github", ".nox", "README.md", + ".pytest_cache", + ".pytest_cache/*", ] diff --git a/how-to/author-guide.md b/how-to/author-guide.md index ec04e5c7..605e1541 100644 --- a/how-to/author-guide.md +++ b/how-to/author-guide.md @@ -71,29 +71,14 @@ Read about our peer review policies. ::::{grid-item} :::{card} Need packaging guidance? -:link: https://www.pyopensci.org/python-package-guide/ -:link-type: doc :class-card: left-aligned -If you want to learn more about packaging best practices, you can check out our packaging guide. -+++ - Go there now +[If you want to learn more about packaging best practices, you can check out our packaging guide.](https://www.pyopensci.org/python-package-guide) ::: :::: -::::{grid-item} -:::{card} Questions? -:link: https://pyopensci.discourse.group/c/review-process/7 -:link-type: doc - -If you have questions about our process or packaging in general, please ask them on our discourse! We are here to help you. -+++ - Go there now -::: - ::::: - Before you begin this process, [please be sure to read the review process guidelines](../our-process/policies). ```{note} diff --git a/how-to/editor-in-chief-guide.md b/how-to/editor-in-chief-guide.md index f80a1fca..783ad36a 100644 --- a/how-to/editor-in-chief-guide.md +++ b/how-to/editor-in-chief-guide.md @@ -1,164 +1,355 @@ # Editor in Chief Guide +:::{admonition} Useful pyOpenSci resources +:class: tip + +Here are some helpful resources to support you in your Editor in Chief role: + +* [**Python Package Guide**](https://www.pyopensci.org/python-package-guide/): + A community-developed guide offering an overview of the Python packaging + ecosystem, plus tutorials for building and publishing a package. +* [**pyOpenSci metrics dashboard**](https://www.pyopensci.org/metrics/): + View the current state of peer reviews and track review activity over time. +* [**pyOpenSci Python package template**](https://github.com/pyOpenSci/pyos-package-template): + A Copier-powered template for creating a new Python package that follows + pyOpenSci best practices. +::: + ## Editor in Chief (EiC) role & responsibilities -The Editor in Chief (EiC) is a rotating position that serves -for 3 to 6 months or a time agreed to by all members of the editorial -board. - -If the EiC needs to step down at any time before the agreed-upon -duration of their tenure, pyOpenSci requests and appreciates 2 weeks notice -to support finding a new EiC. - -### The Editor in Chief fulfills the following roles: - -- Watches all issues posted to the [software-review repository](https://github.com/pyOpenSci/software-review/issues) (by "watching" it on GitHub to receive notifications, and by joining the `#feed-software-review` channel on Slack). -- Performs an initial set of editor checks on new package submissions (see {ref}`template ` for these checks below) -- Raises scope/overlap issue with all editors if they see an ambiguous submission. -This may also be done by handling editors if appropriate (see note below). If -the scope of a package is in question, the EiC should post to the pyOpenSci -Slack `#software-review` channel, tagging all editors. -- Assigns package submissions to other editors to handle. Assigning may be based upon domain background or just who has bandwidth to lead the review. The editor in chief can assign packages to themself for review. -- Responds to pre-submission inquiries posted to the software-review repository -and similarly pings editors in the `#software-review` Slack channel if discussion -is needed. Any editor should feel free to communicate with package authors as it -makes sense. See [this section](#responding-to-out-of-scope-submissions) about -how to respond to out-of-scope (pre-) submissions. -- Responds to review referrals from JOSS or other publication partners. -- Monitors pace of review process and reminds other editors to move packages along as needed. -- Requests a new EiC when their rotation is up (set a calendar reminder ahead of your expected end date and ask for volunteers in the editors’ Slack channel) -- Once or twice during the EiC rotation, the EiC should check to see if any packages in our pyOpenSci list are potentially no longer maintained. If a package is no longer maintained, follow the process in the [package archive section](https://www.pyopensci.org/software-peer-review/our-process/policies.html#package-maintenance-and-maintainer-responsiveness) of our peer review guide - -This Editor in Chief position rotates between different pyOpenSci editors. - -```{note} -In some cases, if the EiC is unable to support review of a particular package due to -conflicts OR if they simply believe another editor is better suited to assess -the scope and readiness of a package to be reviewed, they may opt to assign an editor to perform initial checks. -``` +The Editor in Chief (EiC) is a rotating position, typically selected from the +current editorial team. It may also be held by a member of the broader +pyOpenSci community, who is familiar with our organization and software peer +review. + +The EiC term lasts **3 to 6 months**, or another duration agreed upon with the +[Peer Review Lead (currently the Executive Director)](https://www.pyopensci.org/handbook/governance/structure.html#peer-review-lead). If the EiC needs to step down early, we request at least +**two weeks’ notice** to allow time to identify and onboard a replacement. + +The Editor in Chief fulfills the roles discussed below: + +### 1. Manage incoming reviews + +* Watch all issues in the + [software-review repo](https://github.com/pyOpenSci/software-review/issues) + +:::{tip} +Enable GitHub notifications and join the `#feed-software-review` Slack channel +to stay up to date on new submissions. +::: + +* Perform the **initial editor checks** on new submissions using the + [editor checklist](pre-review-checks). +* Flag scope or overlap concerns. Raise questions by tagging editors in + `#software-review` or, if needed, in `#private-editorial-team`. +* Assign submissions to handling editors based on: + * subject matter fit + * editor availability + +> The EiC may assign a package to themselves if they have capacity and want to +> lead the review. + +### 2. Manage pre-submission inquiries + +* Respond to pre-submission inquiries and assess package scope or structure. +* Handle or delegate review referrals from the [Journal of Open Source Software + (JOSS)](joss) or other partners. + +### 3. Monitor review progress + +Check the status of active reviews **monthly**. Use the +[peer review dashboard](https://www.pyopensci.org/metrics/peer-review/peer-review-status-dashboard.html) +to identify stalled reviews or submissions needing editors or reviewers. + +The dashboard highlights: + +* Packages still seeking reviewers +* Packages needing an editor +* Open pre-submission inquiries +* Stale issues with no recent comments + +If a review has been inactive for 3–4 weeks, message the editor in Slack to +check in. You or the [Peer Review Lead](https://www.pyopensci.org/handbook/governance/structure.html#peer-review-lead) can help move things forward. If needed, +discuss in the `#private-editorial-team` channel. + +:::{tip} +Need help unblocking a review? Contact the acting Peer Review Lead. +::: + +### 4. Monitor package maintenance + +Once or twice during your term, review our list of accepted packages and flag +any that appear unmaintained. If needed, follow the +[archiving process](https://www.pyopensci.org/software-peer-review/our-process/policies.html#package-maintenance-and-maintainer-responsiveness). + +### 5. Support EiC transition + +As your term nears its end, discuss with the peer-review lead the process of identifying your successor. +Set a calendar reminder 2–3 weeks in advance to start the transition process. + +:::{note} +See [this section](#responding-to-out-of-scope-submissions) for guidance on +responding to out-of-scope pre-submissions. +::: + +:::{note} +If the EiC has limited time to handle [pre-review checks](pre-review-checks) for a package, a conflict of interest, or lacks relevant expertise, they may ask another editor to perform initial checks on a package at any time. +::: ## Editor in Chief checklist -When a new package is submitted for review, the Editor in Chief will: +When a new package is submitted for review, the Editor in Chief should: + +### 1. ✔️ Tag the issue with the `0/pre-review-checks` label in GitHub + +### 2. ✔️ Add a partner tag if the author selected a partner affiliation -### 1. ✔️ Tag the issue with `0/pre-review-checks` tag in GitHub +pyOpenSci supports +[partnerships with other communities](partner-communities). Astropy is our only active partner. -### 2. ✔️ Add the editor checks to the issue +If the author selects a partner in the submission template, -```{important} -It is important that this step occur in one post rather than a string of -conversational feedback that is more difficult to follow. This allows the author to address all issues at -one time. Thus the EIC should: +1. Notify an editor from that community that a review may be forthcoming. — they will typically take +the lead on that review. +2. Add the appropriate partner label to the issue. -1. Review the checklist. -1. Give the author a rough estimate of how long the checks might take to complete. -1. Perform all of the checks locally. -1. When all of the above are complete, post the checklist with any feedback for the author in the issue. This should be one single post. +The partner section of the submission looks like this: + +```markdown +## Community Partnerships +If your package is associated with an +existing community, please check below: + +- [ ] Astropy:[My package adheres to Astropy community standards](https://www.pyopensci.org/software-peer-review/partners/astropy.html) +- [ ] Pangeo: My package adheres to the [Pangeo standards listed in the pyOpenSci peer review guidebook][PangeoCollaboration] ``` -Copy the {ref}`template below ` -and add it to the issue. +(pre-review-checks)= + +### 3. ✔️ Add the pre-review checks to the issue + +:::{important} +Post your complete pre-review/editor checks in **one single comment**, rather than in multiple +comments. This keeps the review easy to follow and lets the author address +everything at once. -Editor checks ensure that the package has -the bare minimum requirements to initiate a review. -We hope that even the process of going through these checks will -improve the quality of the package. +Before posting: -In some situations, the editor-in-chief initial checks may be passed down to an editor as follows: +1. Review the editor-in-chief checklist. +2. Estimate how long the checks might take and share that with the author. +3. Perform all checks locally. +4. Post the completed checklist and any feedback in a **single GitHub comment**. +::: -* If the Editor in Chief is overwhelmed with package submissions to evaluate. -* If the Editor in Chief simply is busy at the time and needs support with checks. -* If the Editor in Chief thinks that the checks might be better served if done by an Editor -(For instance, if a specific domain or technical expertise would support more effective checks). +Copy the template below and add it to the issue. + +These checks confirm that the package meets the **minimum standards for +review**. In many cases, going through this process improves the package itself. + +The EiC may ask another editor to complete the checks if: + +* They are overwhelmed with new submissions. +* They are temporarily unavailable. +* Another editor has relevant domain or technical expertise. (editor-checklist-template)= + ### Editor-in-chief checklist -Copy the template below to use it in the issue. +Copy the template below and use it in the review issue. ```{include} ../appendices/editor-in-chief-checks.md ``` -### 3. ✔️ Ensure that the package onboarding survey is filled out. - -Thank the authors graciously for filling out our survey. They can -skip sections of it if they wish. We do need their contact -information to stay in touch about package maintenance. We also -want to track their experience with our review process and -organization. - -### 4. ✔️ Assign an editor to the issue to manage the rest of the review and tag the issue with the `1/editor-assigned` tag in GitHub - -Once the package initial checks are complete, and it is determined that -the package is in scope for pyOpenSci review, the Editor in Chief will assign an -editor to the review issue and add the `1/editor-assigned` tag in GitHub. -This may involve finding a new (guest) editor -as described in the [onboarding guide](onboarding-guide.md). -If you as Editor in Chief do recruit a new editor, -be sure to complete all the onboarding steps described -[here](onboarding-a-new-editor) so that the new editor -has everything they need to manage the review, -such as GitHub permissions and access to the relevant channels -in the pyOpenSci Slack team. -The editor will now begin the process of finding reviewers -for the package. -[Check out the editor guide for more information on the process that an editor follows](editors-guide.md) - -```{admonition} Diversity in the editorial & reviewer team is important +### 4. ✔️ Ensure that the package onboarding survey is complete + +Use [this spreadsheet](https://docs.google.com/spreadsheets/d/1jEk-DDpkz14Z07OX_o1cN2vHzVbJO6mQ83ihGXsWkLc/edit?gid=930774086#gid=930774086) +to check whether the author—and ideally all maintainers—have completed the +pre-review survey. You can search using their GitHub handle. + +Thank the author for completing the survey. While some sections are optional, +we do need contact information to follow up about package maintenance. The +survey also helps us track and improve our peer review process. + +### 5. ✔️ Assign an editor and add the `1/editor-assigned` label to the GitHub issue + +Once the package is determined to be in scope, the pre-review surveys are complete, and pre-review checks +are done, it's time to assign an editor. + +Use the [editorial dashboard](https://www.pyopensci.org/metrics/peer-review/editorial-dashboard.html) +to check which editors are currently available and what domains those editors are familiar with. + +Once you’ve selected an editor: + +1. Assign the issue to them in GitHub +2. Update the YAML at the top of the issue with their GitHub username +3. Add the `1/editor-assigned` label to the issue + +:::{note} +If there isn't an available editor with relevant expertise for a review, work with the [Peer +Review Lead](https://www.pyopensci.org/handbook/governance/structure.html#peer-review-lead) to recruit a guest editor or onboard someone new. + +Follow the [onboarding guide](onboarding-guide.md), and complete the full +[onboarding process](onboarding-a-new-editor) to ensure they have: + +* GitHub access +* Slack access +* Everything needed to manage the review + +[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 +work on the review is complete, and they will now begin identifying reviewers. + +::: + +:::{admonition} Diversity in the editorial & reviewer team is important :class: important -Diversity is core to the pyOpenSci mission. As such it's important to have an -editorial team comprised of an editor + 2 reviewers from diverse backgrounds. +Inclusion is core to the pyOpenSci mission. It's important to have an +editorial team comprised of an editor + 2 reviewers from different backgrounds and identities to enrich the review process. As you select an editor (and guide that editor in finding reviewers), -ensure that there is diversity -in the team supporting package review. [Specifically reviewers and the editor should have a mix of gender-identities whenever possible](reviewer-diversity). pyOpenSci [also supports mentoring new reviewers and editors if needed!](review-mentorship) +seek diversity in the team supporting package review. [Specifically, reviewers and the editor should have a mix of gender identities whenever possible](reviewer-diversity). pyOpenSci [also supports mentoring new reviewers and editors if needed!](review-mentorship) -``` +::: -### 5. ✔️ Update the YAML header of the issue +### 6. ✔️ Update the YAML header -Once all of the above is complete, the Editor in Chief should: +After assigning the editor to the issue and adding the `1/editor-assigned` label: -* Add any comments to the bottom of your editor checks comment. -* Update the YAML in the issue's header with the editor assigned to the review. -* Add the tag `2/seeking-reviewer(s)` to the issue. +* Update the YAML at the top of the issue with the editor’s GitHub username +* Add any final comments to the bottom of your pre-review checklist comment -## A note about submissions that are incomplete or vague +:::{important} +Be sure to update both the **GitHub assignment** and the **YAML header** with the editor's name. Our [peer +review dashboard](https://www.pyopensci.org/metrics/peer-review/current-review-status.html) depends on both! +::: -In some cases: +## Handling submissions that are incomplete or vague -* Online documentation of a package is sparse. -* README is minimal or hard to understand. -* No clear documentation setup. -* Elements of the YAML template at the top of the issue are not filled out. +Sometimes a submission lacks enough information to assess whether it’s in +scope. For example: -This makes assessment of the package's scope much harder. -In this case, please ask the author for more information. Even if the package is deemed -out-of-scope, the package documentation will improve as a result of your questions. +* Online documentation is sparse +* The README is minimal or unclear +* There’s no documentation structure +* The YAML template at the top of the issue is incomplete -Example text: +In these cases, ask the author for more information. Even if the package is +ultimately out of scope, this will still help improve its documentation. + +You can adapt the message below when requesting more details: ```markdown -Hello and many thanks for your submission. +Hello , and thank you for your submission! -We are discussing whether the package is in scope and need a bit more -information. +We are reviewing whether your package fits within pyOpenSci’s scope and +could use a bit more information. -Please add more details and context to your `README` file. -After reading it, someone with little domain knowledge should understand -the aim, goals and functionality of the package. +Please expand your `README` to give more context. After reading it, someone +without domain expertise should understand the package’s goals, use cases, +and core functionality. -If a package has overlapping functionality with other packages, we require you -to mention in your documentation (README) and in this issue [how it is "best in class"](https://www.pyopensci.org/software-peer-review/about/package-scope.html#package-overlap). Please add a more detailed comparison to the packages you mention in the README so we can evaluate? +If your package overlaps with others, please explain in the README and in +this issue how your package is "best in class." You can refer to our +[guidance on package overlap](https://www.pyopensci.org/software-peer-review/about/package-scope.html#package-overlap). ``` +## Addressing challenges in the review process + +During the review, you may encounter challenges that require resolution. + +* For **technical issues** such as repository access, GitHub integration, or platform problems, post in the `#pyos-infrastructure` Slack channel where our technical team can assist you. + +* For **behavior concerns** including unprofessional communication, harassment, or guideline violations, use our [pyOpenSci Code of Conduct](https://www.pyopensci.org/handbook/CODE_OF_CONDUCT.html) as guidance. Follow the Code of Conduct reporting procedures and notify the Peer Review Lead of the issue. + +* For **conflicts of interest** involving financial, professional, or personal conflicts between reviewers and authors, you can post in the `private-editorial-channel` Slack channel or contact the Peer Review Lead directly if you prefer a more confidential approach. + +* For **all other questions** related to the review process, you can contact the Peer Review Lead for guidance and support. + +## Keeping the review process moving forward + +The pyOpenSci peer review metrics dashboard can help you keep tabs on review status. + +### Keeping track of reviews that need editors + +The [editors needed table](https://www.pyopensci.org/metrics/peer-review/current-review-status.html#editors-needed) and [reviewers needed table](https://www.pyopensci.org/metrics/peer-review/current-review-status.html#reviewers-needed) lists reviews that are still searching for editors and reviewers. + +### How to handle stalled reviews + +* [This table contains a list of all open reviews (and pre-review submissions).](https://www.pyopensci.org/metrics/peer-review/current-review-status.html#all-open-reviews). You can sort it by **last comment date** to understand better what reviews have been "quiet" and might need a nudge to move forward. + +If you notice that a review hasn't been active in over 1+ months, do the following: + +1. Leave a note on the review to see what the state of the review is. +2. If no one responds to the comment within ~2 weeks, consider DM'ing the editor in the pyOpenSci Slack to see if they are still able to move the review forward. +3. If a DM to the editor doesn't work, consider sending an email next. Oftentimes, people lose track of GitHub notifications, but they respond to emails. +4. If all of the above fail and there is no movement on the review, post in the `#private-editorial-team` channel in our Slack, and the peer review lead can help you move things forward. In some cases, you may need to find a new editor who has more bandwidth to complete the review. In other cases, the editor will step back in and get things moving again. + +If you need to find a new editor, the [editors available for a review](https://www.pyopensci.org/metrics/peer-review/current-review-status.html#editors-available-for-a-review) lists editors that are not currently running a review. + +:::{tip} +If the editor is struggling with reviewers not responding, see [the editor guide for more information on how to manage this](reviewer-response-time) +::: + ## Responding to out-of-scope submissions -If the package is determined to be out-of-scope, the Editor in Chief should -thank authors for their submission, explain the reasons for the decision, and -direct them to other publication venues if relevant. If further discussion is -warranted that can take place within the issue. +If a package is determined to be out of scope, thank the author for their +submission, briefly explain why it is not in scope, and suggest other venues +for review if relevant. + +Keep the conversation respectful and transparent. If the author has questions, +continue the discussion in the GitHub issue. + +## Stepping down from the EiC role + +As your term ends, help onboard the next Editor in Chief. + +* Set a calendar reminder 2–3 weeks before your term ends and begin to communicate with the incoming editor-in-chief about the transition. +* Craft a summary of where peer review is, and where the incoming Editor in Chief will need to pick up. +* Let the Peer Review Lead know that a transition is coming soon so they can support as needed. +<<<<<<< HEAD +* If you can, try to be available after your term has ended to answer questions and support a smooth transition for the new editor in chief +======= +* If you can, try to be available after your term has ended to answer questions and support a smooth transition for the new Editor in Chief + +>>>>>>> 2f46a28 (ENH: Fix more typos) + +:::{important} +If you are leading any active reviews as EiC, you must hand them off to the +incoming Editor in Chief before stepping down. This ensures continuity and +prevents reviews from stalling. +::: + +The new EiC assumes full responsibility for all active reviews and +pre-submission inquiries previously managed by the outgoing EiC. + +### Share your reflections + +Before stepping down, write a summary of: + +* What went well +* What could be improved +* Any challenges or ideas you’d recommend to future EiCs + +Post your reflection in the `#private-editorial-team` Slack channel or share it with +the peer review lead directly. + +### EiC Transition Checklist + +You can use the checklist below to manage the tasks. + +```markdown +### EiC Transition Checklist + +- [ ] Set calendar reminder 3 weeks before term end +- [ ] Contact peer review lead about successor +- [ ] Document active reviews and their status +- [ ] Hand off any reviews you're personally handling +- [ ] Write reflection summary +- [ ] Schedule handoff meeting with incoming EiC +``` diff --git a/how-to/editors-guide.md b/how-to/editors-guide.md index 48ac6020..854c14e7 100644 --- a/how-to/editors-guide.md +++ b/how-to/editors-guide.md @@ -1,15 +1,6 @@ # pyOpenSci Software Review Editor Guide - - -Thank you for your time in serving as an editor for a PyOpenSci package! Below you will find some +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. @@ -18,8 +9,8 @@ pyOpenSci Python open peer review process. 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 also could be experience related to usability of open source software and/or documentation, tutorials etc. Or finally it could be involvement in the scientific Python community in some other way. +- 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 @@ -29,16 +20,16 @@ There are two types of editors involved in our open peer review process: - Full editors Both types of editors are considered a part of the editorial board for -pyOpenSci. The major difference between guest and full editors is: +pyOpenSci. The significant difference 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 is invited to lead a review in the +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 +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 on as full editors for pyOpenSci may do so @@ -55,27 +46,27 @@ pyOpenSci open package review process. A full editor ideally: - 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 certainly -not a requirement however if you are interested in getting involved with +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 on boarded with less experience! The above are simply guidelines that we like to follow. +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 normally recruited by the Editor in Chief, other editors on the +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. +- 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 +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. ``` @@ -85,8 +76,8 @@ are comfortable with checking Slack regularly. 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 editors -channel in slack. +the editor for that review. Or you can raise the issue in the `private-editorial-team` Slack +channel. ## Editor-in-Chief rotation @@ -205,35 +196,36 @@ appreciate the communication and understand it's a volunteer-lead process. ```{admonition} Diversity in the editorial & reviewer team is important :class: important -Diversity is core to the pyOpenSci mission. As such it's important to have an +Diversity is core to the pyOpenSci mission. As such, it's important to have an 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. Specifically both reviewers should have [different backgrounds and different gender-identities](reviewer-diversity) whenever possible. pyOpenSci [supports mentoring new reviewers if needed!](review-mentorship) +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 wish, you can use the email template below to invite 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," so as to give a clear +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 -2. the review deadline date. -```{info} -At this point you can add the following to the **Editor Response to Review** under **Editor Comments**: +1. Reviewer GitHub handles and +2. The review deadline date. + +:::{tip} +At this point, you can add the following to the **Editor Response to Review** under **Editor Comments**: `:wave: Hi @reviewer-one and @reviewer-two! Thank you for volunteering to review for pyOpenSci!` -``` +::: - Change the label on the issue to `3/reviewer(s)-assigned` @@ -263,8 +255,8 @@ During the review process, it is important to check in with the reviewers to ensure that things are moving smoothly: - Check in with reviewers and authors occasionally. Offer clarification and help as needed. -- In general aim for 3 weeks for review, 2 weeks for subsequent changes, and 1 week for reviewer approval of changes. -- If a review has not been submitted after 2 weeks, ping the reviewer(s) within the review issue to ensure they are aware of the 3 week deadline. +- Aim for ~3 weeks for review, 2 weeks for subsequent changes, and 1 week for reviewer approval of changes. +- If a review has not been submitted after 2 weeks, ping the reviewer(s) within the review issue to ensure they are aware of the 3-week deadline. ### ✔️ 5. What to do when reviews are in @@ -272,48 +264,57 @@ ensure that things are moving smoothly: If the author stops responding, refer to [the policies](/our-process/policies) and/or ping the other editors in the Slack channel <_Not available publicly yet_> for discussion. -Once the author has responded to the reviews and made appropriate changes made changes: +Once the author has responded to the reviews and made appropriate changes: - Briefly check to ensure that the changes were indeed made. - Change the issue status tag to `5/awaiting-reviewer-response`. ```{important} -If for some reason during the process you need to halt the review and close the issue, be sure to let all parties know (maintainer and reviewers) prior to closing the issue. +If you need to stop the review and close the issue for some reason during the process, please be sure to let all parties know (the maintainer and reviewers) before closing the issue. Be sure to: * explain why the decision was made * thank them for their work -* make a note to assign the reviewer to another submission with high chance of smooth -review next time (e.g. a package author who has already submitted packages to us). +* make a note to assign the reviewer to another submission with a high chance of smooth +review next time (for example, a package author who has already submitted packages to us). ``` +(reviewer-response-time)= +## What to do if reviewers become quiet +In some cases, the reviewers get busy and stop responding to the issue. If a reviewer hasn't responded to a direct ping `@reviewer-user-name` on the issue, try to email them (if an email is available). If email doesn't work and they haven't responded in over a month, do the following: + +1. If they have already submitted a review, you can move the review forward by making sure the review comments were addressed by the author yourself. +2. If the reviewer has not yet submitted a review in the issue, leave a note on the review that you will look for a new reviewer. When you find a new reviewer, replace the old reviewer's name with the new reviewer's name in the YAML at the top of the issue. + +In some cases, you may be able to find an editor or reviewers in the pyOpenSci Slack community that can help move the review forward. + ## Putting a review on hold & handling non-responsive authors In some cases, an author may need more time to respond to review comments. In this case, the author can choose to have -their submission put on hold. As an editor you should apply the `holding label` to the GitHub issue. +their submission put on hold. As an editor, you should apply the `holding label` to the GitHub issue. The holding status will be revisited every 3 months. -After one year the issue will be closed if there is no movement towards responding to reviews by the author. +After one year, the issue will be closed if there is no movement towards responding to reviews by the author. -If the author simply not responding, the editor should: +If the author is not responding, the editor should: - Tag the author (`@author-github-handle`) in an issue comment notifying them that we will close the issue in one month if there is no response. -- Close the issue if one month has passed without a reply. +- Close the issue if two months have passed without a reply. -If needed you can also chose to email the author. using the email provided in the package metadata file of the package. The email -could be in any of the three files in the package: `setup.py`, `pyproject.toml` (preferred) or `setup.cfg`. +Before closing the issue, email the author using the email provided in the package metadata file of the package. The email +could be in any of the three files in the package: `setup.py`, `pyproject.toml` (preferred), or `setup.cfg`. ```{important} -If a submission is closed and the author wishes to re-submit, they will have to start a new submission. +If a submission is closed and the author wishes to resubmit, they will have to start a new submission. If the package is still in scope, the author will have to respond to the first round of reviews first. After that is complete, you can begin looking for new reviewers to -evaluated the package. This ensures that none of the review -energy spent in the first review, goes to waste. +evaluate the package. This ensures that none of the review +energy spent in the first review goes to waste. ``` ### ✔️ 6. How to accept a package into the pyOpenSci ecosystem @@ -343,11 +344,11 @@ Date accepted (month/day/year): UPDATE-THIS-TBD - Once the YAML is updated, change the status tag of the issue to `6/pyOS-approved` 🚀🚀🚀`. - The [listing on the PyOpenSci website](https://www.pyopensci.org/python-packages.html) is updated by a cron job that parses the YAML in all issues with the tag `6/pyOS-approved` 🚀🚀🚀`, so a new package might take a few days to appear; in particular, if there are formatting errors in the YAML that need to be corrected. - - Editors should be able to manually trigger the [cron job](https://github.com/pyOpenSci/pyopensci.github.io/actions/workflows/update-contribs-reviews.yml) and/or check the output of the last run to see if there are any YAML formatting errors. - - Other "after review" tasks like the post-review survey can be done after the package is accepted; the cron job does not depend on them. + - Editors can manually trigger the [cron job](https://github.com/pyOpenSci/pyopensci.github.io/actions/workflows/update-contribs-reviews.yml) and/or check the output of the last run to see if there are any YAML formatting errors. + - Other "after review" tasks, like the post-review survey, can be done after the package is accepted; the cron job does not depend on them. ```{note} -* `Archive` refers to an archive created through a release. You can use zenodo to create this archive and provide the package with a citable DOI. If zenodo is used, please add the Zenodo link and/or badge link here. +* `Archive` refers to an archive created through a release. You can [use Zenodo to create this archive](https://www.pyopensci.org/lessons/package-share-code/publish-share-code/cite-code.html#cite-your-code) and provide the package with a citable DOI. If Zenodo is used, please add the Zenodo link and/or badge link here. * `Version` refers to the final package version that was accepted by pyOpenSci. This is the final version as presented after all feedback from the @@ -381,12 +382,12 @@ eligible to be published with JOSS unless **significant** changes and improvemen to package functionality have been made. ``` -JOSS will accept the pyOpenSci review and direct the author to check their `paper.md` file. Once the package is accepted by JOSS, +JOSS will accept the pyOpenSci review and direct the author to check their `paper.md` file. Once JOSS accepts the package, the author will be instructed to add the JOSS DOI badge to their package **README** file. Once the package is accepted by JOSS and the DOI badge resolves properly: -- Tag the issue with `9/joss-approved`. (please do NOT remove the pyos approved label - simple add the joss approved label) +- Tag the issue with `9/joss-approved`. (Please do NOT remove the `pyos-approved` label, instead add the `JOSS-approved` label) ## Last Steps Before Closing the Review Issue @@ -396,36 +397,10 @@ Once the review is complete, you can close the issue. Before doing that: - Check the pyOpenSci website to ensure: - - The package was properly added to the [pyOpenSci website](https://www.pyopensci.org/python-packages/). + - The package was added to the [pyOpenSci website](https://www.pyopensci.org/python-packages/). - Reviewers and maintainers are listed on the [contributors page](https://www.pyopensci.org/our-community/). - - Make sure the YAML at the top of the issue is fully filled out and up to date. + - Make sure the YAML at the top of the issue is filled out and up to date. -- If the package is approved by JOSS, be sure that the issue is tagged with `7/JOSS-approved` and that the archive / DOI information at the top is updated with the JOSS archive before closing the issue. +- If JOSS approves the package, be sure that the issue is tagged with `7/JOSS-approved` and that the archive / DOI information at the top is updated with the JOSS archive before closing the issue. Congratulations, you have completed a review for pyOpenSci! - - - - - - diff --git a/how-to/onboarding-guide.md b/how-to/onboarding-guide.md index 3aad1d47..cccc98ec 100644 --- a/how-to/onboarding-guide.md +++ b/how-to/onboarding-guide.md @@ -112,9 +112,6 @@ to them either in a private Slack message or via email, at ::: - - - ## Starting the editorial search To begin, first post in our `private-editorial-team` slack channel to see if any of our existing [Editorial Team](https://www.pyopensci.org/about-peer-review/index.html#meet-our-editorial-board) members can identify past reviewers or other people they know that might be a good editorial candidate. @@ -155,14 +152,12 @@ an individual Direct Message (DM) because: * It allows other community members who may know of potential editors to see the request and potentially respond. ::: -Our Community Manager interacts with the broader community and partner communities and as such often interacts with people who may be interested in joining our pyOpenSci review team. The Community Manager may from time to time meet community members who might make great editors or reviewers. In those cases they will share that information with the current Editor in Chief and Software Review Lead. +Our Community Manager engages with the broader community and partner communities, frequently interacting with individuals interested in joining our pyOpenSci review team. The Community Manager may, from time to time, meet community members who might make great editors or reviewers. In those cases, they will share that information with the current Editor in Chief and Software Review Lead. :::{todo} pyOpenSci anticipates being able to send targeted emails to community members that meet certain criteria related to domain expertise by the Fall of 2024. Please reach out to the pyOpenSci Community Manager with any questions about this process! ::: - - :::{note} It is important that a new reviewer or a new editor fill out the appropriate form prior to onboarding. @@ -183,27 +178,29 @@ When the EIC has identified an editor who is not currently part of the pyOpenSci * Welcome the individual in Slack, and provide them with access to the `#private-editorial-team` and any other channels as needed. :::{note} -The Community Manager will ensure that any new member that joins our Slack workspace is welcomed and set up with anything they need in our pyOpenSci Slack workspace. +The Community Manager will ensure that any new member who joins our Slack workspace is welcomed and set up with anything they need in our pyOpenSci Slack workspace. ::: ## Process for inviting a new editor * Editorial board candidates most often start as guest editors. -* After 3 months or their first review (which ever comes first), the Software Review Lead working with the EiC will assess how the +* After 3 months or their first review (whichever comes first), the Software Review Lead working with the EiC will assess how the review process went. Allow other editors to provide input as well. -* Once it is determined that the guest editor is committed to support the pyOpenSci -review process, you can email them to fully participate on the editorial board +* Once it is determined that the guest editor is committed to supporting the pyOpenSci +review process, you can email them to participate on the editorial board using the template below. ``` Hi [NAME HERE]: We would like to formally invite you to join the pyOpenSci editorial board as a full -member. [*SPECIFIC REASONS FOR INVITATION (mention contributions TO pyOpenSci)*]. +member. [*SPECIFIC REASONS FOR INVITATION (mention contributions to pyOpenSci)*]. We think you will make a wonderful addition to our pyOpenSci open review team! -[IF GUEST EDITOR: You are familiar with the editor's role as you've been a guest editor]. We aim for editors to handle reviews for four packages per year +[Here is an onboarding document to help you navigate your first weeks in this role.](https://docs.google.com/document/d/1UfG1Fe5wSiEAObvqNMT4etZ5sx7QXzW0f8mozKyK1NE/edit?tab=t.0) + +[IF GUEST EDITOR: You are familiar with the editor's role, as you've been a guest editor]. We aim for editors to handle reviews for four packages per year ([IF GUEST EDITOR including the one that you just finished!]). We ask that editors make an informal commitment to serve for two years and re-evaluate their participation after that. @@ -211,16 +208,16 @@ On a short-term basis, any editor can decline to handle a package or say, "I'm pretty busy, I can't handle a new package for a few weeks." In addition to handling packages, editors weigh in on group editorial decisions, -such as whether a package is in-scope, and determining updates to our policies. +such as whether a package is in scope, and support updates to our policies. We generally do this through Slack, which we expect editors to be able to check regularly. We have editorial board calls annually. -Every 3-6 months the Editor-in-Chief responsibilities rotate to a new editor. +Every 3-6 months, the Editor-in-Chief's responsibilities rotate to a new editor. You'll have the opportunity to enter this rotation once you have been on the editorial board for at least 6 months. OPTIONAL: Some editors also take on bigger projects to support pyOpenSci and -improve the peer-review process. This is entirely optional but please let us +improve the peer-review process. This is entirely optional, but please let us know if you are interested in additional activities that support the organization. We hope that you'll join our growing editorial board! diff --git a/how-to/review-triage-team.md b/how-to/review-triage-team.md index 7270b021..d324fab4 100644 --- a/how-to/review-triage-team.md +++ b/how-to/review-triage-team.md @@ -1,18 +1,18 @@ # Editorial Review Triage Team -The editorial board triage team focuses on ensuring review issues are complete with all metadata filled out in each GitHub review issue. Members of this team are considered a integral part of the [pyOpenSci editorial board](https://www.pyopensci.org/about-peer-review/index.html#our-editorial-board). +The editorial board triage team focuses on ensuring review issues are complete with all metadata filled out in each GitHub review issue. Members of this team are considered an integral part of the [pyOpenSci editorial board](https://www.pyopensci.org/about-peer-review/index.html#our-editorial-board). ## Estimated time allocation for this team -It is estimated that the time associated with this role will be a few hours a month given we normally accept 1-2 packages each month. +It is estimated that the time associated with this role will be a few hours a month, given we normally accept 1-2 packages each month. ```{note} There may be (rare) periods where additional time is needed. These include -1) when we need to update old, dated reviews and -2) if many submissions are accepted in a particular month. +1. When we need to update old, dated reviews and +1. If many submissions are accepted in a particular month. -In the case that a time-intensive update process is required such as a large -update to the review metadata structure, we can instill the help of others on +In the case that a time-intensive update process is required, such as a large +update to the review metadata structure, we can enlist the help of others on the editorial board to get caught up. This role should never be a burdensome role on any individual community @@ -67,15 +67,15 @@ Documentation: https://gemgis.readthedocs.io/en/latest/ JOSS Publication: https://joss.theoj.org/papers/10.21105/joss.03709 # We want to add the JOSS publication as well - but let's figure out a standardized way to do it. I think the JOSS badge would be great to display on our website. Editor: TBD Reviewer 1: TBD -Reviewer 2: TBD # Sometimes there may be a third reviewer particularly in a mentorship situation or when specific domain expertise is required +Reviewer 2: TBD # Sometimes there may be a third reviewer, particularly in a mentorship situation or when specific domain expertise is required Archive: TBD Version accepted: TBD Date accepted (month/day/year): TBD ``` -At the end of a review, the completed metadata should look something like the example below with all metadata items containing text. +At the end of a review, the completed metadata should look something like the example below, with all metadata items containing text. -Notice in the example below this particular review is missing the archive information and instead has `TBD`. This item should contain either a zenodo link to a tagged release or a tagged release link on GitHub. It is also missing the version accepted. But this review was accepted, as such we will want to update the metadata in the issue. +Notice in the example below, this particular review is missing the archive information and instead has `TBD`. This item should contain either a Zenodo link to a tagged release or a link to a tagged release on GitHub. It is also missing the version accepted. Since this review was accepted, we will update the metadata in the issue. ```markdown Submitting Author: Sam Pottinger (@sampottinger) @@ -104,16 +104,15 @@ If it is missing those labels please add them as it makes sense for the state of The review issue triage team's role is to do the following: - Ensure that after each review is closed, all metadata are filled out -- Ensure that labels are updated accordingly. These labels are what we use to parse reviews that end up posted on our website, if they aren't labeled correctly they will not get automagically added. +- Ensure that labels are updated accordingly. These labels are what we use to parse reviews that end up posted on our website. If they aren't labeled correctly, they will not get automagically added. - Ensure that the [post-review survey filled out](https://docs.google.com/spreadsheets/d/1jEk-DDpkz14Z07OX_o1cN2vHzVbJO6mQ83ihGXsWkLc/edit#gid=0) (for issues opened after March 2023). Note this page is only accessible to our editorial team and only contains names / gh user names of people who filled out the survey rather than any survey data. -- Help the software review lead update older issues when metadata items is missing. -- Update review status on project board -- Post on the [pyOpenSci Discourse packages channel](https://pyopensci.discourse.group/c/packages/8) announcing & celebrating that a successful review has been completed! +- Help the software review lead update older issues when metadata items are missing. +- Post on the pyOpenSci Slack #pyos-updates channel announcing & celebrating that a successful review has been completed! - Make sure JOSS tracking is happening as expected The team might also do the following in some cases: -- Close issue if it is open but complete +- Close the issue if it is open, but complete ## Celebrating accepted packages @@ -122,32 +121,18 @@ We like to celebrate when a package is 1. accepted by pyOpenSci and 2. accepted by JOSS -As such the editorial triage team will post on the [pyOpenSci discourse site](https://pyopensci.discourse.group/c/packages/8) when we have a new accepted package. - -To post on Discourse do the following: - -1. head to Discourse and create a new post in the packages channel -2. tag the post with `pyos-acccepted` - -:::{figure-md} fig-target - -image showing the top of a discourse post with the title text in the text box that reads - welcome pynteny and crowsetta to the pyOpenSci ecosystem. Below you see two boxes, on the left is a red square with the word packages next to it. on the right is the tag pyos-accepted with an x next to it. - -Image showing the discourse interface when you add a new post. The pyos-accepted tag is found under the the text box where you add the post title. -::: - -Once you create the post, it will be cross-posted into the pyopensci-slack in the `software-review` channel via an automated slack-discourse bridge. +The editorial triage team will post on the pyOpenSci Slack `#pyos-updates` channel when we have a new accepted package. ## Updating reviews & contributors using GitHub actions -The issue review team can also, as they wish update packages and reviewers on the website by enabling the update_reviews and update_contributors workflow. Or by simply merging an open PR as the action will run every few days submitting a new pull request. +The issue review team can also, as they wish, update packages and reviewers on the website by enabling the update_reviews and update_contributors workflow. Alternatively, you can merge an open PR, which will run the action every few days and submit a new pull request. To do this: 1. [Head to the pyOpenSci website repo](https://github.com/pyOpenSci/pyopensci.github.io/actions/workflows/update-contribs-reviews.yml). 2. Click the run workflow button to trigger a build that will update reviews and also editors, reviewers and associated contributions! -:::{figure-md} fig-target +:::{figure-md} contribs-action Image on a black background of the GitHub interface. on the right you can see a list of action names - 5 total. the one action Update Contribs & reviewers has a blue line next to it indicating it is the action being viewed on the screen. On the right of the image you see a run workflow button which is what needs to be pressed to manually make that action run @@ -156,7 +141,7 @@ When you go to the actions tab in github, you will see the Update Contribs and r Once you trigger this, the action will run and submit a pull request. -:::{figure-md} fig-target +:::{figure-md} run-contrib-action Image showing a pull request with the title Update contributor and review data. The first comment is from the github-actions bot and says automated changes by create-pull-request GitHub action. @@ -167,7 +152,7 @@ You may notice that the pull request has a pre-commit failure. You can fix that `pre-commit.ci autofix` -:::{figure-md} fig-target +:::{figure-md} pre-commit-autofix Image showing the github action results on a pull request. the pre-commit.ci - pr check has a failing x next to it. @@ -180,11 +165,11 @@ 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 in to 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/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. -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. +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. -:::{figure-md} fig-target +:::{figure-md} accepted-package Image on a black background of the GitHub interface. Generally what this shows is the template message that is provided by pyOpenSci when a package is accepted. It starts with hey there, username and then congratulates them for being accepted. Finally it provides a list of last steps needed to close out the review. @@ -198,55 +183,48 @@ and @alizma for reviewing this package! 😸 ## How to confirm that the post-survey was filled out -At the end of each review we ask reviewers and the maintainers to fill out the post survey. You can check whether this has been completed by [looking at this document](https://docs.google.com/spreadsheets/d/1jEk-DDpkz14Z07OX_o1cN2vHzVbJO6mQ83ihGXsWkLc/edit?usp=sharing). NOTE: only editors have access to view this document. It simply contains a list of GitHub usernames that have completed the survey and the associated date. It will allow you to confirm that step was completed! +At the end of each review, we ask reviewers and maintainers to fill out the post survey. You can check whether this has been completed by [looking at this document](https://docs.google.com/spreadsheets/d/1jEk-DDpkz14Z07OX_o1cN2vHzVbJO6mQ83ihGXsWkLc/edit?usp=sharing). NOTE: only editors have access to view this document. It simply contains a list of GitHub usernames that have completed the survey and the associated date. It will allow you to confirm that the step was completed! ## Adjusting labels & the project board on an issue Every issue has a label associated with it that tells us what -part of the process the review is in. Our automated workflow, +part of the process the review is in. Our automated workflow finds packages that were accepted using the `6/pyOS-approved` tag (see below). -:::{figure-md} fig-target +:::{figure-md} accepted-review-label -Image that shows an accepted review. The editor is the assignee. The labels on the review say 6/pyos-approved with 3 rocket emojis next to it. below is 7/under-joss review which is a green label. +Image that shows an accepted review. The editor is the assignee. The labels on the review say 6/pyos-approved with three rocket emojis next to it. Below is 7/under-joss review, which is a green label. -If a package has been accepted it should have at least the pyos-approved label. If the package moves on to joss and is accepted it should have the joss label as well. If the package is actively in joss review it should have the under-joss review. Otherwise if it has been accepted it should have the 9/joss-accepted label. +If a package has been accepted, it should have at least the pyos-approved label. If the package moves on to JOSS and is accepted, it should have the JOSS label as well. If the package is actively under review by JOSS, it should be marked as such. Otherwise, if it has been accepted, it should have the `9/joss-accepted` label. ::: -Often times it's easy for an editor to celebrate a review ending and forget to add that final tag. Or sometimes they might forget that they need to follow the package as it goes through the JOSS process (if it goes on to that process). +Oftentimes it's easy for an editor to celebrate a review ending and forget to add that final tag. Or sometimes they might forget that they need to follow the package as it goes through the JOSS process (if it goes on to that process). The triage team should ensure that all accepted packages have the `6/pyOS-approved` label associated with them. You can remove any other labels on the issue once a package is approved. We can assume it's gone through all of the appropriate checks! -In the case of a JOSS submission after our review, you can make sure that the editor is updating the label on the issue associated with JOSS. the final label once the package is JOSS accepted is -9/JOSS-approved +In the case of a JOSS submission after our review, you can make sure that the editor is updating the label on the issue associated with JOSS. The review, once complete and accepted by both pyOpenSci and JOSS, should have two labels: -:::{figure-md} fig-target +* `6/pyos-approved` +* `9/JOSS-approved`. -Image that shows the three options for joss labels. 7/under-joss-review, 8-joss-review-complete and 9/joss-approved. +:::{figure-md} joss-labels -The joss labels indicate the state that a package is in. -Once JOSS has accepted the package, you should ensure that 9/joss-approved if the final label. At this point the package review issue can be closed if all lose ends are complete! -::: - -### Updating the software-review project board - -We keep track of our reviews using the peer-review-status project board. +Image that shows the three options for JOSS labels. 7/under-joss-review, 8-joss-review-complete and 9/joss-approved. -:::{figure-md} fig-target - -Image that shows the empty assignees section for a new review. Also there are 2 labels 1/editor checks and new submission. Finally there is a project board available however the status is not yet set. - -When a review is just starting, the assignee should be the editor leading the review. The labels will begin with editor-checks. You can also set the peer-review state on the project board. +The JOSS labels indicate the state that a package is in. +Once JOSS has accepted the package, ensure the final label has both `6/pyos-accepted` and `9/joss-approved`. At this point, the package review issue can be closed if all loose ends are complete! ::: -When a package is accepted you can also update the project board to the "pyos-accepted" (or JOSS accepted) status. Given the nature of our partnership with JOSS, we can always assume that if a package got to the JOSS stage it was already accepted by pyOpenSci. +### Assign the issue to the editor leading the review + +Make sure that the issue is assigned to the editor leading the review. This step is often missed in our review process. -:::{figure-md} fig-target +:::{figure-md} start-review -Image showing the project board in a review. the project board says peer-review-status. It also shows the drop down options which include under-review which is checked, pyos-accepted, pre-submission and joss accepted. +Image that shows the empty assignees section for a new review. Also, there are two labels 1/editor checks and new submission. -We use the project board to track the status of reviews. +When a review is just starting, the assignee should be the editor leading the review. The labels will begin with `editor-checks`. ::: ## Organization permissions needed for the editorial triage team @@ -259,5 +237,4 @@ Team members will need: - to be a part of the pyOpenSci GitHub organization - merge permissions on [pyopensci.github.io repository.](https://github.com/pyOpenSci/pyopensci.github.io) - edit permissions for reviews in the software-submission repository -- access to post in the slack pyos-updates channel -- an account in the [pyOpenSci discourse](https://pyopensci.discourse.group/c/pyopensci-updates/13) to post updates there. +- access to post in the Slack `pyos-updates` channel diff --git a/noxfile.py b/noxfile.py index 22d9e68c..41c9f8ec 100644 --- a/noxfile.py +++ b/noxfile.py @@ -1,9 +1,34 @@ import nox +import pathlib nox.options.reuse_existing_virtualenvs = True build_command = ["-b", "html", ".", "_build/html"] +AUTOBUILD_IGNORE = [ + "_build", + ".nox", + "build_assets", + "tmp", + ".pytest_cache", +] + +# Sphinx output and source directories +BUILD_DIR = "_build" +OUTPUT_DIR = pathlib.Path(BUILD_DIR, "html") +SOURCE_DIR = pathlib.Path(".") + +# Sphinx build commands +SPHINX_BUILD = "sphinx-build" +SPHINX_AUTO_BUILD = "sphinx-autobuild" + +# Sphinx parameters used to build the guide +BUILD_PARAMETERS = ["-b", "html"] + +# Sphinx parameters used to test the build of the guide +TEST_PARAMETERS = ["-W", "--keep-going", "-E", "-a"] + + @nox.session def docs(session): session.install("-r", "requirements.txt") @@ -15,14 +40,26 @@ def docs(session): @nox.session(name="docs-live") def docs_live(session): session.install("-r", "requirements.txt") - - AUTOBUILD_IGNORE = [ - "_build", - "build_assets", - "tmp", - ] cmd = ["sphinx-autobuild"] for folder in AUTOBUILD_IGNORE: cmd.extend(["--ignore", f"*/{folder}/*"]) cmd.extend(build_command + session.posargs) session.run(*cmd) + + +@nox.session(name="docs-test") +def docs_test(session): + """ + Build the packaging guide with more restricted parameters. + + Note: this is the session used in CI/CD to release the guide. + """ + session.install("-e", ".") + session.run( + SPHINX_BUILD, + *BUILD_PARAMETERS, + *TEST_PARAMETERS, + SOURCE_DIR, + OUTPUT_DIR, + *session.posargs, + ) diff --git a/partners/joss.md b/partners/joss.md index 5e7d3fb3..d539066c 100644 --- a/partners/joss.md +++ b/partners/joss.md @@ -1,3 +1,4 @@ +(joss)= # pyOpenSci and Journal of Open Source Software (JOSS) Partnership pyOpenSci has a formal partnership with diff --git a/partners/scientific-communities.md b/partners/scientific-communities.md index 3d4f2165..b72cb2d0 100644 --- a/partners/scientific-communities.md +++ b/partners/scientific-communities.md @@ -1,3 +1,4 @@ +(partner-communities)= # Partnerships with scientific Python Communities diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..e4a4cd5b --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,53 @@ +[build-system] +requires = ["hatchling", "hatch-vcs"] +build-backend = "hatchling.build" + +[project] +name = "peer-review-guide" +dynamic = [ + "version" +] +dependencies = [ + "pyos_sphinx_theme", + "myst-nb", + "sphinx", + "sphinx-autobuild", + "sphinx-copybutton", + "sphinx-design", + "sphinx-favicon", + "sphinx-togglebutton", + # XML feed for analytics + "sphinx-sitemap", + # Support for social / adds meta tags + "sphinxext-opengraph", + "sphinx-inline-tabs", + # for project cards + "matplotlib", + "pandas", + "sphinx-codeautolink", + "rich", + "sphinxcontrib-youtube", +] + +[project.optional-dependencies] +dev = [ + # for general build workflows + "nox", +] + +[tool.hatch.build.targets.wheel] +bypass-selection = true + +[tool.hatch] +version.source = "vcs" + + +# https://github.com/codespell-project/codespell#usage +[tool.codespell] +#ignore-words = "codespell-ignore.txt" +skip = "./.git,./.nox,./_static,./_build,codespell-ignore.txt,*.svg" + + +[tool.jupytext] +# Pair ipynb notebooks to py:percent text notebooks +formats = "ipynb,myst" diff --git a/requirements.txt b/requirements.txt index 60d1ac6c..42205c1f 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -pydata-sphinx-theme==0.14.4 +pyos-sphinx-theme myst-nb sphinx sphinx-autobuild