From b6cbdbc614e560c84a599edc9e0d00716deb9a38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Mon, 24 Aug 2026 11:04:12 +0200 Subject: [PATCH 1/3] Enforce the prefixing of comments more #1024 --- booknews.Rmd | 1 + softwarereview_author.Rmd | 3 ++- softwarereview_editor.Rmd | 1 + templates/editor.md | 2 ++ templates/review.md | 2 ++ 5 files changed, 8 insertions(+), 1 deletion(-) diff --git a/booknews.Rmd b/booknews.Rmd index 5592b062f..5dfa32a8b 100644 --- a/booknews.Rmd +++ b/booknews.Rmd @@ -2,6 +2,7 @@ ## Dev version +- 2026-08-24, enforce the prefixing of comments more (#1024). - 2026-06-26, explicitely state that authors should not change their package while it is under review (#1022). - 2026-06-25, add note for editors that authors should record their responses (#1021, `@robitalec`) - 2026-06-12, clarify expections for volunteer form for eds and revs (#1015; thanks to `@joelnitta`) diff --git a/softwarereview_author.Rmd b/softwarereview_author.Rmd index 5b071cc08..1b80f0df7 100644 --- a/softwarereview_author.Rmd +++ b/softwarereview_author.Rmd @@ -83,7 +83,8 @@ If you intend to submit an accompanying manuscript for your package, rOpenSci ha - An [editor](#editors) will review your submission within 5 business days and respond with next steps. The editor may assign the package to reviewers, request that the package be updated to meet minimal criteria before review, or reject the package due to lack of fit or overlap. - If your package meets minimal criteria, the editor will assign 1-3 reviewers. They will be asked to provide reviews as comments on your issue within 3 weeks. - While your package is under review, please refrain from making any change, apart from hot fixes. Indeed, reviewers should be able to review the latest (best until now) version of your software, and that version should not be changing. -- We ask that you respond to reviewers' comments within 2 weeks of the last-submitted review, but you may make updates to your package or respond at any time. Your response should include a link to the updated [NEWS.md](#news) of your package. Here is [an author response example](https://github.com/ropensci/software-review/issues/160#issuecomment-355043656). Once the response is commited, [submit it using the bot](#submit-response-to-reviewers). We encourage ongoing conversations between authors and reviewers. See the [reviewing guide](#reviewerguide) for more details. +- We ask that you respond to reviewers' comments within 2 weeks of the last-submitted review, but you may make updates to your package or respond at any time. Your response should include a link to the updated [NEWS.md](#news) of your package. Here is [an author response example](https://github.com/ropensci/software-review/issues/160#issuecomment-355043656). Once the response is commited, [submit it using the bot](#submit-response-to-reviewers). If reviewers used prefixes before their comments e.g. ml01, ml02, use them in your response as well. +- We encourage ongoing conversations between authors and reviewers. See the [reviewing guide](#reviewerguide) for more details. - Any time package changes are likely to alter the results of [the automated `pkgcheck` checks](https://docs.ropensci.org/pkgcheck), authors can request a re-check with the command, `@ropensci-review-bot check package`. - Please notify us immediately if you are no longer able to maintain your package or to respond to reviews. You will then be expected to either retract a submission, or to find alternative package maintainers. You can also discuss maintenance issues in the rOpenSci slack workspace. - Once your package is approved, we will provide further instructions about the transfer of your repository to the rOpenSci repository. diff --git a/softwarereview_editor.Rmd b/softwarereview_editor.Rmd index 6580c94f4..da95d22e9 100644 --- a/softwarereview_editor.Rmd +++ b/softwarereview_editor.Rmd @@ -231,6 +231,7 @@ Please use all of this information to judge whether: #### Initial editorial comments - After automatic checks are posted, use the [editor template](#editortemplate) to guide initial checks (if not already covered by the EiC) and record your response to the submission. + Prefix all your comments with numbered codes e.g. ml01, ml02, etc. You can also streamline your editor checks by using the [`pkgreviewr` package created by former editor Anna Krystalli](https://docs.ropensci.org/pkgreviewr/articles/editors.html). Please strive to finish the checks and start looking for reviewers within 5 working days. - Check against policies for [fit](#aims-and-scope) and [overlap](#overlap). diff --git a/templates/editor.md b/templates/editor.md index 9dde3e8e7..46926ca73 100644 --- a/templates/editor.md +++ b/templates/editor.md @@ -14,5 +14,7 @@ #### Editor comments +_Prefix all your comments with numbered codes e.g. ml01, ml02, etc._ + --- diff --git a/templates/review.md b/templates/review.md index 732b40c24..b781afeca 100644 --- a/templates/review.md +++ b/templates/review.md @@ -40,3 +40,5 @@ Estimated hours spent reviewing: --- ### Review Comments + +_Prefix all your comments with numbered codes e.g. ml01, ml02, etc._ From c44bbde642ae8599db0fb92434112aacb29b2602 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Tue, 25 Aug 2026 10:11:19 +0200 Subject: [PATCH 2/3] add more docs --- softwarereview_author.Rmd | 2 +- softwarereview_editor.Rmd | 2 +- softwarereview_reviewer.Rmd | 37 +++++++++++++++++++++++++++++++++++-- 3 files changed, 37 insertions(+), 4 deletions(-) diff --git a/softwarereview_author.Rmd b/softwarereview_author.Rmd index 98a783fd3..6ce7b3085 100644 --- a/softwarereview_author.Rmd +++ b/softwarereview_author.Rmd @@ -83,7 +83,7 @@ If you intend to submit an accompanying manuscript for your package, rOpenSci ha - An [editor](#editors) will review your submission within 5 business days and respond with next steps. The editor may assign the package to reviewers, request that the package be updated to meet minimal criteria before review, or reject the package due to lack of fit or overlap. - If your package meets minimal criteria, the editor will assign 1-3 reviewers. They will be asked to provide reviews as comments on your issue within 3 weeks. - While your package is under review, please refrain from making any change, apart from hot fixes. Indeed, reviewers should be able to review the latest (best until now) version of your software, and that version should not be changing. -- We ask that you respond to reviewers' comments within 2 weeks of the last-submitted review, but you may make updates to your package or respond at any time. Your response should include a link to the updated [NEWS.md](#news) of your package. Here is [an author response example](https://github.com/ropensci/software-review/issues/160#issuecomment-355043656). Once the response is commited, [submit it using the bot](#submit-response-to-reviewers). If reviewers used prefixes before their comments e.g. ml01, ml02, use them in your response as well. +- We ask that you respond to reviewers' comments within 2 weeks of the last-submitted review, but you may make updates to your package or respond at any time. Your response should include a link to the updated [NEWS.md](#news) of your package. Here is [an author response example](https://github.com/ropensci/software-review/issues/160#issuecomment-355043656). Once the response is commited, [submit it using the bot](#submit-response-to-reviewers). If reviewers [used prefixes](#prefixing) before their comments e.g. ml01, ml02, use them in your response as well. - We encourage ongoing conversations between authors and reviewers. See the [reviewing guide](#reviewerguide) for more details. - Any time package changes are likely to alter the results of [the automated `pkgcheck` checks](https://docs.ropensci.org/pkgcheck), authors can request a re-check with the command, `@ropensci-review-bot check package`. - Please notify us immediately if you are no longer able to maintain your package or to respond to reviews. You will then be expected to either retract a submission, or to find alternative package maintainers. You can also discuss maintenance issues in the rOpenSci slack workspace. diff --git a/softwarereview_editor.Rmd b/softwarereview_editor.Rmd index da95d22e9..321f0a6f0 100644 --- a/softwarereview_editor.Rmd +++ b/softwarereview_editor.Rmd @@ -231,7 +231,7 @@ Please use all of this information to judge whether: #### Initial editorial comments - After automatic checks are posted, use the [editor template](#editortemplate) to guide initial checks (if not already covered by the EiC) and record your response to the submission. - Prefix all your comments with numbered codes e.g. ml01, ml02, etc. + Prefix all your comments with [numbered codes](#prefixing) e.g. ml01, ml02, etc. You can also streamline your editor checks by using the [`pkgreviewr` package created by former editor Anna Krystalli](https://docs.ropensci.org/pkgreviewr/articles/editors.html). Please strive to finish the checks and start looking for reviewers within 5 working days. - Check against policies for [fit](#aims-and-scope) and [overlap](#overlap). diff --git a/softwarereview_reviewer.Rmd b/softwarereview_reviewer.Rmd index 580e1e98d..026874475 100644 --- a/softwarereview_reviewer.Rmd +++ b/softwarereview_reviewer.Rmd @@ -43,6 +43,9 @@ All submissions trigger a detailed report on package structure and functionality To review a package, please begin by copying our [review template](#reviewtemplate), or the the [statistics review template](https://stats-devguide.ropensci.org/pkgreview.html#pkgrev-template) for statistical software. These templates should be used as high-level checklists to guide initial review structure. + +#### Checklist + In addition to checking off the minimum criteria, we ask that you provide general comments addressing the following: - Does the package comply with the [rOpenSci packaging guide](#building)? @@ -55,8 +58,9 @@ In addition to checking off the minimum criteria, we ask that you provide genera - Were functions and arguments named to work together to form a common, logical programming API that is easy to read, and autocomplete? - If you have your own relevant data/problem, work through it with the package. You may find rough edges and use-cases the author didn't think about. +Some items in our checklist were inspired by the [Mozilla code review guide](https://mozillascience.github.io/codeReview/review.html). -Please be respectful and kind to the authors in your reviews. Our [code of conduct](#code-of-conduct) is mandatory for everyone involved in our review process. We expect you to submit your review within 3 weeks, depending on the deadline set by the editor. Please contact the editor directly or in the submission thread to inform them about possible delays. +#### Automatic tools We encourage you to use automated tools to facilitate your review. These include: @@ -68,7 +72,36 @@ We encourage you to use automated tools to facilitate your review. These includ Reviewers may also re-generate package check results from `@ropensci-review-bot` at any time by issuing the single comment in a review issue: `@ropensci-review-bot check package`. -Some items in our checklist were inspired by the [Mozilla code review guide](https://mozillascience.github.io/codeReview/review.html). +#### Tone + +Please be respectful and kind to the authors in your reviews. Our [code of conduct](#code-of-conduct) is mandatory for everyone involved in our review process. We expect you to submit your review within 3 weeks, depending on the deadline set by the editor. Please contact the editor directly or in the submission thread to inform them about possible delays. + + +#### Formatting {#prefixing} + +You might be writing many individual comments as part of your review. +To facilitate communication around them, please prefix your answers like so, with your initials unless you share them with anyone else in the thread, and a number: + +``` +- ml01: your package lacks a test for bla. +- ml02: the reference index's grouping is unclear. +.... +``` + +This way the author can respond like so: + +``` +> - ml01: your package lacks a test for bla. + +Good catch, I added two tests, see [commit](link-to-commit). + +> - ml02: the reference index's grouping is unclear. + +Thank you, the functions are now grouped into data ingestion, data checking and data analysis. See [new reference index](pkgdown-link). + +.... +``` + ### Off-thread interactions {#off-thread-interactions} From 2d5f9581a9afae2cb380b40b7c2ac20923243c15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Wed, 26 Aug 2026 08:40:33 +0200 Subject: [PATCH 3/3] Apply suggestion from @joelnitta Co-authored-by: Joel Nitta --- softwarereview_editor.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/softwarereview_editor.Rmd b/softwarereview_editor.Rmd index bc227b493..ed1e3074f 100644 --- a/softwarereview_editor.Rmd +++ b/softwarereview_editor.Rmd @@ -231,7 +231,7 @@ Please use all of this information to judge whether: #### Initial editorial comments - After automatic checks are posted, use the [editor template](#editortemplate) to guide initial checks (if not already covered by the EiC) and record your response to the submission. - Prefix all your comments with [numbered codes](#prefixing) e.g. ml01, ml02, etc. + Prefix each of your comments with an [identifier consisting of your initials and a number](#prefixing) e.g. `ml01`, `ml02`, etc. You can also streamline your editor checks by using the [`pkgreviewr` package created by former editor Anna Krystalli](https://docs.ropensci.org/pkgreviewr/articles/editors.html). Please strive to finish the checks and start looking for reviewers within 5 working days. - Check against policies for [fit](#aims-and-scope) and [overlap](#overlap).