diff --git a/booknews.Rmd b/booknews.Rmd index e21821c28..8745dbb23 100644 --- a/booknews.Rmd +++ b/booknews.Rmd @@ -2,6 +2,7 @@ ## Dev version +- 2026-05-29, link in reviewer guide to stats template for stats reviews (#1012) - 2026-04-10, two fixes to roxygen2 tags mentions (#1000, #1001, `@Pakillo`). Now 4 digits for PRs and issues! ## 1.0.0 diff --git a/softwarereview_reviewer.Rmd b/softwarereview_reviewer.Rmd index 94eb744fb..8c26363d4 100644 --- a/softwarereview_reviewer.Rmd +++ b/softwarereview_reviewer.Rmd @@ -40,7 +40,9 @@ All submissions trigger a detailed report on package structure and functionality ### General guidelines {#general-guidelines} -To review a package, please begin by copying our [review template](#reviewtemplate) and using it as a high-level checklist. In addition to checking off the minimum criteria, we ask that you provide general comments addressing the following: +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. +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)? - Are there improvements that could be made to the code style and to code patterns? For instance, do functions need to be broken down into smaller helper functions and is the role of each helper function clear? diff --git a/softwarereview_reviewer.es.Rmd b/softwarereview_reviewer.es.Rmd index e84324e7d..295c31b80 100644 --- a/softwarereview_reviewer.es.Rmd +++ b/softwarereview_reviewer.es.Rmd @@ -34,7 +34,9 @@ Todos los envíos generan un informe detallado sobre la estructura y funcionalid ### Directrices generales {#general-guidelines} -Para revisar un paquete, empieza por copiar nuestra [plantilla de revisión](#reviewtemplate) y utilízala como lista de verificación general. Además de marcar los criterios mínimos, te pedimos que hagas comentarios generales sobre lo siguiente: +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. +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 empaquetado de rOpenSci](#building)? - ¿Pueden mejorarse el estilo y los patrones del código? Por ejemplo, ¿es necesario dividir las funciones en funciones auxiliares más pequeñas y está claro el papel de cada función auxiliar? @@ -115,5 +117,3 @@ Te animamos a que preguntes y opines sobre el proceso de revisión en https://gi Las personas que enviaron el paquete a revisón deben responder en un plazo de 2 semanas con sus cambios en el paquete en respuesta a tu revisión. En esta fase, te pedimos que respondas si los cambios abordan suficientemente las cuestiones planteadas en tu revisión. Fomentamos el debate continuo entre quienes enviaron el paquete y quienes lo revisan, y también puedes pedir que quienes están a cargo de la edición aclaren cosas en el mismo hilo. Utilizarás la [plantilla de aprobación](#approval2template). - - diff --git a/softwarereview_reviewer.pt.Rmd b/softwarereview_reviewer.pt.Rmd index 7ca6fe245..2ae8117f5 100644 --- a/softwarereview_reviewer.pt.Rmd +++ b/softwarereview_reviewer.pt.Rmd @@ -1,119 +1,118 @@ - -# Guia para revisores {#reviewerguide} - -```{block, type="summaryblock"} -Obrigado por aceitar revisar um pacote para a rOpenSci! Este capítulo consiste em nossas diretrizes para [preparar](#preparereview), [enviar](#submitreview) e [acompanhar](#followupreviewer) a sua revisão. - -Você pode entrar em contato com o(a) editor(a) responsável pela submissão para esclarecer qualquer dúvida que tenha sobre o processo ou sobre a sua revisão. - -Tente ao máximo concluir sua avaliação em até 3 semanas após o aceite da solicitação de avaliação. Nós vamos lembrar os(as) revisores(as) das datas de vencimento, tanto futuras quanto passadas. Os(as) editores(as) podem designar revisores(as) adicionais ou alternativos se uma revisão estiver muito atrasada. - -**A comunidade da rOpenSci é o nosso melhor patrimônio. -Nosso objetivo é que as revisões sejam abertas, colaborativas e focadas na melhoria da qualidade do software. -Seja respeitoso e gentil! -Consulte o nosso guia para revisores e também o [código de conduta] (https://ropensci.org/code-of-conduct/) para obter mais informações.** - -_Se você usar nossos processos, guias, listas de verificação, etc., ao revisar um software em outra plataforma, por favor, notifique os envolvidos (e.g., editores(as) de periódicos, estudantes ou equipes de revisão interna de código) que esses processos, padrões e materiais são provenientes da rOpenSci, e nos informe em nosso [fórum público] (https://ropensci.org/usecases) ou em [particular por e-mail] (https://ropensci.org/contact/)._ -``` - -## Se voluntariando como revisor(a) {#volunteering-as-a-reviewer} - -Obrigado pelo seu desejo de participar como revisor(a) da revisão por pares de software da rOpenSci! - -Por favor, preencha o nosso [formulário de voluntariado](https://ropensci.org/software-reviewer). - -Se você encontrar alguma submissão que seja particularmente relevante para seus interesses, envie um e-mail para `info@ropensci.org`, incluindo o nome do pacote, a URL da *issue* que corresponde a este envio e o nome do(a) editor(a) responsável. -No entanto, lembre-se de que o(a) editor(a) é responsável por indicar os(as) potenciais revisores(as), sendo possível que outras pessoas já tenham sido convidadas. -Pedimos que não se candidate a todas as submissões e também evite se voluntariar diretamente pela interface do GitHub. - -Para saber outras maneiras de contribuir, consulte o [Guia de contribuição da rOpenSci](https://contributing.ropensci.org/). - -## Preparando a sua revisão {#preparereview} - -As revisões devem ser baseadas na versão mais recente da *branch* `main` no GitHub, a menos que os(as) autores(as) do pacote indiquem o contrário. -Todos os envios criam um relatório detalhado, gerado pelo nosso pacote [`pkgcheck`](https://docs.ropensci.org/pkgcheck/), sobre a estrutura e a funcionalidade do pacote enviado. Se o pacote tiver sido alterado substancialmente desde as últimas verificações, você pode solicitar uma nova verificação com o comando `@ropensci-review-bot check package`. Observe que, ao instalar o pacote para revisá-lo, você deve se certificar de que todas as dependências estão disponíveis em sua máquina (por exemplo, você pode executar `pak::pak()` para isso). - -### Diretrizes gerais {#general-guidelines} - -Para revisar um pacote, comece copiando o nosso [modelo de revisão](#reviewtemplate) e use ele como uma lista de verificações que precisam ser feitas. Além de marcar os critérios mínimos, pedimos que você forneça comentários gerais abordando o seguinte: - -- O pacote está de acordo com os requisitos do [Guia de pacotes da rOpenSci](#building)? -- Há melhorias que poderiam ser feitas no estilo e nos padrões de código? Por exemplo, as funções precisam ser divididas em funções auxiliares menores e o papel de cada função auxiliar está claro? -- Há duplicação de código no pacote que deveria ser reduzida? -- Existem funções no R básico ou na dependência leve que fornecem a mesma interface que algumas funções auxiliares no pacote? -- Há melhorias na interface do usuário que poderiam ser feitas? -- Existem melhorias de desempenho que podem ser feitas? -- A documentação (instruções de instalação, *vignettes*, exemplos e demonstrações) é clara e suficiente? O princípio de *vários pontos de entrada* está sendo usado? Ou seja, a documentação leva em conta o fato de que qualquer parte da documentação pode ser o primeiro encontro do usuário com o pacote e/ou com as ferramentas e os dados que ele contém? -- 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. - -Incentivamos você a usar ferramentas automatizadas para facilitar a revisão. Isso inclui: - -- Verificar o relatório inicial do pacote gerado pelo nosso `@ropensci-review-bot`. -- Verificar os registros (logs) nos serviços de integração contínua utilizados pelo pacote (GitHub Actions, Codecov, etc.) -- Executar `devtools::check()` e `devtools::test()` no pacote para localizar quaisquer erros que possam ter passado despercebidos pelo(a) autor(a). -- Verificar se a omissão de testes é justificada (e.g., o uso de `skip_on_cran()` em testes que fazem solicitações reais de API vs. ignorar todos os testes em um sistema operacional). -- Se o pacote não for enviado por meio da *branch* padrão/principal, lembre-se de mudar para a *branch* de revisão que foi submetida antes de iniciar sua revisão. Nesse caso, você também terá que pesquisar o pacote localmente, dado que a pesquisa no GitHub é limitada à *branch* padrão. Além disso, documentações hospedadas em um website tipo `pkgdown` não são necessariamente atualizadas, por isso recomendamos que você inspecione a documentação do pacote localmente, executando `pkgdown::build_site()`. - -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). - -### Interações feitas fora dos canais oficiais {#off-thread-interactions} - -Se você interagiu com os(as) autores(as) do pacote e falou sobre a revisão fora de um tópico de revisão (como em _chats_, mensagens diretas, pessoalmente ou *issues* no repositório do projeto), certifique-se de que sua revisão capture e/ou referencie elementos dessas conversas que sejam relevantes para o processo. - -### Experiências de revisores(as) anteriores {#experience-from-past-reviewers} - -Revisores(as) iniciantes podem achar útil ler sobre algumas revisões anteriores. Em geral, você pode encontrar os [tópicos de envio de pacotes que já foram integrados](https://github.com/ropensci/software-review/issues?q=is%3Aissue+is%3Aclosed+label%3A6%2Fapproved). Aqui, estão alguns exemplos de revisões (observe que suas revisões não precisam ser tão longas quanto esses exemplos): - -- [revisão 1](https://github.com/ropensci/software-review/issues/191#issuecomment-367166658) e [revisão 2](https://github.com/ropensci/software-review/issues/191#issuecomment-368254623) de `rtika` - -- `NLMR` [revisão 1](https://github.com/ropensci/software-review/issues/188#issuecomment-368042693) e [revisão2](https://github.com/ropensci/software-review/issues/188#issuecomment-369310831) - -- `bowerbird` [comentário pré-revisão](https://github.com/ropensci/software-review/issues/139#issuecomment-322713737), [revisão 1](https://github.com/ropensci/software-review/issues/139#issuecomment-342380870), [revisão 2](https://github.com/ropensci/software-review/issues/139#issuecomment-342724843). - -- `rusda` [revisão](https://github.com/ropensci/software-review/issues/18#issuecomment-120445737) (de antes de termos um modelo de revisão) - -Você pode ler algumas publicações escritas por avaliadores(as) sobre as suas experiências [através deste link](https://ropensci.org/tags/reviewer/). Em especial, [nesta postagem de Mara Averick](https://ropensci.org/blog/2017/08/22/first-package-review/), você pode ler sobre o papel de "usuário ingênuo" que um(a) revisor(a) pode assumir para fornecer um feedback útil, mesmo sem ser especialista no tópico ou na implementação do pacote, ao se perguntar: *"O que eu achava que seria feito? Realmente, faz isso? Quais são os detalhes que me assustam?"*. Em [outra postagem](https://ropensci.org/blog/2017/09/08/first-review-experiences/), Verena Haunschmid compartilha sua experiência de alternar entre usar o pacote e revisar seu código. - -O ex-revisor e autor de pacotes [Adam Sparks](https://adamhsparks.netlify.app/) escreveu o seguinte "\[escreva\] uma boa crítica da estrutura do pacote e das práticas recomendadas de codificação. Se você souber como fazer algo melhor, diga-me. É fácil perder oportunidades de documentação como desenvolvedor(a); porém, como revisor(a), você tem uma visão diferente. Você é um usuário que pode dar um *feedback*. O que não está claro no pacote? Como você poderia deixar isso mais claro? Se você estiver usando-o pela primeira vez, é fácil? Você conhece algum outro pacote R que talvez eu devesse usar? Ou há algum que eu esteja usando e que talvez não devesse usar? Se você puder contribuir com o pacote, então contribua." - -### Pacote de ajuda para revisores {#helper-package-for-reviewers} - -Se estiver trabalhando no RStudio, você pode otimizar o fluxo de trabalho de revisão usando o pacote [`pkgreviewr`](https://github.com/ropensci-org/pkgreviewr), criado pela editora associada Anna Krystalli. Digamos que você tenha aceitado revisar o pacote `refnet`, então você escreveria o seguinte: - -``` -remotes::install_github("ropensci-org/pkgreviewr") -library(pkgreviewr) -pkgreview_create(pkg_repo = "embruna/refnet", - review_parent = "~/Documents/workflows/rOpenSci/reviews/") -``` - -Como resultado: - -- o repositório do GitHub do pacote `refnet` será clonado. -- um projeto de revisão será criado, contendo um bloco de notas para você preencher, já usando o modelo de revisão recomendado. - -Observe que, se o pacote não for enviado por meio da *branch* padrão/principal, você precisará mudar para a *branch* enviada antes de iniciar a revisão. - -### Comentários sobre o processo {#feedback-on-the-process} - -Incentivamos você a fazer perguntas e fornecer feedbacks sobre o processo de revisão em https://github.com/ropensci/software-review-meta/issues - -## Envio da revisão {#submitreview} - -- Quando sua revisão estiver concluída, cole-a como um comentário na *issue* onde a revisão do pacote está sendo feita/tratada. -- Comentários adicionais são bem-vindos na mesma issue. Esperamos que as revisões de pacotes funcionem como uma conversa contínua com os(as) autores(as), em vez de uma única rodada de revisões típica de manuscritos acadêmicos. -- Você também pode enviar *issues* ou *Pull Requests* diretamente para o repositório dos pacotes, se preferir, mas, se o fizer, comente sobre eles e coloque um link para eles dentro do tópico onde a revisão do pacote está sendo tratada, para que tenhamos um registro centralizado da sua revisão. -- Inclua uma estimativa de quantas horas você gastou na revisão. - -## Acompanhamento da revisão {#followupreviewer} - -Os(as) autores(as) devem responder dentro de 2 (duas) semanas com as alterações feitas no pacote em resposta à sua avaliação. Nesse estágio, pedimos que você avalie se as alterações são suficientes para resolver as questões levantadas em sua revisão. Incentivamos a discussão contínua entre autores(as) de pacotes e revisores(as), e você também pode pedir aos editores que esclareçam os problemas no tópico de revisão. - -Você usará o [modelo de aprovação](#approval2template). - - +# Guia para revisores {#reviewerguide} + +```{block, type="summaryblock"} +Obrigado por aceitar revisar um pacote para a rOpenSci! Este capítulo consiste em nossas diretrizes para [preparar](#preparereview), [enviar](#submitreview) e [acompanhar](#followupreviewer) a sua revisão. + +Você pode entrar em contato com o(a) editor(a) responsável pela submissão para esclarecer qualquer dúvida que tenha sobre o processo ou sobre a sua revisão. + +Tente ao máximo concluir sua avaliação em até 3 semanas após o aceite da solicitação de avaliação. Nós vamos lembrar os(as) revisores(as) das datas de vencimento, tanto futuras quanto passadas. Os(as) editores(as) podem designar revisores(as) adicionais ou alternativos se uma revisão estiver muito atrasada. + +**A comunidade da rOpenSci é o nosso melhor patrimônio. +Nosso objetivo é que as revisões sejam abertas, colaborativas e focadas na melhoria da qualidade do software. +Seja respeitoso e gentil! +Consulte o nosso guia para revisores e também o [código de conduta] (https://ropensci.org/code-of-conduct/) para obter mais informações.** + +_Se você usar nossos processos, guias, listas de verificação, etc., ao revisar um software em outra plataforma, por favor, notifique os envolvidos (e.g., editores(as) de periódicos, estudantes ou equipes de revisão interna de código) que esses processos, padrões e materiais são provenientes da rOpenSci, e nos informe em nosso [fórum público] (https://ropensci.org/usecases) ou em [particular por e-mail] (https://ropensci.org/contact/)._ +``` + +## Se voluntariando como revisor(a) {#volunteering-as-a-reviewer} + +Obrigado pelo seu desejo de participar como revisor(a) da revisão por pares de software da rOpenSci! + +Por favor, preencha o nosso [formulário de voluntariado](https://ropensci.org/software-reviewer). + +Se você encontrar alguma submissão que seja particularmente relevante para seus interesses, envie um e-mail para `info@ropensci.org`, incluindo o nome do pacote, a URL da *issue* que corresponde a este envio e o nome do(a) editor(a) responsável. +No entanto, lembre-se de que o(a) editor(a) é responsável por indicar os(as) potenciais revisores(as), sendo possível que outras pessoas já tenham sido convidadas. +Pedimos que não se candidate a todas as submissões e também evite se voluntariar diretamente pela interface do GitHub. + +Para saber outras maneiras de contribuir, consulte o [Guia de contribuição da rOpenSci](https://contributing.ropensci.org/). + +## Preparando a sua revisão {#preparereview} + +As revisões devem ser baseadas na versão mais recente da *branch* `main` no GitHub, a menos que os(as) autores(as) do pacote indiquem o contrário. +Todos os envios criam um relatório detalhado, gerado pelo nosso pacote [`pkgcheck`](https://docs.ropensci.org/pkgcheck/), sobre a estrutura e a funcionalidade do pacote enviado. Se o pacote tiver sido alterado substancialmente desde as últimas verificações, você pode solicitar uma nova verificação com o comando `@ropensci-review-bot check package`. Observe que, ao instalar o pacote para revisá-lo, você deve se certificar de que todas as dependências estão disponíveis em sua máquina (por exemplo, você pode executar `pak::pak()` para isso). + +### Diretrizes gerais {#general-guidelines} + +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. +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)? +- Há melhorias que poderiam ser feitas no estilo e nos padrões de código? Por exemplo, as funções precisam ser divididas em funções auxiliares menores e o papel de cada função auxiliar está claro? +- Há duplicação de código no pacote que deveria ser reduzida? +- Existem funções no R básico ou na dependência leve que fornecem a mesma interface que algumas funções auxiliares no pacote? +- Há melhorias na interface do usuário que poderiam ser feitas? +- Existem melhorias de desempenho que podem ser feitas? +- A documentação (instruções de instalação, *vignettes*, exemplos e demonstrações) é clara e suficiente? O princípio de *vários pontos de entrada* está sendo usado? Ou seja, a documentação leva em conta o fato de que qualquer parte da documentação pode ser o primeiro encontro do usuário com o pacote e/ou com as ferramentas e os dados que ele contém? +- 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. + +Incentivamos você a usar ferramentas automatizadas para facilitar a revisão. Isso inclui: + +- Verificar o relatório inicial do pacote gerado pelo nosso `@ropensci-review-bot`. +- Verificar os registros (logs) nos serviços de integração contínua utilizados pelo pacote (GitHub Actions, Codecov, etc.) +- Executar `devtools::check()` e `devtools::test()` no pacote para localizar quaisquer erros que possam ter passado despercebidos pelo(a) autor(a). +- Verificar se a omissão de testes é justificada (e.g., o uso de `skip_on_cran()` em testes que fazem solicitações reais de API vs. ignorar todos os testes em um sistema operacional). +- Se o pacote não for enviado por meio da *branch* padrão/principal, lembre-se de mudar para a *branch* de revisão que foi submetida antes de iniciar sua revisão. Nesse caso, você também terá que pesquisar o pacote localmente, dado que a pesquisa no GitHub é limitada à *branch* padrão. Além disso, documentações hospedadas em um website tipo `pkgdown` não são necessariamente atualizadas, por isso recomendamos que você inspecione a documentação do pacote localmente, executando `pkgdown::build_site()`. + +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). + +### Interações feitas fora dos canais oficiais {#off-thread-interactions} + +Se você interagiu com os(as) autores(as) do pacote e falou sobre a revisão fora de um tópico de revisão (como em _chats_, mensagens diretas, pessoalmente ou *issues* no repositório do projeto), certifique-se de que sua revisão capture e/ou referencie elementos dessas conversas que sejam relevantes para o processo. + +### Experiências de revisores(as) anteriores {#experience-from-past-reviewers} + +Revisores(as) iniciantes podem achar útil ler sobre algumas revisões anteriores. Em geral, você pode encontrar os [tópicos de envio de pacotes que já foram integrados](https://github.com/ropensci/software-review/issues?q=is%3Aissue+is%3Aclosed+label%3A6%2Fapproved). Aqui, estão alguns exemplos de revisões (observe que suas revisões não precisam ser tão longas quanto esses exemplos): + +- [revisão 1](https://github.com/ropensci/software-review/issues/191#issuecomment-367166658) e [revisão 2](https://github.com/ropensci/software-review/issues/191#issuecomment-368254623) de `rtika` + +- `NLMR` [revisão 1](https://github.com/ropensci/software-review/issues/188#issuecomment-368042693) e [revisão2](https://github.com/ropensci/software-review/issues/188#issuecomment-369310831) + +- `bowerbird` [comentário pré-revisão](https://github.com/ropensci/software-review/issues/139#issuecomment-322713737), [revisão 1](https://github.com/ropensci/software-review/issues/139#issuecomment-342380870), [revisão 2](https://github.com/ropensci/software-review/issues/139#issuecomment-342724843). + +- `rusda` [revisão](https://github.com/ropensci/software-review/issues/18#issuecomment-120445737) (de antes de termos um modelo de revisão) + +Você pode ler algumas publicações escritas por avaliadores(as) sobre as suas experiências [através deste link](https://ropensci.org/tags/reviewer/). Em especial, [nesta postagem de Mara Averick](https://ropensci.org/blog/2017/08/22/first-package-review/), você pode ler sobre o papel de "usuário ingênuo" que um(a) revisor(a) pode assumir para fornecer um feedback útil, mesmo sem ser especialista no tópico ou na implementação do pacote, ao se perguntar: *"O que eu achava que seria feito? Realmente, faz isso? Quais são os detalhes que me assustam?"*. Em [outra postagem](https://ropensci.org/blog/2017/09/08/first-review-experiences/), Verena Haunschmid compartilha sua experiência de alternar entre usar o pacote e revisar seu código. + +O ex-revisor e autor de pacotes [Adam Sparks](https://adamhsparks.netlify.app/) escreveu o seguinte "\[escreva\] uma boa crítica da estrutura do pacote e das práticas recomendadas de codificação. Se você souber como fazer algo melhor, diga-me. É fácil perder oportunidades de documentação como desenvolvedor(a); porém, como revisor(a), você tem uma visão diferente. Você é um usuário que pode dar um *feedback*. O que não está claro no pacote? Como você poderia deixar isso mais claro? Se você estiver usando-o pela primeira vez, é fácil? Você conhece algum outro pacote R que talvez eu devesse usar? Ou há algum que eu esteja usando e que talvez não devesse usar? Se você puder contribuir com o pacote, então contribua." + +### Pacote de ajuda para revisores {#helper-package-for-reviewers} + +Se estiver trabalhando no RStudio, você pode otimizar o fluxo de trabalho de revisão usando o pacote [`pkgreviewr`](https://github.com/ropensci-org/pkgreviewr), criado pela editora associada Anna Krystalli. Digamos que você tenha aceitado revisar o pacote `refnet`, então você escreveria o seguinte: + +``` +remotes::install_github("ropensci-org/pkgreviewr") +library(pkgreviewr) +pkgreview_create(pkg_repo = "embruna/refnet", + review_parent = "~/Documents/workflows/rOpenSci/reviews/") +``` + +Como resultado: + +- o repositório do GitHub do pacote `refnet` será clonado. +- um projeto de revisão será criado, contendo um bloco de notas para você preencher, já usando o modelo de revisão recomendado. + +Observe que, se o pacote não for enviado por meio da *branch* padrão/principal, você precisará mudar para a *branch* enviada antes de iniciar a revisão. + +### Comentários sobre o processo {#feedback-on-the-process} + +Incentivamos você a fazer perguntas e fornecer feedbacks sobre o processo de revisão em https://github.com/ropensci/software-review-meta/issues + +## Envio da revisão {#submitreview} + +- Quando sua revisão estiver concluída, cole-a como um comentário na *issue* onde a revisão do pacote está sendo feita/tratada. +- Comentários adicionais são bem-vindos na mesma issue. Esperamos que as revisões de pacotes funcionem como uma conversa contínua com os(as) autores(as), em vez de uma única rodada de revisões típica de manuscritos acadêmicos. +- Você também pode enviar *issues* ou *Pull Requests* diretamente para o repositório dos pacotes, se preferir, mas, se o fizer, comente sobre eles e coloque um link para eles dentro do tópico onde a revisão do pacote está sendo tratada, para que tenhamos um registro centralizado da sua revisão. +- Inclua uma estimativa de quantas horas você gastou na revisão. + +## Acompanhamento da revisão {#followupreviewer} + +Os(as) autores(as) devem responder dentro de 2 (duas) semanas com as alterações feitas no pacote em resposta à sua avaliação. Nesse estágio, pedimos que você avalie se as alterações são suficientes para resolver as questões levantadas em sua revisão. Incentivamos a discussão contínua entre autores(as) de pacotes e revisores(as), e você também pode pedir aos editores que esclareçam os problemas no tópico de revisão. + +Você usará o [modelo de aprovação](#approval2template).