Onboarding and offboarding editors#

pyOpenSci peer review runs on volunteer editors and reviewers. Finding new volunteers is often the trickiest part of the process, so we’ve built resources to help you. This page is for you if you’re the Editor in Chief (EiC) or the Software Review Lead. It walks you through finding, onboarding, inviting to the board, and offboarding editors.

How we support you#

You don’t have to do this alone. Here’s what’s in place:

  • Your editorial board. Ask them first. They often know great candidates.

  • Our Community Manager. They can post open calls, write blog posts, and introduce you to people they meet in the community.

  • Our contributor pool. Past authors, reviewers, and guest editors are all people who already know us.

  • Editor mentorship. New editors without prior experience get paired with a seasoned editor for their first review(s).

  • Automated website updates. Add someone to the right GitHub team, run one workflow, and merge the pull request it opens. The website listing updates once the data are updated. See how the website updates.

About the editorial board#

Our peer review process depends on a well-balanced editorial board. As you recruit, look for combined expertise in:

  • Science domains that fall within the scope of our peer review process

  • Python packaging

  • Documentation and package usability

  • CI and test suites for robust software development

We also work to build a board with people from different backgrounds, cultures, genders, and domains.

Types of editors#

New editors start as guests#

A new editor is a guest editor for their first 3 months, or until they complete leading their first review process from start to finish. After that review process is complete, you and the current editorial board decide whether they become a full editor.

Ad hoc guest editors#

An ad hoc editor has the specific skills needed to lead a single review. You might need one when:

  • There’s a conflict of interest between a package submitter and the editorial team (for example, a close colleague of everyone on the team)

  • The editorial board is at capacity with the current review load

  • A review needs a very specialized skill set (a one-off situation)

In these cases, try our internal reviewer sign-up list. Someone who signed up to review may be happy to serve as an editor.

Experience and mentorship#

We prefer editors who have some experience reviewing software, such as a previous review with pyOpenSci, rOpenSci, or JOSS.

If a volunteer doesn’t have that experience, that’s okay. Our mentorship process pairs them with an experienced editor who guides them through their first review(s).

Who does the recruiting#

Recruiting new editors and keeping the board well-balanced is the responsibility of the Software Review Lead, with support and advice from the EiC team.

Find new editors#

The Editor in Chief team and Software Review Lead work together to find and onboard editors, especially in scientific areas where we have gaps.

Start with your network#

Good candidates to be editors can come from:

  • Our existing reviewer pool

  • Your professional network. You may know people in a specific domain who would be a great fit.

  • Our contributor pool, which includes:

    • Package authors and maintainers who have submitted a package for review

    • Reviewers who have led reviews for pyOpenSci

    • Past guest editors

  • Colleagues who have reviewed for the Journal of Open Source Software (JOSS) or rOpenSci and have Python expertise

  • Community members in the pyOpenSci Slack (post a call in #software-review)

Ask the editorial board#

Post in the private-editorial-team Slack channel. Ask whether any editors can suggest past reviewers or other people who might be a good fit.

If the conversation turns to specific candidates:

  • Start a private group message to discuss them. This keeps names out of a channel history that a future editor might stumble on (awkward for everyone!).

  • Ping editors with @here so they get a notification. This is an important topic.

IMPORTANT: Give editors up to a week to chime in before you onboard a new editor.

Ask the Community Manager for help#

If those options don’t turn up a candidate, our Community Manager can help. They can:

Note

Here’s an example of a social post recruiting editors. We’ve also run a blog post and call-outs in our monthly and weekly newsletters.

To request this support, post in the public #software-review Slack channel and ping the Community Manager. Include:

  • That you’re looking for editors

  • Any specific domains or technical skills you need, or note that it’s a general call

  • Any specific packages that need an editor (link to the submission the new editor would lead, if possible)

Tip

Post in #software-review rather than sending a DM. Other editors can see what expertise you need and that this support exists, and community members who know potential editors can respond.

The Community Manager also meets people through the broader community and partner communities who may make great editors or reviewers. When that happens, they’ll pass the names along to you.

pyOpenSci also maintains a database of contributors, and the Community Manager can help you find people who may be a good fit. Reach out in a private Slack message or by email at media@pyopensci.org.

Note

Before onboarding, make sure the new reviewer or editor has filled out the right form:

Onboard a new editor#

New editors usually start as guest editors. As a member of the Editor in Chief team, you work with the Software Review Lead to get them set up. Most of it is Slack and a warm welcome. GitHub is the only technical part.

Slack#

  • If they’re new to the pyOpenSci community, send them a Slack invitation (or ask the Community Manager to do so).

  • Welcome them in Slack and give them access to #private-editorial-team and any other channels they need.

  • Post a welcome message in the editor channel and ping all editors.

Introduce them to the Community Manager#

Message the Community Manager and the new editor in Slack to introduce them. The Community Manager makes sure new members are welcomed and have what they need in Slack. They’ll also work with the new editor on an introductory blog post, which gets published on the pyOpenSci blog, shared on social media, and included in an upcoming newsletter.

Security#

Ask the new editor to turn on two-factor authentication (2FA) for GitHub if they haven’t already. It’s required to join our GitHub organization.

GitHub access#

You (as the EiC or Software Review Lead) add editors to our GitHub organization. To do so, you’ll need permission to:

  • Invite members to the pyOpenSci organization

  • Add or remove people on editorial teams

  • Run a workflow and merge a pull request on pyopensci.github.io (only needed if you want to update the website listing before the weekly run)

GitHub repository access is managed using GitHub teams. Add the person to a team and they will have access to the repositories that team needs. The handbook’s editorial teams page has a table of every team, what it grants, and how a guest editor can join without a team.

Guest editors (a new editor during their first review, or an ad hoc editor for one review):

  • Add them to the editorial-board team for the duration of their editorial work. The team grants the repository access they need and lists them on the website while they’re editing.

  • When that work ends, remove them from the team. Don’t add them to an emeritus team unless they later serve on the board and then step down.

Board editors: add them to every team that matches their role. Being on the parent peer-review-team alone doesn’t list them.

If you add someone who isn’t already in the organization, GitHub also invites them. They won’t be on the team, or listed on the website, until they accept the organization invitation.

Note

If someone can’t join the organization, add them to data/manual-editorial-roster.yml in the website repository instead of a GitHub team. That’s the only editorial file you should ever edit by hand.

How the website updates#

Two workflows in the pyopensci.github.io repository read the GitHub teams and open a pull request that updates the editorial YAML files. The website listing changes once you merge that pull request.

  • Update editorial board runs every Wednesday. It only checks team membership, so it finishes quickly and opens a small pull request.

  • Update Contribs & reviewers runs every Monday. It also refreshes the editorial files, but only after re-scanning every repository and review issue. That makes it slower and its pull request much larger.

Tip

After you change a team, don’t wait for the next scheduled run. Go to the Actions tab in pyopensci.github.io, choose Update editorial board, select Run workflow, and merge the pull request it opens. Use this one rather than Update Contribs & reviewers. It’s the fast one.

        flowchart LR
  Membership[Update GitHub team] --> Cron[Run Update editorial board]
  Cron --> PR[Merge the pull request]
  PR --> Live[Editorial team updated on the website ✨]

Don’t hand-edit editorial-board.yml, emeritus-editors.yml, or editorial flags in contributors.yml. The workflows update them automatically, and hand edits can be overwritten. For the bigger picture, see how pyOpenSci data flows and the infrastructure overview in the handbook.

Check that it worked#

Once the person has accepted the organization invitation and you’ve merged the pull request, they should appear on the editorial board page. If they don’t, check that they accepted the invite and that they’re on the right team.

Invite a guest editor to join the board#

After 3 months or their first review (whichever comes first), you and the EiC assess how it went. Invite other editors to weigh in too.

Once you’re confident the guest editor is committed to supporting our review process, email them an invitation to join 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)*].
We think you will make a wonderful addition to our pyOpenSci open review team!

[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.
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 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'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
know if you are interested in additional activities that support the organization.

We hope that you'll join our growing editorial board!

Please give this some thought, ask us any questions you have, and let us know
whether you can join us.

Best,
[your-name-here], on behalf of the pyOpenSci Editorial Board

When they say yes#

A guest editor is already on the editorial-board team, so promoting them doesn’t require a team change. If they take on a specialty role (Editor in Chief, Software Review Lead, or triage), add them to the matching team from GitHub access, then update the website using how the website updates. Announce the good news in #private-editorial-team.

Offboard an editor#

When an editor steps down, thank them for their work first. Then update Slack, GitHub, and the website.

Guest editors who have finished their review:

  • Remove them from editorial-board.

  • Don’t add them to an emeritus team. That’s only for people who served on the board.

Board editors:

  • Announce that they’re stepping down, and thank them, in the #software-review Slack channel. Then remove them from the #private-editorial-team channel.

  • Remove them from every active editorial team: editorial-board, plus eic-team, peer-review-lead, or triage-team if they were on those.

  • Add them to emeritus-editors. If they held a specialty role, also add them to the matching emeritus team:

Then update the website the same way as when you add someone. Follow how the website updates: run Update editorial board and merge the pull request.