diff --git a/booknews.Rmd b/booknews.Rmd index 3c7c377f1..0f3580496 100644 --- a/booknews.Rmd +++ b/booknews.Rmd @@ -2,6 +2,8 @@ ## dev version +- 2025-04-03, add details about MEE process and structure the author guide a bit more (`@robitalec`, #862) + - 2025-03-11, add note in the packaging guide about checking maintenance status of dependencies (#881) - 2025-03-11, add item about "top level code" in packaging guide (#879) diff --git a/softwarereview_author.Rmd b/softwarereview_author.Rmd index 73533b61a..a2ee38e7c 100644 --- a/softwarereview_author.Rmd +++ b/softwarereview_author.Rmd @@ -11,30 +11,54 @@ This concise guide presents the software peer review process for you as a packag ## Planning a Submission (or a Pre-Submission Enquiry) {#planning-a-submission-or-a-pre-submission-enquiry} -- Do you expect to maintain your package for at least 2 years, or to be able to identify a new maintainer? + +### Scope + - Consult our [policies](#policies) see if your package meets our criteria for fitting into our suite and does not overlap with other packages. - If you are unsure whether a package meets our criteria, feel free to open an issue as a pre-submission inquiry to ask if the package is appropriate. - [Example response regarding overlap](https://github.com/ropensci/software-review/issues/199#issuecomment-375358362). Also consider adding some points about similar packages to your [package documentation](#docs-general). + +### Lifecycle + +- Please do not submit several packages at a time: we request you wait until a package has been approved before you submit another one. +- Do you expect to maintain your package for at least 2 years, or to be able to identify a new maintainer? - Please consider the best time in your package's development to submit. Your package should be sufficiently mature so that reviewers are able to review all essential aspects, but keep in mind that review may result in major changes. - We strongly suggest submitting your package for review *before* publishing on CRAN or submitting a software paper describing the package to a journal. Review feedback may result in major improvements and updates to your package, including renaming and breaking changes to functions. - Do not submit your package for review while it or an associated manuscript is also under review at another venue, as this may result in conflicting requests for changes. - Please also consider the time and effort needed to respond to reviews: think about your availability or that of your collaborators in the next weeks and months following a submission. Note that reviewers are volunteers, and we ask that you respect their time and effort by responding in a timely and respectful manner. - If you use [repostatus.org badges](https://www.repostatus.org/) (which we recommend), submit when you're ready to get an *Active* instead of *WIP* badge. Similarly, if you use [lifecycle badges](https://www.tidyverse.org/lifecycle/), submission should happen when the package is *Stable*. +- Your package will continue to evolve after review, the chapter on *Package evolution* [provides guidance about the topic](#evolution). + +### Documentation + - For any submission or pre-submission inquiry the README of your package should provide enough information about your package (goals, usage, similar packages) for the editors to assess its scope without having to install the package. Even better, set up a pkgdown website for allowing more detailed assessment of functionality online. - At the submission stage, all major functions should be stable enough to be fully documented and tested; the README should make a strong case for the package. - Your README file should strive to explain your package's functionality and aims, assuming readers have little to no domain knowledge. All technical tems, including references to other software, should be clarified. - Your package will continue to evolve after review, the chapter on *Package evolution* [provides guidance about the topic](#evolution). -- Please do not submit several packages at a time: we request you wait until a package has been approved before you submit another one. ## Preparing for Submission {#preparing-for-submission} -- Read and follow [our packaging style guide](#building), [reviewer's guide](#preparereview) to ensure your package meets our style and quality criteria. +### Asking for help + - Feel free to ask any questions about the process, or your specific package, in our [Discussion Forum](https://discuss.ropensci.org). + +### Guidelines + +- Read and follow [our packaging style guide](#building), [reviewer's guide](#preparereview) to ensure your package meets our style and quality criteria. + +### Automatic checks + - All submissions are automatically checked by our [pkgcheck](https://docs.ropensci.org/pkgcheck/) system to ensure packages follow our guidelines. All authors are expected to have run [the main `pkgcheck` function](https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html) locally to confirm that the package is ready to be submitted. Alternatively, an even easier way to ensure a package is ready for submission is to use [the `pkgcheck` GitHub Action](https://github.com/ropensci-review-tools/pkgcheck-action) to run `pkgcheck` as a GitHub Action, as described in [our blog post](https://ropensci.org/blog/2022/02/01/pkgcheck-action/). - If your package requires unusual system dependencies (see [*Packaging Guide*](#pkgdependencies)) for our GitHub Action to pass, please submit a pull request adding them to [our base Dockerfile](https://github.com/ropensci-review-tools/pkgcheck/blob/main/Dockerfile). - If there are any aspects of `pkgcheck` which your package is unable to pass, please explain reasons in your submission template. -- If you feel your package is in scope for the - [Journal of Open-Source Software](https://joss.theoj.org/) (JOSS), do not submit it to JOSS consideration until after the rOpenSci review process is over: if your package is deemed in scope by JOSS editors, only the accompanying short paper would be reviewed, (not the software that will have been extended reviewed by rOpenSci by that time). Not all rOpenSci packages will meet the criteria for JOSS. + +### Accompanying manuscript (optional) + +If you intend to submit an accompanying manuscript for your package, rOpenSci has a collaborative partnership with the [Journal of Open-Source Software](https://joss.theoj.org/) and [Methods in Ecology and Evolution](https://besjournals.onlinelibrary.wiley.com/journal/2041210X): + +- For a submission to Journal of Open-Source Software (JOSS), do not submit it to JOSS consideration until after the rOpenSci review process is over: if your package is deemed in scope by JOSS editors, only the accompanying short paper would be reviewed, (not the software that will have been extended reviewed by rOpenSci by that time). Not all rOpenSci packages will meet the criteria for JOSS. + +- For a submission to Methods in Ecology and Evolution (MEE), submit it to MEE only after the rOpenSci reviewers have submitted their reviews, either before or after the package has been accepted. The review collaboration with MEE was introduced in a [blog post](https://ropensci.org/blog/2017/11/29/review-collaboration-mee/). The relevant article type for MEE is [Application](https://besjournals.onlinelibrary.wiley.com/hub/journal/2041210X/features/applicationpapers) for more details. ## The Submission Process {#the-submission-process} diff --git a/softwarereview_author.es.Rmd b/softwarereview_author.es.Rmd index bd980bc80..93ab22f64 100644 --- a/softwarereview_author.es.Rmd +++ b/softwarereview_author.es.Rmd @@ -6,29 +6,53 @@ Esta guía condensa el proceso de revisión por pares desde el punto de vista de ## Planificar un envío (o una consulta previa al envío) {#planning-a-submission-or-a-pre-submission-enquiry} -- ¿Esperas mantener tu paquete durante al menos 2 años, o poder encontrar a otra persona para mantenerlo? +### Alcance + - Consulta nuestras [políticas](#policies) para evaluar si tu paquete cumple los criterios para ser incluido en nuestro conjunto de paquetes y no se superpone con otros. - - Si no sabes si un paquete cumple con nuestros criterios, no dudes en abrir un issue para consultarlo. +- Si no sabes si un paquete cumple con nuestros criterios, no dudes en abrir un _issue_ para consultarlo. - [Ejemplo de respuesta sobre solapamiento](https://github.com/ropensci/software-review/issues/199#issuecomment-375358362). Considera también añadir información sobre paquetes similares a tu [documentación de paquetes](#docs-general). + +### Ciclo de desarrollo + +- Por favor, no envies varios paquetes a la vez: te rogamos que espere hasta que un paquete haya sido aprobado antes de enviar otro. +- ¿Esperas mantener tu paquete durante al menos 2 años, o poder encontrar a otra persona para mantenerlo? - Por favor, considera cuál es el mejor momento en el desarrollo de tu paquete para presentarlo. Tu paquete debe estar lo suficientemente maduro como para que quienes lo revisen puedan evaluar todos los aspectos esenciales, pero ten en cuenta que la revisión puede resultar en cambios importantes. - Te recomendamos fuertemente que envíes tu paquete para su revisión *antes de* publicarlo en CRAN o enviar un artículo de software que describa el paquete a una revista. Las devoluciones de las revisiones pueden dar pie a importantes mejoras y actualizaciones de tu paquete, incluso cambiar el nombre o modificaciones incompatibles con versiones previas. - No envíes tu paquete para su revisión mientras éste o un artículo científico asociado también esté siendo revisado en otro lugar, ya que esto puede dar lugar a recomendaciones incompatibles. - Ten en cuenta también el tiempo y el esfuerzo necesarios para responder a las revisiones: piensa en tu disponibilidad o en la de quienes colaboran con tu paquete en las semanas y meses siguientes al envío. Ten en cuenta que las revisiones son realizadas por personas voluntarias, y te pedimos que respetes su tiempo y esfuerzo respondiendo puntual y respetuosamente. - Si utilizas [etiquetas de repostatus.org](https://www.repostatus.org/) (que recomendamos), envía tu paquete cuando esté listo para obtener la etiqueta *Active* en vez de *WIP*. Si utilizas [etiquetas de ciclo de vida](https://www.tidyverse.org/lifecycle/), el envío debe producirse cuando el paquete esté al menos en el estado *Maturing*. +- Tu paquete seguirá evolucionando después de la revisión, el capítulo sobre *Evolución de paquetes* [proporciona orientación sobre el tema](#evolution). + +### Documentación + - Para cualquier envío o consulta previa al envío, el *README* de tu paquete debería proporcionar suficiente información sobre el mismo (objetivos, uso, paquetes similares) para que quienes revisan el paquete puedan evaluar su alcance sin tener que instalarlo. Mejor aún, crea un sitio web de pkgdown para que puedan evaluar las funcionalidads detalladamente en línea. - En la fase de envío, todas las funciones principales deben ser lo suficientemente estables como para estar completamente documentadas y testeadas. El *README* tiene que dar una buena impresión de tu paquete. - El archivo *README* debe esforzarse por explicar las funcionalidades y los objetivos de tu paquete asumiendo poco o ningún conocimiento del dominio. Además, debe aclarar todos los temas técnicos, incluidas las referencias a otros software. - Tu paquete seguirá evolucionando después de la revisión, el capítulo sobre *Evolución de paquetes* [proporciona orientación sobre el tema](#evolution). -- Por favor, no envies varios paquetes a la vez: te rogamos que espere hasta que un paquete haya sido aprobado antes de enviar otro. ## Preparación para el envío {#preparing-for-submission} -- Lee y sigue nuestra [guía de estilo para paquetes](#building) y nuestra [guía para la revisión](#preparereview) para asegurarte de que tu paquete cumple nuestros criterios de estilo y calidad. +### Pedir ayuda + - No dudes en hacer cualquier pregunta sobre el proceso en general, o sobre tu paquete en particular en nuestro [foro de discusión](https://discuss.ropensci.org). + +### Directrices + +- Lee y sigue nuestra [guía de estilo para paquetes](#building) y nuestra [guía para la revisión](#preparereview) para asegurarte de que tu paquete cumple nuestros criterios de estilo y calidad. + +### Controles automáticos + - Todos los envíos son revisados automáticamente por nuestro [propio sistema](https://docs.ropensci.org/pkgcheck/) para garantizar que los paquetes sigan nuestras directrices. Se espera que hayas corrido [la función `pkgcheck`](https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html) localmente para confirmar que el paquete está listo para ser enviado. Otra forma aún más fácil de asegurarse de que un paquete está listo para su envío es utilizar [la acción de GitHub `pkgcheck`](https://github.com/ropensci-review-tools/pkgcheck-action) para ejecutar `pkgcheck` como una Acción de GitHub, como se describe en [esta publicación en nuestro blog](https://ropensci.org/blog/2022/02/01/pkgcheck-action/). - Si tu paquete requiere dependencias inusuales del sistema (ver [*Guía de Empaquetado*](#pkgdependencies) para que nuestra Acción de GitHub pase, por favor envíe un _pull request_ añadiéndolas a [nuestro _Dockerfile_ base](https://github.com/ropensci-review-tools/pkgcheck/blob/main/Dockerfile). - Si hay algún test de `pkgcheck` que tu paquete no pueda aprobar, explica los motivos en la plantilla de envío. -- Si crees que tu paquete es relevante para el [Journal of Open Source Software](https://joss.theoj.org/) (JOSS), no lo sometas a consideración de JOSS hasta que haya finalizado el proceso de revisión de rOpenSci: si el equipo de edición de JOSS considera que tu paquete está dentro de su ámbito de aplicación, sólo se revisará el breve artículo que lo acompaña (pero no el software que habrá sido revisado por rOpenSci en ese momento). No todos los paquetes de rOpenSci pueden aplicar a JOSS. + +### Artículo complementario (opcional) + +Si tiene intención de enviar un artículo científico sobre tu paquete, rOpenSci colabora con el [Journal of Open-Source Software](https://joss.theoj.org/) y [Methods in Ecology and Evolution](https://besjournals.onlinelibrary.wiley.com/journal/2041210X): + +- Envía el artículo al [Journal of Open Source Software](https://joss.theoj.org/) (JOSS),una vez que has recibido las revistas: si el equipo de edición de JOSS considera que tu paquete está dentro de su ámbito de aplicación, sólo se revisará el artículo que lo acompaña (pero no el software que ya habrá sido revisado por rOpenSci en ese momento). No todos los paquetes de rOpenSci pueden aplicar a JOSS. + +- Para un envío a Methods in Ecology and Evolution (MEE), envíelo a MEE sólo después de que el proceso de revisión de rOpenSci haya terminado, ya sea antes o después de que el paquete haya sido aceptado. La colaboración de revisión con MEE se introdujo en un [blog post](https://ropensci.org/blog/2017/11/29/review-collaboration-mee/). El tipo de artículo relevante para MEE es [Solicitud](https://besjournals.onlinelibrary.wiley.com/hub/journal/2041210X/features/applicationpapers) para más detalles. ## El proceso de envío {#the-submission-process} diff --git a/softwarereview_author.pt.Rmd b/softwarereview_author.pt.Rmd index 9af38a834..3320f3291 100644 --- a/softwarereview_author.pt.Rmd +++ b/softwarereview_author.pt.Rmd @@ -11,30 +11,52 @@ Este guia conciso apresenta o processo de revisão de software por pares, para v ## Planejando uma Submissão (ou uma Consulta de Pré-Submissão) {#planning-a-submission-or-a-pre-submission-enquiry} -- Você pretende manter o seu pacote por pelo menos 2 anos ou ser capaz de identificar um(a) novo(a) mantenedor(a)? +### Escopo + - Consulte nossas [políticas de uso](#policies) para ver se o seu pacote atende aos nossos critérios e se encaixa em nossa coleção, não se sobrepondo a outros pacotes já existentes. - Se você não tiver certeza de que um pacote atende aos nossos critérios, sinta-se à vontade para abrir um _issue_ no GitHub como uma consulta de pré-submissão para perguntar se o pacote é apropriado. - [Exemplo de resposta a sobreposição](https://github.com/ropensci/software-review/issues/199#issuecomment-375358362). Também considere adicionar alguns pontos sobre pacotes semelhantes ao seu na sua [documentação do pacote](#docs-general). + +### Ciclo de vida + +- Não envie vários pacotes ao mesmo tempo: solicitamos que você espere até que um pacote seja aprovado antes de enviar outro. +- Você pretende manter o seu pacote por pelo menos 2 anos ou ser capaz de identificar uma nova pessoa para mantê-lo? - Considere o melhor momento de desenvolvimento do seu pacote para enviar sua submissão. Seu pacote deve estar suficientemente maduro para que os revisores possam analisar todos os aspectos essenciais, mas tenha em mente que revisões podem resultar em grandes alterações. - Sugerimos enfaticamente que você envie seu pacote para análise *antes de* publicá-lo no CRAN ou antes de enviá-lo para publicação como artigo em um periódico. O _feedback_ da revisão pode resultar em grandes aprimoramentos e atualizações do seu pacote, incluindo renomeações e alterações de funções. - Não envie seu pacote para revisão enquanto este ou o manuscrito associado também estiver sendo revisado em outro local, pois isso pode resultar em solicitações conflitantes de alterações. - Considere também o tempo e o esforço necessários para responder às revisões: pense na sua disponibilidade ou na de seus colaboradores nas próximas semanas e meses após o envio da submissão. Observe que os revisores são voluntários e pedimos que você respeite o tempo e o esforço deles, respondendo de maneira oportuna e respeitosa. - Se você usa [distintivos do repostatus.org](https://www.repostatus.org/) (o que recomendamos), envie uma submissão quando você estiver pronto para receber um distintivo tipo _Active_ em vez de _WIP_. Da mesma forma, se você usa [distintivos tipo _lifecycle_](https://www.tidyverse.org/lifecycle/) o envio da submissão deverá ocorrer quando o pacote for _Stable_. +- Seu pacote continuará a evoluir após a revisão. O capítulo sobre *Evolução do pacote* [fornece mais orientações sobre este tópico](#evolution). + +### Documentação + - Para qualquer envio ou consulta de pré-submissão, o README do seu pacote deve fornecer informações suficientes sobre o pacote (objetivos, uso, pacotes semelhantes) para que os editores avaliem seu escopo sem precisar instalar o pacote. Melhor ainda, crie um website pkgdown para permitir uma avaliação mais detalhada da funcionalidade online. - No estágio de envio da submissão, todas as principais funções devem ser estáveis o suficiente para serem totalmente documentadas e testadas; o README deve apresentar uma base segura para o pacote. - Seu arquivo README deve assegurar-se em explicar a funcionalidade e os objetivos do seu pacote, presumindo que os leitores tenham pouco ou nenhum conhecimento do domínio. Todos os termos técnicos, inclusive as referências a outros softwares, devem ser esclarecidos. - Seu pacote continuará a evoluir após a revisão. O capítulo sobre *Evolução do pacote* [fornece mais orientações sobre este tópico](#evolution). -- Não envie vários pacotes ao mesmo tempo: solicitamos que você espere até que um pacote seja aprovado antes de enviar outro. ## Preparando para Submissão {#preparing-for-submission} -- Leia e siga [nosso guia de estilo de pacotes](#building) e nosso [guia do revisor](#preparereview), para garantir que seu pacote atenda aos nossos critérios de estilo e qualidade. +### Solicitação de ajuda + - Fique à vontade para fazer perguntas sobre o processo ou sobre seu pacote em específico no nosso [Fórum de discussão](https://discuss.ropensci.org). + +### Diretrizes + +- Leia e siga [nosso guia de estilo de pacotes](#building) e nosso [guia de revisão](#preparereview), para garantir que seu pacote atenda aos nossos critérios de estilo e qualidade. + +### Verificações automáticas + - Todas as submissões são verificadas automaticamente pelo nosso [`pkgcheck`](https://docs.ropensci.org/pkgcheck/) para garantir que os pacotes seguem nossas diretrizes. Espera-se que todos os autores tenham executado a [principal função do `pkgcheck`](https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html) localmente para confirmar que o pacote está pronto para ser submetido. Como alternativa, uma maneira ainda mais fácil de garantir que um pacote está pronto para ser submetido é usando [a função `pkgcheck` do GitHub Action](https://github.com/ropensci-review-tools/pkgcheck-action), conforme descrito em [nossa postagem no blog](https://ropensci.org/blog/2022/02/01/pkgcheck-action/). - Se o seu pacote exigir dependências de sistema incomuns (consulte [*Guia de pacotes*](#pkgdependencies)) para que a _GitHub Action_ seja aprovada, envie um _pull request_ adicionando-as ao [nosso arquivo Dockerfile](https://github.com/ropensci-review-tools/pkgcheck/blob/main/Dockerfile). - Se houver algum aspecto do `pkgcheck` no qual seu pacote não possa ser aprovado, explique os motivos no seu modelo de submissão. -- Se você acha que seu pacote está no escopo do - [Journal of Open-Source Software](https://joss.theoj.org/) (JOSS), não o submeta a publivação no JOSS até que o processo de revisão da rOpenSci tenha terminado. Se o seu pacote for considerado dentro do escopo pelos editores do JOSS, apenas o artigo curto que o acompanha será revisado (não o software que terá sido revisado extensivamente pela rOpenSci até aquele momento). Nem todos os pacotes da rOpenSci atenderão aos critérios do JOSS. + +### Manuscrito de acompanhamento (opcional) + +Se você pretende enviar um manuscrito de acompanhamento para seu pacote, a rOpenSci tem uma parceria de colaboração com o [Journal of Open-Source Software] (https://joss.theoj.org/) e o [Methods in Ecology and Evolution] (https://besjournals.onlinelibrary.wiley.com/journal/2041210X): + +- Para enviar um pacote ao Journal of Open-Source Software (JOSS), não o envie para consideração do JOSS até que o processo de revisão do rOpenSci tenha terminado: se o seu pacote for considerado dentro do escopo pelos editores do JOSS, apenas o artigo curto que o acompanha será revisado (não o software que terá sido revisado extensivamente pelo rOpenSci até aquele momento). Nem todos os pacotes da rOpenSci atenderão aos critérios do JOSS. +- Para uma submissão ao Methods in Ecology and Evolution (MEE), envie-a ao MEE somente depois que as revisoras e revisores da rOpenSci tiverem enviado suas revisões, antes ou depois de o pacote ter sido aceito. A colaboração de revisão com a MEE foi apresentada em uma [postagem de blog](https://ropensci.org/blog/2017/11/29/review-collaboration-mee/). O tipo de artigo relevante para a MEE é [*Applications*](https://besjournals.onlinelibrary.wiley.com/hub/journal/2041210X/features/applicationpapers) para obter mais detalhes. ## O Processo de Submissão {#the-submission-process} diff --git a/softwarereview_editor.Rmd b/softwarereview_editor.Rmd index b95708911..e0c878632 100644 --- a/softwarereview_editor.Rmd +++ b/softwarereview_editor.Rmd @@ -107,6 +107,7 @@ Each submission should be reviewed by *two* package reviewers. Although it is fi - Record the review via typing a new comment `@ropensci-review-bot submit review time