Onboarding New Editors

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!

Below we discuss processes for finding and onboarding new volunteers to our peer review process.

About the Editorial Board

The success of our peer review process is dependent upon a well-balanced editorial board. Our board needs to have combined expertise in:

• A suite of specific science domains that fall within the scope of our peer review process

• Technical expertise in Python packaging

• Awareness of the importance of documentation and package usability

• Awareness of the importance of CI / test suites to ensure robust software development

We also strive to ensure our editorial team is diverse and comprised of people from different backgrounds, cultures, genders, and domains.

Types of Editors

New Editors Start as “Guests”

A new editor will be considered a guest editor for the first 3 months of their tenure and/or until they have completed their first review. Once they have completed a review, they can be considered a full editor as deemed appropriate by the Software Review Lead and the current editorial board.

ad hoc Guest Editors

Adhoc editors are editors with specific skill sets that are brought in to lead a single review. Examples of when there might be a need for an ad hoc editor include:

• If there is a conflict of interest between a package submitter and the editorial team (e.g., a close colleague of everyone on the team)

• If the editorial board is at capacity handling the current review load

• If a very specialized skill set is needed (in a one-off type of situation)

In this case, you may consider using our internal reviewer sign-up list to see if someone who signed up to be a reviewer might want to serve as an editor.

Experience Required to Be an Editor

We prefer that editors have some experience with reviewing software. This experience could come from a previous review they worked on with pyOpenSci, rOpenSci, or JOSS.

Editorial Mentorship

If a potential volunteer does not have prior software editorial experience, we offer a mentorship process. Editor mentorship is where someone with existing editorial experience mentors the new editor through their first review(s).

Recruiting New Editors

Recruiting new editors and maintaining a sufficient and well-balanced editorial board is the responsibility of the Software Review Lead with support and advice from the editorial board.

Note

For the time being, the Software Review Lead role is being filled by the Executive Director with support from the Editor in Chief as we define our process and track the volume of submissions that we need to support. In the future, we will find someone with interest in leading peer review for pyOpenSci.

Where to Find New Editors

Typically the Editor in Chief will work with the Software Review Lead to find and onboard new editors in scientific topical areas where pyOpenSci has existing gaps.

You might find good candidates to be an editor through:

• Your professional network: you may know people in a specific domain that might be a good fit to be an editor for pyOpenSci.

• Our pyOpenSci list of contributor pool which includes:

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

  • Reviewers who have already led reviews for pyOpenSci

  • Past guest editors

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

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

When all of the above fails to return a good new editor candidate, you can find support from our pyOpenSci Community Manager who will post an open call on our social media channels with a link to our editorial board sign-up form. Using our online network will allow you to cast an even wider net to find new interested editors.

Starting the editorial search

To begin, first post in our private-editorial-team slack channel to see if any of our existing Editorial Team members can identify past reviewers or other people they know that might be a good editorial candidate.

If there is a discussion around specific candidates, be sure to:

• Start a private group message for discussion about particular candidates. This ensures there is not a visible history in a public channel that a new editor may see in the future (this could be awkward for someone to see!)

• Ping editors using @here to be sure they get a notification, as this is an important topic.

IMPORTANT: Provide up to a week of time for editors to chime in before onboarding a new editor.

Leverage pyOpenSci social channels to find editors

If you have tried all of the above and still aren’t able to find a new candidate, then the pyOpenSci Community Manager can assist you by:

• Posting on our social media channels about the position.

• Writing a call for editors blog post about our current editorial needs.

Note

See an example here of a post that seeks to recruit editors, a blog post, and call-outs in both our monthly and weekly newsletters.

To get support from the Community Manager in recruiting editors (or reviewers) follow the process below:

• Post in our public #software-review slack channel pinging the community manager (@username). In your post, include the following details:

  • That you’re looking for editors.

  • Any specific domains or technical skills you need an editor to have, or if it’s a general call for editors.

  • Any specific packages that need an editor (include links to a package submission that they would lead if possible).

Tip

It’s helpful to post in our #software-review channel rather than an individual Direct Message (DM) because:

• It allows other editors to see the type of expertise that you are requesting and that we offer this support from our Community Manager.

• 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.

Note

It is important that a new reviewer or a new editor fill out the appropriate form prior to onboarding.

• reviewer signup form

• editor signup form

On-boarding a new editor

The Editor in Chief, working closely with the Software Review Lead, is responsible for inviting and onboarding a new editor to our peer review process.

When the EIC has identified an editor who is not currently part of the pyOpenSci community, they should:

• Extend a Slack invitation to the individual (or ask our Community Manager to do so)

• 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.

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 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 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!

[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 determining 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.
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

Onboarding a new editor

To onboard a new editor:

• Message the pyOpenSci Community Manager and the new editor in Slack, introducing them to one another. The Community Manager will collaborate with the new editor to create a blog post introducing them, which will in turn get posted on the pyOpenSci blog, promoted on social media, and included in an upcoming newsletter.

• Ask the new editor to turn on two-factor authentication (2FA) for GitHub if they haven’t already done so.

• Give editors permissions they will need on GitHub to manage reviews:

  • For ad-hoc guest editors: invite the editor to the software-submission repository with “maintain” permissions.

  • For new editors (not ad-hoc): invite editors to the pyOpenSci GitHub organization as a member of the editorial-board team. This will give them appropriate permissions and allow them to get team-specific notifications.

• Add the new editor to the pyOpenSci Slack workspace and specifically the private-editorial channel.

• Post a welcome message for the new editor in the editor channel, pinging all editors.

• Update the website contributors.yml file with the name of the new editor.

Note

We have a bi-weekly cron job that parses through existing issues and grabs the names of editors, reviewers and authors. However, if you want the editors name to be listed on the website prior to a review beginning and/or sooner than the cron job might pick up their name, then we suggest that you add their name, and GitHub username and title to the contributors.yml file through a pull request.

You do not need to fill out all of the elements of the YAML file - only the name, GitHub user field and the editorial_board: true key:value pair.

- name: FirstName LastName
  github_username: ghuser
  github_image_id: 1234566
  title:
    - Editor # Title to be listed under their name
  # ..... #
  editorial_board: true # Be sure editorial_board is set to true
  emeritus_editor: false # Emeritus is initially set to false
  # ..... #
  contributor_type:
    - editor # This field will be automatically updated after their first review
    - guidebook-contrib
    - reviewer

Off-boarding an editor

When it is time for an editor to step down, do the following:

• Thank them for their work!

• Remove them from the editors-only Slack channel and the editors GitHub team.

• Move them to emeritus-editor on the pyOpenSci website as follows:

- name: FirstName LastName
  github_username: ghuser
  github_image_id: 1234566
  # ..... more here ... #
  editorial_board: false # Be sure editorial_board is set to FALSE
  emeritus_editor: true # Emeritus is now true if they've served as an editor
  # .. #
  contributor_type:
    - editor # This field will be automatically updated after their first review
    - guidebook-contrib
    - reviewer