9  Editorial management

Guidance for managing the editorial team and the dev guide.

9.1 Recruiting new editors

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

Steps:

  • Start a private channel for discussion (so that it does not have a history in the editors channel that future editors will join, which could be awkward).

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

  • Wait for a majority of editors to chime in before inviting someone. Leave them one week to respond.

9.2 Inviting a new editor

  • Editorial committee members generally start by being guest editors.

  • Send an email.

We would like to invite you to join the rOpenSci editorial board as a full member. [SPECIFIC REASONS FOR INVITATION (MENTION CONTRIBUTIONS TO ROPENSCI)]. 
We think you would make a wonderful addition to the 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 four packages per year ([IF GUEST EDITOR including the one you just finished!]).  
We ask that editors make an informal commitment of serving 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.  
We also rotate Editor-in-Chief responsibilities (first-pass scope decisions and assigning editors) amongst the board about quarterly. 
You'll have the opportunity to enter this rotation once you have been on the board for some time, usually at least six months. 
Some of us also take on bigger projects to improve the peer-review process, though this is entirely optional. 

We hope that you'll join the board!  
It's an exciting time for peer-review at rOpenSci.

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

Best,
[EDITOR], on behalf of the rOpenSci Editorial Board

9.3 Onboarding a new editor

  • Add to “team.json” file of website with "editor": true, and also "stats": true for stats editors. That will automatically add new editors to the editorial team shown on the rOpenSci website.

  • Inform rOpenSci community manager so that an introductory blog post can be put together.

  • If they haven’t already done so as guest editors, request that the new editor turn on two-factor authentication (2FA) for GitHub.

  • Invite them to the rOpenSci GitHub organization as member, as a member of the editors team, and also stats-editors team for stats editors. This will give them appropriate permissions, and ensure that they appear in the editors dashboard.

  • Invite them to the AirTable database of software review (linked in the description of the editors-only channel on Slack). Ensure invitation is “Read only”.

  • Invite them to the private “editors-only” channel in rOpenSci’s Slack workspace (and to the Slack workspace in general if they’re not yet there).

  • Once they’re in the “editors-only” channel, post a welcome message pinging all editors.

9.4 Offboarding an editor

  • Thank them for their work!

  • Inform rOpenSci community manager or other staff members, to ensure our newsletter will announce their departure, and thank them.

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

  • Remove them from https://github.com/orgs/ropensci/teams/editors/members and sub-team.

  • Update “team.json” on website by replacing “roles” with “past_roles”, and adding new field, alumnus: "true".

  • Remove their access to the Airtable workspace.

    • From the “interface” view, pull down main menu at top-left and enter “View Data”
    • Click “Share” button on top right, and then “People with access”
    • Click checkbox on left on editor to be removed, and “Remove 1 collaborator”.

  • The (past-)editors lists in both the dev_guide chapter introducing software review and the software-review README are automatically populated from the AirTable data. Updates are run daily, so check a day after AirTable updates to ensure both have been updated.

9.5 Putting the system on pause

If you want to put the system on a break for instance over the holidays, before leaving:

  • Add a vacation message to the about field of issue templates. Example PR.
  • Add a vacation message to the bot’s standard welcome response. Example PR.

Upon resuming activities:

  • Remove the vacation message from issue templates. Example PR.
  • Remove the vacation message from the bot’s standard welcome response. Example commit.

9.6 Managing a dev guide release

If you are in charge of managing a release of the very book you are reading, use the book release guidance as an issue template to be posted in the dev guide issue tracker, and do not hesitate to ask questions to other editors.

9.6.1 Dev guide governance

For very small amendments to the dev guide, no PR review is needed. For larger amendments, request review from at least a few editors (if none participated in the discussion related to the amendment, request a review from all of them on GitHub, and in the absence of any reaction merge after a week).

Two weeks before a dev guide release, once the PR from dev to master and the release blog post are ready for review, all editors should be pinged by GitHub (“review request” on the PR from dev to master) and Slack, but the release doesn’t need all of them to explicitly approve the release.

9.6.2 Blog post about a release

The blog post about a release will be reviewed by editors, and one of @ropensci/blog-editors.

9.6.2.1 Content

Refer to the general rOpenSci blogging guidance, and the more specific guidance below.

First example of such a post; second example.

The blog post should mention all important items from the changelog organized in (sub)sections: e.g. a section about big change A, another one about big change B, and one about smaller changes lumped together. Mention the most important changes first.

For each change made by an external contributor, thank them explicitly using the information from the changelog. E.g. [Matt Fidler](https://github.com/mattfidler/) amended our section on Console messages [ropensci/dev_guide#178](https://github.com/ropensci/dev_guide/pull/178)..

At the end of the post, mention upcoming changes by linking to open issues in the issue tracker, and invite readers to contribute to the dev guide by opening issues and participating in open discussions. Conclusion template:

In this post we summarized the changes incorporated into our book ["rOpenSci Packages: Development, Maintenance, and Peer Review"](https://devguide.ropensci.org/) over the last X months.
We are grateful for all contributions that made this release possible.
We are already working on updates for our next version, such as ISSUE1, ISSUE2.
Check out the [the issue tracker](https://github.com/ropensci/dev_guide/issues/) if you'd like to contribute.

9.6.2.2 Authorship

The editor writing the post is the first author, other editors are listed in alphabetical order.