The Journal of Open Source Software (JOSS) conducts all peer review and editorial processes in the open, on the GitHub issue tracker.
JOSS editors manage the review workflow with the help of our bot,
@whedon. The bot is summoned with commands typed directly on the GitHub review issues. For a list of commands, type:
To learn more about
@whedon’s functionalities, take a look at our dedicated guide.
Once a submission comes in, it will be in the queue for a quick check by the Editor-in-chief (EiC). From there, it moves to a
PRE-REVIEW issue, where the EiC will assign a handling editor, and the author can suggest reviewers. Initial direction to the authors for improving the paper can already happen here, especially if the paper lacks some requested sections.
If the paper is out-of-scope for JOSS, editors assess this and notify the author in the
Editors can flag submissions of questionable scope using the command
@whedon query scope.
The EiC assigns an editor (or a volunteering editor self-assigns) with the command
@whedon assign @username as editor in a comment.
If a paper is submitted without a recommended editor, it will show up in the weekly digest email under the category ‘Papers currently without an editor.’ Please review this weekly email and volunteer to edit papers that look to be in your domain. If you choose to be an editor in the issue thread type the command
@whedon assign @yourhandle as editor or simply
@whedon assign me as editor
How papers are assigned to editors¶
By default, unless an editor volunteers, the Associated Editor-in-chief (AEiC) on duty will attempt to assign an incoming paper to the most suitable handling editor. While AEiCs will make every effort to match a submission with the most appropriate editor, there are a number of situations where an AEiC may assign a paper to an editor that doesn’t fit entirely within the editor’s research domains:
- If there’s no obvious fit to any of the JOSS editors
- If the most suitable editor is already handling a large number of papers
- If the chosen editor has a lighter editorial load than other editors
In most cases, an AEiC will ask one or more editors to edit a submission (e.g.
@editor1, @editor 2 - would one of you be willing to edit this submission for JOSS). If the editor doesn’t respond within ~3 working days, the AEiC may assign the paper to the editor regardless.
Editors may also be invited to edit over email when an AEiC runs the command
@whedon invite @editor1 as editor.
At this point, the handling editor’s job is to identify reviewers who have sufficient expertise in the field of software and in the field of the submission. JOSS papers have to have a minimum of two reviewers per submission, except for papers that have previously been peer-reviewed via rOpenSci. In some cases, the editor also might want to formally add themself as one of the reviewers. If the editor feels particularly unsure of the submission, a third (or fourth) reviewer can be recruited.
To recruit reviewers, the handling editor can mention them in the
PRE-REVIEW issue with their GitHub handle, ping them on Twitter, or email them. After expressing initial interest, candidate reviewers may need a longer explanation via email. See sample reviewer invitation email, below.
- It is rare that all reviewers have the expertise to cover all aspects of a submission (e.g., knows the language really well and knows the scientific discipline well). As such, a good practice is to try and make sure that between the two or three reviewers, all aspects of the submission are covered.
- Selection and assignment of reviewers should adhere to the JOSS COI policy.
Potential ways to find reviewers
Finding reviewers can be challenging, especially if a submission is outside of your immediate area of expertise. Some strategies you can use to identify potential candidates:
- Search the reviewer spreadsheet of volunteer reviewers.
- When using this spreadsheet, pay attention to the number of reviews this individual is already doing to avoid overloading them.
- It can be helpful to use the “Data > Filter Views” capability to temporarily filter the table view to include only people with language or domain expertise matching the paper.
- Ask the author(s): You are free to ask the submitting author to suggest possible reviewers by using the reviewer spreadsheet and also people from their professional network. In this situation, the editor still needs to verify that their suggestions are appropriate.
- Use your professional network: You’re welcome to invite people you know of who might be able to give a good review.
- Search Google and GitHub for related work, and write to the authors of that related work.
- You might like to try this tool from @dfm.
- Ask on social networks: Sometimes asking on Twitter for reviewers can identify good candidates.
- Check the work being referenced in the submission:
- Authors of software that is being built on might be interested in reviewing the submission.
- Users of the the software that is being submission be interested in reviewing the submission
- Avoid asking JOSS editors to review: If at all possible, avoid asking JOSS editors to review as they are generally very busy editing their own papers.
Once a reviewer accepts, the handling editor runs the command
@whedon assign @username as reviewer in the
PRE-REVIEW issue. Add more reviewers with the command
@whedon add @username as reviewer.
Under the uncommon circumstance that a review must be started before all reviewers have been identified (e.g., if finding a second reviewer is taking a long time and the first reviewer wants to get started), an editor may elect to start the review and add the remaining reviewers later. To accomplish this, the editor will need to hand-edit the review checklist to create space for the reviewers added after the review issues is created.
assign command clobbers all reviewer assignments. If you want to add an additional reviewer use the
Starting the review¶
Next, run the command
@whedon start review. If you haven’t assigned an editor and reviewer, this command will fail and
@whedon will tell you this. This will open the
REVIEW issue, with prepared review checklists for each reviewer, and instructions. The editor should close the
PRE-REVIEW issue, at this point, and move the conversation to the separate
REVIEW issue contains some instructions, and reviewer checklists. The reviewer(s) should check off items of the checklist one-by-one, until done. In the meantime, reviewers can engage the authors freely in a conversation aimed at improving the paper.
When a new review is started, Whedon invites the reviewers to the GitHub repository. The reviewers must accept the invitation to the GitHub repository in order for Whedon to be able to assign the review issue to them, and reviewers are unable to check off checklist items until they have accepted the repository invitation.
If a reviewer recants their commitment or is unresponsive, editors can remove them with the command
@whedon remove @username as reviewer. You can also add new reviewers in the
REVIEW issue, but in this case, you need to manually add a review checklist for them by editing the issue body.
Comments in the
REVIEW issue should be kept brief, as much as possible, with more lengthy suggestions or requests posted as separate issues, directly in the submission repository. A link-back to those issues in the
REVIEW is helpful.
When the reviewers are satisfied with the improvements, we ask that they confirm their recommendation to accept the submission.
Adding a new reviewer once the review has started¶
Sometimes you’ll need to add a new reviewer once the main review (i.e. post pre-review) is already underway. In this situation you should do the following:
- In the review thread, do
@whedon add @newreviewer as reviewer.
- Manually edit the first message in the thread to add a checklist for @newreviewer.
In the future, this will be more automated but for now, there’s some manual work required.
After reviewers recommend acceptance¶
When a submission is ready to be accepted, we ask that the authors issue a new tagged release of the software (if changed), and archive it (on Zenodo, figshare, or other). The authors then post the version number and archive DOI in the
REVIEW issue. The handling editor executes the pre-publication steps, and pings the EiCs for final processing.
- Get a new proof with the
@whedon generate pdfcommand.
- Download the proof, check all references have DOIs, follow the links and check the references.
- Whedon can help check references with the command
@whedon check references
- Whedon can help check references with the command
- Proof-read the paper and ask authors to fix any remaining typos, badly formed citations, awkward wording, etc..
- Ask the author to make a tagged release and archive, and report the version number and archive DOI in the review thread.
- Check the archive deposit has the correct metadata (title and author list), and request the author edit it if it doesn’t match the paper.
@whedon set <doi> as archive.
@whedon set <v1.x.x> as versionif the version was updated.
@whedon recommend-acceptto generate the final proofs, which has Whedon notify the
@openjournals/joss-eicsteam that the paper is ready for final processing.
At this point, the EiC/AEiC will take over to make final checks and publish the paper.
It’s also a good idea to ask the authors to check the proof. We’ve had a few papers request a post-publication change of author list, for example—this requires a manual download/compile/deposit cycle and should be a rare event.
Handling of papers published together with AAS publishing¶
JOSS is collaborating with AAS publishing to offer software review for some of the papers submitted to their journals. A detailed overview of the motivations/background is available in the announcement blog post, here we document the additional editorial steps that are necessary for JOSS to follow:
- If the paper is a joint publication, make sure you apply the
AASlabel to both the
- Before moving the JOSS paper from
review, ensure that you (the JOSS editor) make the reviewers aware that JOSS will be receiving a small financial donation from AAS publishing for this review (e.g. like this).
After the paper has been accepted by JOSS
- Once the JOSS review is complete, ask the author for the status of their AAS publication, specifically if they have the AAS paper DOI yet.
- Once this is available, ask the author to add this information to their
paper.mdYAML header as documented in the submission guidelines.
# Optional fields if submitting to a AAS journal too, see this blog post: # https://blog.joss.theoj.org/2018/12/a-new-collaboration-with-aas-publishing aas-doi: 10.3847/xxxxx <- update this with the DOI from AAS once you know it. aas-journal: Astrophysical Journal <- The name of the AAS journal.
- Pause the review (by applying the
pausedlabel) to await notification that the AAS paper is published.
Once the AAS paper is published
- Ask the EiC on rotation to publish the paper as normal (by tagging
Processing of rOpenSci-reviewed and accepted submissions¶
If a paper has already been reviewed and accepted by rOpenSci, the streamlined JOSS review process is:
- Assign yourself as editor and reviewer
- Add a comment in the pre-review issue pointing to the rOpenSci review
- Add the rOpenSci label to the pre-review issue
- Start the review issue
- Add a comment in the review issue pointing to the rOpenSci review
- Compile the paper and check it looks ok
- Tick off all the review checkboxes
- Go to to the source code repo and grab the Zenodo DOI
- Accept and publish the paper
Rejecting a paper¶
If you believe a submission should be rejected, for example, because it is out of scope for JOSS, then you should:
- Ask Whedon to flag the submission as potentially out of scope with the command
@whedon query scope. This command adds the
query-scopelabel to the issue.
- Mention to the author your reasons for flagging the submission as possibly out of scope, and give them an opportunity to defend their submission.
- The EiC on rotation will make a final determination of whether a submission is in scope, taking into account the feedback of other editors.
Voting on papers flagged as potentially out of scope¶
Once per week, an email is sent to all JOSS editors with a summary of the papers that are currently flagged as potentially out of scope. Editors are asked to review these submissions and vote on the JOSS website if they have an opinion about a submission.
Overview of editorial process¶
Step 1: An author submits a paper.
The author can choose to select an preferred editor based on the information available in our biographies. This can be changed later.
Step 2: If you are selected as an editor you get @-mentioned in the pre-review issue.
This doesn’t mean that you’re the editor, just that you’ve been suggested by the author.
Step 3: Once you are the editor, find the link to the code repository in the
Step 4: The editor looks at the software submitted and checks to see if:
- There’s a general description of the software
- The software is within scope as research software
- It has an OSI-approved license
Step 5: The editor responds to the author saying that things look in line (or not) and will search for reviewer
Step 6: The editor finds >= 2 reviewers
- Use the list of reviewers: type the command
@whedon list reviewersor look at list of reviewers in a Google spreadsheet
- If people are in the review list, the editor can @-mention them on the issue to see if they will review: e.g.
@person1 @person2 can you review this submission for JOSS?
- Or solicit reviewers outside the list. Send an email to people describing what JOSS is and asking if they would be interested in reviewing.
- If you ask the author to suggest potential reviewers, please be sure to tell the author not to @-tag their suggestions.
Step 7: Editor tells Whedon to assign the reviewer to the paper
@whedon assign @reviewer as reviewer
- To add a second reviewer use
@whedon add @reviwer2 as reviewer
assign command clobbers all reviewer assignments. If you want to add an additional reviewer use the
Step 8: Create the actual review issue
@whedon start review
- An issue is created with the review checklist, one per reviewer, e.g. https://github.com/openjournals/joss-reviews/issues/717
Step 9: Close the pre-review issue
Step 10: The actual JOSS review
- The reviewer reviews the paper and has a conversation with the author. The editor lurks on this conversation and comes in if needed for questions (or CoC issues).
- The reviewer potentially asks for changes and the author makes changes. Everyone agrees it’s ready.
Step 11: The editor pings the EiC team to get the paper published
- Make a final check of the paper with
@whedon generate pdfand that all references have DOIs (where appropriate) with
@whedon check references.
- If everything looks good, ask the author to make a new release (if possible) of the software being reviewed and deposit a new archive the software with Zenodo/figshare. Update the review thread with this archive DOI:
@whedon set 10.5281/zenodo.xxxxxxas archive.
- Finally, use
@whedon recommend-accepton the review thread to ping the
@openjournals/joss-eicsteam letting them know the paper is ready to be accepted.
Step 12: Celebrate publication! Tweet! Thank reviewers! Say thank you on issue.
Visualization of editorial flow¶
Expectations on JOSS editors¶
Responding to editorial assignments¶
As documented above, usually, papers will be assigned to you by one of the AEiCs. We ask that editors do their best to respond in a timely fashion (~ 3 working days) to invites to edit a new submission.
Continued attention to assigned submissions¶
As an editor, part of your role is to ensure that submissions you’re responsible for are progressing smoothly through the editorial process. This means that once or twice per week we ask that you check your GitHub notifications and/or your editorial dashboard (e.g.
http://joss.theoj.org/dashboard/youreditorname) for updates to the papers you are handling.
If reviews go stale
Sometimes reviews go quiet, either because a reviewer has failed to complete their review or an author has been slow to respond to a reviewer’s feedback. As the editor, we need you to prompt the author/or reviewer(s) to revisit the submission if there has been no response within 7-10 days unless there’s a clear statement in the review thread that says an action is coming at a slightly later time, perhaps because a reviewer committed to a review by a certain date, or an author is making changes and says they will be done by a certain date.
Whedon has functionality to remind an author or review to return to a review at a certain point in the future. For example:
@whedon remind @reviewer in five days
Out of office¶
Sometimes we need time away from our editing duties at JOSS. The joss-reviews repository has the OoO bot installed which means you can mark yourself as out of the office (and unable to respond to reviews) for a period of time e.g.:
Mark yourself as OoO in one of the reviews you’re editing in the joss-reviews repository like this:
/ooo January 18 until February 2
Ooo bot will then respond to any mentions in the joss-reviews repository to let people know you’re away.
Note, if you’re planning on being out of the office for more than two weeks, please let the JOSS editorial team know.
New editors are assigned an editorial ‘buddy’ from the existing editorial team. The buddy is there to help the new editor onboard successfully and to provide a dedicated resource for any questions they might have but don’t feel comfortable posting to the editor mailing list.
Buddy assignments don’t have a fixed term but generally require a committment for 1-2 months.
Some things you might need to do as a buddy for a new editor:
- Respond to questions via email or on GitHub review issues.
- Check in with the new editor every couple of weeks if there hasn’t been any other communication.
- (Optionally) keep an eye on the new editor’s submissions.
Being on the JOSS editorial team means that there can be a lot of notifications from GitHub if you don’t take some proactive steps to minimize noise from the reviews repository.
Things you should do when joining the editorial team¶
Unsubscribe from the reviews repository on GitHub
When you’re added to the editorial team on GitHub, you will almost certainly find yourself subscribed (watching) to the
joss-reviews repository. The first thing you should do is set yourself to ‘not watching’:
Repository notifications settings
Please note, that by not watching the reviews repository, you will still receive notifications for issues (reviews) where you are
Sometimes another editor might mention you in a review issue (for example to ask you a question). If you’ve responded and no-longer want to receive messages for that review, you can manually unsubscribe by clicking the button in the right-hand column on the review issue page.
Curate your GitHub notifications experience
GitHub has extensive documentation on managing notifications which explains when and why different notifications are sent from a repository.
Set up email filters
Email filters can be very useful for managing incoming email notifications, here are some recommended resources:
- A GitHub blog post describing how to set up email filters.
If you use Gmail:
Use a dedicated tool
For papers that you are already assigned to edit, the dedicated JOSS dashboard aggregates notifications associated with each paper. The dashboard is available at:
Another tool you might want to try out is Octobox.