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

  • Inform rOpenSci community manager so that

    • The new editor is added to the rOpenSci website.
    • 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 the data-pkg-editors or stats-board sub-team, as appropriate. This will give them appropriate permissions and allow them to get team-specific notifications.

  • Editors need access to the AirTable database of software review (linked in the description of the editors-only channel on Slack).

  • Editors need access to the private editors channel in rOpenSci Slack workspace (and to the Slack workspace in general if they didn’t previously, in that case ask rOpenSci community manager).

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

  • In the Slack workspace they need to be added to the editors team so that @editors will ping them too.

  • We add editors’ names to

  • Add editors to https://github.com/orgs/ropensci/teams/editors/members

9.4 Offboarding an editor

Both the dev_guide and software-review README are automatically knit via continuous integration.

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.