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/7] 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/7] 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/7] 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). From 2949293ed9c253b43436032444d508339bfaaaa7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Mon, 31 Aug 2026 14:46:44 +0200 Subject: [PATCH 4/7] rephrase --- templates/editor.md | 2 +- templates/review.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/editor.md b/templates/editor.md index 46926ca73..f10c509fa 100644 --- a/templates/editor.md +++ b/templates/editor.md @@ -14,7 +14,7 @@ #### Editor comments -_Prefix all your comments with numbered codes e.g. ml01, ml02, etc._ +_Prefix all your comments with an identifier consisting of your initials and a number e.g. ml01, ml02, etc._ --- diff --git a/templates/review.md b/templates/review.md index 1f356a6e9..62a4e74a6 100644 --- a/templates/review.md +++ b/templates/review.md @@ -41,4 +41,4 @@ Estimated hours spent reviewing: ### Review Comments -_Prefix all your comments with numbered codes e.g. ml01, ml02, etc._ +_Prefix all your comments with an identifier consisting of your initials and a number e.g. ml01, ml02, etc._ From 51b0aff1c0677f70f942f06bc879822625420cd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Mon, 31 Aug 2026 15:08:23 +0200 Subject: [PATCH 5/7] add translations :tada: --- softwarereview_author.es.Rmd | 3 ++- softwarereview_author.pt.Rmd | 3 ++- softwarereview_editor.es.Rmd | 1 + softwarereview_editor.pt.Rmd | 1 + softwarereview_reviewer.es.Rmd | 38 ++++++++++++++++++++++++++++++++-- softwarereview_reviewer.pt.Rmd | 37 +++++++++++++++++++++++++++++++-- templates/editor.es.md | 2 ++ templates/editor.pt.md | 2 ++ templates/review.es.md | 2 +- templates/review.pt.md | 2 ++ 10 files changed, 84 insertions(+), 7 deletions(-) diff --git a/softwarereview_author.es.Rmd b/softwarereview_author.es.Rmd index 7c185f566..a9de10c25 100644 --- a/softwarereview_author.es.Rmd +++ b/softwarereview_author.es.Rmd @@ -83,7 +83,8 @@ Si tiene intención de enviar un artículo científico sobre tu paquete, rOpenSc - Una persona realizará la [edición](#editors) y revisará tu envío en un plazo de 5 días laborables y te responderá con los siguientes pasos a seguir. Puede asignar el paquete a personas para que lo revisen, solicitar que el paquete se actualice para cumplir los criterios mínimos antes de la revisión, o rechazar el paquete porque el mismo no encaja en rOpenSci o porque se solapa con uno ya existente. - Si tu paquete cumple con los criterios mínimos, se le asignará de 1 a 3 personas para hacer la revisión, a quienes se les pedirá proporcionar revisiones en forma de comentarios sobre tu *issue* en un plazo máximo de 3 semanas. - Mientras se revisa tu paquete, por favor, no hagas ningún cambio, salvo las correcciones urgentes. De hecho, los revisores deben poder revisar la última versión (la mejor hasta ahora) de tu software, y esa versión no debería cambiar. -- Te pedimos que respondas a estos comentarios en un plazo máximo de 2 semanas desde la última revisión presentada, pero puedes actualizar tu paquete o responder en cualquier momento. Tu respuesta debe incluir un enlace a la actualización del archivo [*NEWS.md*](#news) de tu paquete. Aquí tienes [un ejemplo de respuesta](https://github.com/ropensci/software-review/issues/593#issuecomment-1714421144). Una vez hayas respondido, [enviala a nuestra base de datos usando nuestro bot](#submit-response-to-reviewers). Animamos a la continuación de conversaciones entre autores y revisores. Consulta la [guía de revisión](#reviewerguide) para más detalles. +- Te pedimos que respondas a estos comentarios en un plazo máximo de 2 semanas desde la última revisión presentada, pero puedes actualizar tu paquete o responder en cualquier momento. Tu respuesta debe incluir un enlace a la actualización del archivo [*NEWS.md*](#news) de tu paquete. Aquí tienes [un ejemplo de respuesta](https://github.com/ropensci/software-review/issues/593#issuecomment-1714421144). Una vez hayas respondido, [enviala a nuestra base de datos usando nuestro bot](#submit-response-to-reviewers). Si las personas que revisaron tu paquete [usaron prefijos](#prefixing) antes de sus comentarios, por ejemplo, ml01, ml02, úsalos también en tu respuesta. +- Animamos a la continuación de conversaciones entre autores y revisores. Consulta la [guía de revisión](#reviewerguide) para más detalles. - Si algún cambio en el paquete puede modificar los resultados de [`pkgcheck`](https://docs.ropensci.org/pkgcheck), se puede solicitar un nuevo chequeo con el comando `@ropensci-review-bot check package`. - Por favor, notifícanos inmediatamente si ya no puedes mantener tu paquete o responder a las revisiones. En ese caso, se espera que retractes el envío o que encuentres responsables alternativos para mantener del paquete. También puedes discutir los problemas de mantenimiento en el Slack de rOpenSci. - Una vez que tu paquete sea aceptado, te proporcionaremos más instrucciones sobre la transferencia de tu repositorio al repositorio de rOpenSci. diff --git a/softwarereview_author.pt.Rmd b/softwarereview_author.pt.Rmd index 49e3c9a52..162539909 100644 --- a/softwarereview_author.pt.Rmd +++ b/softwarereview_author.pt.Rmd @@ -83,7 +83,8 @@ Se você pretende enviar um manuscrito de acompanhamento para seu o pacote, a rO - Um [editor](#editors) analisará sua submissão em até 5 dias úteis e responderá com as próximas etapas. O editor poderá atribuir o pacote a revisores, solicitar que o pacote seja atualizado para atender aos critérios mínimos antes da revisão ou rejeitar o pacote devido à falta de adequação ou sobreposição. - Se o seu pacote atender aos critérios mínimos, o editor designará de 1 a 3 revisores. Eles serão solicitados a fornecer revisões como comentários sobre a sua _issue_ (submissão) dentro de 3 semanas. - Enquanto seu pacote estiver em análise, por favor, não faça nenhuma alteração, exceto correções de emergência. Afinal, os(as) revisores(as) precisam poder analisar a versão mais recente (a melhor até o momento) do seu software, e essa versão não deve sofrer alterações. -- Pedimos que você responda aos comentários dos revisores em até 2 semanas após a última revisão enviada, mas você pode fazer atualizações no seu pacote ou responder a qualquer momento. Sua resposta deve incluir um link para a versão atualizada da sua [NEWS.md](#news) do seu pacote. Aqui está um [exemplo de resposta de autor](https://github.com/ropensci/software-review/issues/160#issuecomment-355043656). Quando sua resposta for enviada, [submeta-a utilizando o bot](#submit-response-to-reviewers). Incentivamos conversas contínuas entre autores e revisores. Consulte a seção [guia de revisão](#reviewerguide) para obter mais detalhes. +- Pedimos que você responda aos comentários dos revisores em até 2 semanas após a última revisão enviada, mas você pode fazer atualizações no seu pacote ou responder a qualquer momento. Sua resposta deve incluir um link para a versão atualizada da sua [NEWS.md](#news) do seu pacote. Aqui está um [exemplo de resposta de autor](https://github.com/ropensci/software-review/issues/160#issuecomment-355043656). Quando sua resposta for enviada, [submeta-a utilizando o bot](#submit-response-to-reviewers). Se os revisores [usarem prefixos](#prefixing) antes de seus comentários, por exemplo, ml01, ml02, use-os também em sua resposta. +- Incentivamos conversas contínuas entre autores e revisores. Consulte a seção [guia de revisão](#reviewerguide) para obter mais detalhes. - Frequentemente, mudanças no pacote podem alterar os resultados automatizados [das verificações `pkgcheck`](https://docs.ropensci.org/pkgcheck). Para avaliar isso, autores podem solicitar uma nova verificação do pacote com o comando `@ropensci-review-bot check package`. - Notifique-nos imediatamente se você não puder mais manter o seu pacote ou responder às revisões. Nestes casos, se espera que você retire a submissão ou que encontre mantenedores alternativos para o pacote. Você também pode discutir questões de manutenção na área de trabalho da rOpenSci no Slack. - Assim que seu pacote for aprovado, forneceremos mais instruções sobre a transferência do seu repositório para o repositório da rOpenSci. diff --git a/softwarereview_editor.es.Rmd b/softwarereview_editor.es.Rmd index ef9abe253..99036d8d2 100644 --- a/softwarereview_editor.es.Rmd +++ b/softwarereview_editor.es.Rmd @@ -231,6 +231,7 @@ Utiliza toda esta información para juzgar si: #### Comentarios editoriales iniciales - Después de contabilizar las comprobaciones automáticas, utiliza la [plantilla editorial](#editortemplate) para guiar las comprobaciones iniciales (si no están ya cubiertas por quien ocupa el rol de LE) y registrar tu respuesta al envío. + Empieza todos tus comentarios con un identificador formado por tus iniciales y un número, por ejemplo: ml01, ml02, etc. También puedes agilizar las comprobaciones editoriales utilizando la plantilla del paquete [`pkgreviewr`, creado por Anna Krystalli cuando formaba parte del equipo editorial](https://docs.ropensci.org/pkgreviewr/articles/editors.html). Procura terminar las comprobaciones y empezar a buscar las personas para revisar en un plazo de 5 días laborables. - Comprueba las políticas [de alcance](#aims-and-scope) y [solapamiento](#overlap). Inicia un debate en el canal de Slack #software-review sobre si es necesario, en casos especiales no detectados por comprobaciones previas, que se realice una revisión. Si se rechaza el paquete, consulta [esta sección](#outofscoperesponse) para conocer cómo responder. diff --git a/softwarereview_editor.pt.Rmd b/softwarereview_editor.pt.Rmd index 5567f9da0..fdb82f369 100644 --- a/softwarereview_editor.pt.Rmd +++ b/softwarereview_editor.pt.Rmd @@ -231,6 +231,7 @@ Use todas essas informações para avaliar se: #### Comentários editoriais iniciais - Depois que as checagens automáticas forem postadas, use o [modelo de edição](#editortemplate) para orientar as verificações iniciais (se ainda não estiverem cobertas pelo(a) EiC) e registre sua resposta na *issue* de submissão. + Inicie todos os seus comentários com um identificador composto por suas iniciais e um número, por exemplo, ml01, ml02, etc. Você também pode simplificar as verificações de editor(a) usando o [pacote `pkgreviewr`, criado pela ex-editora Anna Krystalli](https://docs.ropensci.org/pkgreviewr/articles/editors.html). Por favor, tente concluir as verificações e começar a buscar revisores(as) dentro de 5 dias úteis. - Verifique as políticas em busca de possíveis [ajustes](#aims-and-scope) e [sobreposições](#overlap). diff --git a/softwarereview_reviewer.es.Rmd b/softwarereview_reviewer.es.Rmd index 38dcfc027..7790fdea3 100644 --- a/softwarereview_reviewer.es.Rmd +++ b/softwarereview_reviewer.es.Rmd @@ -37,6 +37,9 @@ Todos los envíos generan un informe detallado sobre la estructura y funcionalid Para revisar un paquete, empieza por copiar nuestro [plantilla de revisión](#reviewtemplate) o la plantilla [plantilla de examen estadístico](https://stats-devguide.ropensci.org/pkgreview.html#pkgrev-template) para software estadístico. Estas plantillas deben utilizarse como listas de comprobación de alto nivel para orientar la estructura de la revisión inicial. + +#### Lista de verificación + Además de marcar los criterios mínimos, te pedimos que aportes comentarios generales sobre lo siguiente: - ¿Cumple el paquete con la [guía de desarrollo de paquetes de rOpenSci](#building)? @@ -49,7 +52,9 @@ Además de marcar los criterios mínimos, te pedimos que aportes comentarios gen - ¿Los nombres de funciones y argumentos forman una API de programación común y lógica que sea fácil de leer y que se beneficie de herramientas de automcompletado? - Si tienes datos propios relevantes o un problema relacionado, trabaja con el paquete. Puede que encuentres asperezas y/o casos de uso no contemplados. -Por favor, en tus revisiones dirígete con respeto y amabilidad hacia las personas que presentaron el paquete. Nuestro [código de conducta](#code-of-conduct) es obligatorio para quienes participan en nuestro proceso de revisión. Esperamos que envíes tu revisión en un plazo de 3 semanas, según el plazo establecido por la persona a cargo de la edición. Por favor, ponte en contacto con esta persona directamente o mediante el *issue* de envío para informarle de posibles retrasos. +Algunos elementos de nuestra lista de verificación se inspiran en la [guía de revisión de código de Mozilla](https://mozillascience.github.io/codeReview/review.html). + +#### Herramientas automáticas Te recomendamos usar herramientas automatizadas para facilitar tu revisión. Éstas incluyen @@ -62,7 +67,36 @@ Te recomendamos usar herramientas automatizadas para facilitar tu revisión. És Puedes volver a correr la comprobación del paquete de `@ropensci-review-bot` en cualquier momento enviando un comentario en el *issue* de revisión con el contenido "`@ropensci-review-bot check package`". -Algunos elementos de nuestra lista de verificación se inspiran en la [guía de revisión de código de Mozilla](https://mozillascience.github.io/codeReview/review.html). +#### Tono + +Por favor, en tus revisiones dirígete con respeto y amabilidad hacia las personas que presentaron el paquete. Nuestro [código de conducta](#code-of-conduct) es obligatorio para quienes participan en nuestro proceso de revisión. Esperamos que envíes tu revisión en un plazo de 3 semanas, según el plazo establecido por la persona a cargo de la edición. Por favor, ponte en contacto con esta persona directamente o mediante el *issue* de envío para informarle de posibles retrasos. + + +#### Formato {#prefijo} + +Es posible que escribas muchos comentarios individuales como parte de tu revisión. +Para facilitar la comunicación en torno a ellos, por favor, antepone a tus respuestas un prefijo como el siguiente, con tus iniciales —a menos que las compartas con alguien más en el hilo— y un número: + + +``` +- ml01: a tu paquete le falta una prueba para bla. +- ml02: la agrupación del índice de referencia no está clara. +.... +``` + +De esta manera, se puede responder así: + +``` +> - ml01: a tu paquete le falta una prueba para bla. + +Buena observación, agregué dos pruebas, ver [commit](enlace-al-commit). + +> - ml02: la agrupación del índice de referencia no está clara. + +Gracias, ahora las funciones están agrupadas en ingestión de datos, verificación de datos y análisis de datos. Véase [el nuevo índice de referencia](enlace-pkgdown). + +.... +``` ### Interacciones fuera del hilo en el _issue_ {#off-thread-interactions} diff --git a/softwarereview_reviewer.pt.Rmd b/softwarereview_reviewer.pt.Rmd index 658870eb4..20b4bd37f 100644 --- a/softwarereview_reviewer.pt.Rmd +++ b/softwarereview_reviewer.pt.Rmd @@ -37,6 +37,9 @@ Todos os envios criam um relatório detalhado, gerado pelo nosso pacote [`pkgche Para revisar um pacote, comece copiando nosso [modelo de revisão](#reviewtemplate) ou o [modelo de revisão para software estatístico](https://stats-devguide.ropensci.org/pkgreview.html#pkgrev-template). Esses modelos devem ser usados como listas de verificação de alto nível para guiar a estrutura da revisão inicial. + +#### Lista de verificação + Além de marcar os critérios mínimos na checklist, pedimos que você forneça comentários gerais abordando os seguintes pontos: - O pacote está de acordo com os requisitos do [Guia de pacotes da rOpenSci](#building)? @@ -49,7 +52,9 @@ Além de marcar os critérios mínimos na checklist, pedimos que você forneça - As funções e os argumentos foram nomeados para trabalharem juntos e formarem uma API de programação comum e lógica que seja fácil de ler e de autocompletar? - Se você tiver seus próprios dados/problemas relevantes, analise-os com o pacote. Você pode acabar encontrando casos de uso extremos nos quais o autor não pensou. -Seja respeitoso e gentil com os(as) autores(as) em suas avaliações. Nosso [código de conduta](#code-of-conduct) é obrigatório para todos os envolvidos em nosso processo de avaliação. Esperamos que você envie sua avaliação em até 3 (três) semanas, de acordo com o prazo estabelecido pelo(a) editor(a). Entre em contato com o(a) editor(a) diretamente ou no tópico de envio para informá-lo sobre possíveis atrasos. +Alguns elementos de nossa lista de verificação são inspirados no [guia de revisão de código da Mozilla] (https://mozillascience.github.io/codeReview/review.html). + +#### Ferramentas automáticas Incentivamos você a usar ferramentas automatizadas para facilitar a revisão. Isso inclui: @@ -61,7 +66,35 @@ Incentivamos você a usar ferramentas automatizadas para facilitar a revisão. I Os(as) revisores(as) também podem gerar novamente os resultados da verificação de pacotes a partir de `@ropensci-review-bot` a qualquer momento, emitindo um único comentário em um *issue* de revisão: `@ropensci-review-bot check package`. -Alguns elementos de nossa lista de verificação são inspirados no [guia de revisão de código da Mozilla] (https://mozillascience.github.io/codeReview/review.html). +#### Tom + +Seja respeitoso e gentil com os(as) autores(as) em suas avaliações. Nosso [código de conduta](#code-of-conduct) é obrigatório para todos os envolvidos em nosso processo de avaliação. Esperamos que você envie sua avaliação em até 3 (três) semanas, de acordo com o prazo estabelecido pelo(a) editor(a). Entre em contato com o(a) editor(a) diretamente ou no tópico de envio para informá-lo sobre possíveis atrasos. + +#### Formatação {#prefixo} + +Você pode estar escrevendo muitos comentários individuais como parte da sua revisão. +Para facilitar a comunicação em torno deles, por favor, coloque um prefixo nas suas respostas da seguinte forma: suas iniciais — a menos que você as compartilhe com outra pessoa no tópico — e um número: + + +``` +- ml01: seu pacote não possui um teste para bla. +- ml02: o agrupamento do índice de referência não está claro. +.... +``` + +Dessa forma, o autor pode responder assim: + +``` +> - ml01: seu pacote não possui um teste para bla. + +Boa observação, adicionei dois testes, veja [commit](link-para-commit). + +> - ml02: o agrupamento do índice de referência não está claro. + +Obrigado, as funções agora estão agrupadas em ingestão de dados, verificação de dados e análise de dados. Veja o [novo índice de referência](pkgdown-link). + +.... +``` ### Interações feitas fora dos canais oficiais {#off-thread-interactions} diff --git a/templates/editor.es.md b/templates/editor.es.md index cd7cf1c63..6abf37abd 100644 --- a/templates/editor.es.md +++ b/templates/editor.es.md @@ -16,4 +16,6 @@ #### Comentarios de edición +_Empieza todos tus comentarios con un identificador formado por tus iniciales y un número, por ejemplo: ml01, ml02, etc._ + --- diff --git a/templates/editor.pt.md b/templates/editor.pt.md index 10cc26abd..3f566d313 100644 --- a/templates/editor.pt.md +++ b/templates/editor.pt.md @@ -15,5 +15,7 @@ #### Comentários do(a) editor(a) +_Inicie todos os seus comentários com um identificador composto por suas iniciais e um número, por exemplo, ml01, ml02, etc._ + --- diff --git a/templates/review.es.md b/templates/review.es.md index 416cea935..ac866762b 100644 --- a/templates/review.es.md +++ b/templates/review.es.md @@ -42,4 +42,4 @@ Estimación de horas dedicadas a la revisión: ### Comentarios de la revisión - +_Empieza todos tus comentarios con un identificador formado por tus iniciales y un número, por ejemplo: ml01, ml02, etc._ diff --git a/templates/review.pt.md b/templates/review.pt.md index bfa2c84fc..c66a8985f 100644 --- a/templates/review.pt.md +++ b/templates/review.pt.md @@ -40,3 +40,5 @@ Horas estimadas gastas na revisão: --- ### Comentários da revisão + +_Inicie todos os seus comentários com um identificador composto por suas iniciais e um número, por exemplo, ml01, ml02, etc._ \ No newline at end of file From 14204d7a8b484ecd2bf07e16cabb6c11685eaf5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Tue, 1 Sep 2026 15:37:40 +0200 Subject: [PATCH 6/7] clarify, thx @yabellini --- softwarereview_author.Rmd | 2 +- softwarereview_author.es.Rmd | 4 +++- softwarereview_author.pt.Rmd | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/softwarereview_author.Rmd b/softwarereview_author.Rmd index 6ce7b3085..1ec5486cf 100644 --- a/softwarereview_author.Rmd +++ b/softwarereview_author.Rmd @@ -84,7 +84,7 @@ If you intend to submit an accompanying manuscript for your package, rOpenSci ha - 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](#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. +- We encourage authors and reviewers to keep the conversation going in the issue comments when needed. You don't have to limit the discussion to the formal review and the responses cycle. 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_author.es.Rmd b/softwarereview_author.es.Rmd index a9de10c25..fbc0d8e34 100644 --- a/softwarereview_author.es.Rmd +++ b/softwarereview_author.es.Rmd @@ -84,7 +84,9 @@ Si tiene intención de enviar un artículo científico sobre tu paquete, rOpenSc - Si tu paquete cumple con los criterios mínimos, se le asignará de 1 a 3 personas para hacer la revisión, a quienes se les pedirá proporcionar revisiones en forma de comentarios sobre tu *issue* en un plazo máximo de 3 semanas. - Mientras se revisa tu paquete, por favor, no hagas ningún cambio, salvo las correcciones urgentes. De hecho, los revisores deben poder revisar la última versión (la mejor hasta ahora) de tu software, y esa versión no debería cambiar. - Te pedimos que respondas a estos comentarios en un plazo máximo de 2 semanas desde la última revisión presentada, pero puedes actualizar tu paquete o responder en cualquier momento. Tu respuesta debe incluir un enlace a la actualización del archivo [*NEWS.md*](#news) de tu paquete. Aquí tienes [un ejemplo de respuesta](https://github.com/ropensci/software-review/issues/593#issuecomment-1714421144). Una vez hayas respondido, [enviala a nuestra base de datos usando nuestro bot](#submit-response-to-reviewers). Si las personas que revisaron tu paquete [usaron prefijos](#prefixing) antes de sus comentarios, por ejemplo, ml01, ml02, úsalos también en tu respuesta. -- Animamos a la continuación de conversaciones entre autores y revisores. Consulta la [guía de revisión](#reviewerguide) para más detalles. +- + +Animamos a las personas autoras y revisoras a que usen los comentarios del issue para mantener el diálogo cuando sea necesario. No es necesario limitar el debate al ciclo formal de revisión y respuestas. Consulta la [guía de revisión](#reviewerguide) para más detalles. - Si algún cambio en el paquete puede modificar los resultados de [`pkgcheck`](https://docs.ropensci.org/pkgcheck), se puede solicitar un nuevo chequeo con el comando `@ropensci-review-bot check package`. - Por favor, notifícanos inmediatamente si ya no puedes mantener tu paquete o responder a las revisiones. En ese caso, se espera que retractes el envío o que encuentres responsables alternativos para mantener del paquete. También puedes discutir los problemas de mantenimiento en el Slack de rOpenSci. - Una vez que tu paquete sea aceptado, te proporcionaremos más instrucciones sobre la transferencia de tu repositorio al repositorio de rOpenSci. diff --git a/softwarereview_author.pt.Rmd b/softwarereview_author.pt.Rmd index 162539909..cea95add5 100644 --- a/softwarereview_author.pt.Rmd +++ b/softwarereview_author.pt.Rmd @@ -84,7 +84,7 @@ Se você pretende enviar um manuscrito de acompanhamento para seu o pacote, a rO - Se o seu pacote atender aos critérios mínimos, o editor designará de 1 a 3 revisores. Eles serão solicitados a fornecer revisões como comentários sobre a sua _issue_ (submissão) dentro de 3 semanas. - Enquanto seu pacote estiver em análise, por favor, não faça nenhuma alteração, exceto correções de emergência. Afinal, os(as) revisores(as) precisam poder analisar a versão mais recente (a melhor até o momento) do seu software, e essa versão não deve sofrer alterações. - Pedimos que você responda aos comentários dos revisores em até 2 semanas após a última revisão enviada, mas você pode fazer atualizações no seu pacote ou responder a qualquer momento. Sua resposta deve incluir um link para a versão atualizada da sua [NEWS.md](#news) do seu pacote. Aqui está um [exemplo de resposta de autor](https://github.com/ropensci/software-review/issues/160#issuecomment-355043656). Quando sua resposta for enviada, [submeta-a utilizando o bot](#submit-response-to-reviewers). Se os revisores [usarem prefixos](#prefixing) antes de seus comentários, por exemplo, ml01, ml02, use-os também em sua resposta. -- Incentivamos conversas contínuas entre autores e revisores. Consulte a seção [guia de revisão](#reviewerguide) para obter mais detalhes. +- Incentivamos os autores e revisores a utilizarem os comentários da issue para manter o diálogo sempre que necessário. Não é preciso limitar a discussão ao ciclo formal de revisão e respostas. Consulte a seção [guia de revisão](#reviewerguide) para obter mais detalhes. - Frequentemente, mudanças no pacote podem alterar os resultados automatizados [das verificações `pkgcheck`](https://docs.ropensci.org/pkgcheck). Para avaliar isso, autores podem solicitar uma nova verificação do pacote com o comando `@ropensci-review-bot check package`. - Notifique-nos imediatamente se você não puder mais manter o seu pacote ou responder às revisões. Nestes casos, se espera que você retire a submissão ou que encontre mantenedores alternativos para o pacote. Você também pode discutir questões de manutenção na área de trabalho da rOpenSci no Slack. - Assim que seu pacote for aprovado, forneceremos mais instruções sobre a transferência do seu repositório para o repositório da rOpenSci. From db75a2a0701893c3b9ea6ba8210c03810a727332 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ma=C3=ABlle=20Salmon?= Date: Tue, 1 Sep 2026 15:47:54 +0200 Subject: [PATCH 7/7] fix crossrefs --- softwarereview_reviewer.es.Rmd | 2 +- softwarereview_reviewer.pt.Rmd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/softwarereview_reviewer.es.Rmd b/softwarereview_reviewer.es.Rmd index 7790fdea3..c6f967002 100644 --- a/softwarereview_reviewer.es.Rmd +++ b/softwarereview_reviewer.es.Rmd @@ -72,7 +72,7 @@ Puedes volver a correr la comprobación del paquete de `@ropensci-review-bot` en Por favor, en tus revisiones dirígete con respeto y amabilidad hacia las personas que presentaron el paquete. Nuestro [código de conducta](#code-of-conduct) es obligatorio para quienes participan en nuestro proceso de revisión. Esperamos que envíes tu revisión en un plazo de 3 semanas, según el plazo establecido por la persona a cargo de la edición. Por favor, ponte en contacto con esta persona directamente o mediante el *issue* de envío para informarle de posibles retrasos. -#### Formato {#prefijo} +#### Formato {#prefixing} Es posible que escribas muchos comentarios individuales como parte de tu revisión. Para facilitar la comunicación en torno a ellos, por favor, antepone a tus respuestas un prefijo como el siguiente, con tus iniciales —a menos que las compartas con alguien más en el hilo— y un número: diff --git a/softwarereview_reviewer.pt.Rmd b/softwarereview_reviewer.pt.Rmd index 20b4bd37f..2be6a0608 100644 --- a/softwarereview_reviewer.pt.Rmd +++ b/softwarereview_reviewer.pt.Rmd @@ -70,7 +70,7 @@ Os(as) revisores(as) também podem gerar novamente os resultados da verificaçã Seja respeitoso e gentil com os(as) autores(as) em suas avaliações. Nosso [código de conduta](#code-of-conduct) é obrigatório para todos os envolvidos em nosso processo de avaliação. Esperamos que você envie sua avaliação em até 3 (três) semanas, de acordo com o prazo estabelecido pelo(a) editor(a). Entre em contato com o(a) editor(a) diretamente ou no tópico de envio para informá-lo sobre possíveis atrasos. -#### Formatação {#prefixo} +#### Formatação {#prefixing} Você pode estar escrevendo muitos comentários individuais como parte da sua revisão. Para facilitar a comunicação em torno deles, por favor, coloque um prefixo nas suas respostas da seguinte forma: suas iniciais — a menos que você as compartilhe com outra pessoa no tópico — e um número: