diff --git a/softwarereview_reviewer.pt.Rmd b/softwarereview_reviewer.pt.Rmd new file mode 100644 index 000000000..ec58c76bd --- /dev/null +++ b/softwarereview_reviewer.pt.Rmd @@ -0,0 +1,110 @@ + +# 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 editor responsável pela submissão para esclarecer qualquer dúvida que tenha sobre o processo ou sobre a sua revisão. + +Por favor tente concluir sua avaliação em até 3 semanas após aceitar uma solicitação de avaliação. Nós procuraremos lembrar os revisores das datas de entrega futuras e passadas. Os editores podem designar revisores adicionais ou substitutos se uma revisão estiver excessivamente atrasada. + +**A comunidade do rOpenSci é o nosso melhor patrimônio. Nosso objetivo é que as revisões sejam abertas, não contraditórias e focadas na melhoria da qualidade do software. Seja respeitoso e gentil! Consulte nosso guia de revisores e [código de conduta] (https://ropensci.org/code-of-conduct/) para obter mais informações. Você pode encontrar mais informações em nosso guia de revisores.** + +_Se você usar nossos guias/listas de verificação, etc. ao revisar um software em outra plataforma, informe aos interessados (e.g. editores de periódicos, estudantes, revisão interna de código) que aqueles vieram da rOpenSci e nos informe em nosso [fórum público] (https://discuss.ropensci.org/c/usecases) ou em [particular por e-mail] (https://ropensci.org/contact/)._ +``` + +## Voluntariando como revisor {#volunteering-as-a-reviewer} + +Obrigado pelo seu desejo de participar como revisor da revisão por pares do software rOpenSci! + +Por favor preencha nosso [formulário de voluntariado](https://ropensci.org/software-reviewer). + +Se você encontrar um envio atual que seja particularmente relevante aos seus interesses, envie um e-mail para `info@ropensci.org` incluindo o nome do pacote, o URL do problema do envio e o nome do editor designado. No entanto, lembre-se de que os convites para revisores são mantidos a critério do editor, sendo possível que o editor já tenha enviado e-mails a outras pessoas. Por favor não se voluntarie em todas as edições e por meio da interface do GitHub. + +Para outras maneiras de contribuir, consulte o [guia de contribuição do rOpenSci](https://contributing.ropensci.org/). + +## Preparando sua revisão {#preparereview} + +As revisões devem ser baseadas na versão mais recente do GitHub no _branch_ padrão, a menos que indicado de outra forma pelos autores do pacote. Todos os envios acionam um relatório detalhado sobre a estrutura e a funcionalidade do pacote, gerado por nosso [`pkgcheck` pacote](https://docs.ropensci.org/pkgcheck/). Se o pacote tiver sido alterado substancialmente desde as últimas verificações, você poderá solicitar uma nova verificação com o comando `@ropensci-review-bot check package`. Note que, ao instalar o pacote para revisá-lo, você deve se certificar de que tem todas as dependências estão disponíveis (por exemplo, execute `pak::pak()`). + +### Diretrizes gerais {#general-guidelines} + +Para revisar um pacote, comece copiando nosso [modelo de revisão](#reviewtemplate) (ou nosso [modelo de revisão em espanhol](#reviewtemplatees)) e use-o como uma lista de verificação global. Além de marcar os critérios mínimos, pedimos que você forneça comentários gerais sobre: + +- O código está em conformidade com os princípios gerais do [guia de revisão da Mozilla](https://mozillascience.github.io/codeReview/review.html)? +- O pacote está em conformidade com o [guia de pacotes da rOpenSci](#building)? +- Há melhorias que poderiam ser feitas no estilo do código? +- Há duplicação de código no pacote que deve ser reduzida? +- Há melhorias na interface do usuário que poderiam ser feitas? +- Há melhorias no desempenho que poderiam ser feitas? +- A documentação (instruções de instalação, vinhetas, exemplos, demonstrações) é clara e suficiente? E ela usa o princípio de *vários pontos de entrada*, i.e., 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 a ferramenta/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ê poderá encontrar pontos fracos e casos de uso nos quais o autor não pensou. + +Por favor, seja respeitoso e gentil com os autores 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 semanas, dependendo do prazo definido pelo editor. Entre em contato com o editor diretamente ou no _thread_ 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 do pacote em seus serviços de integração contínua (GitHub Actions, Codecov, etc.) +- Execução `devtools::check()` e `devtools::test()` no pacote para localizar quaisquer erros que possam ter passado despercebidos no sistema do autor. +- Verificar se a omissão (_skipping_) de testes é justificada (e.g. `skip_on_cran()` realiza solicitações reais de API vs. ignora todos os testes em um sistema operacional). +- Se o pacote não for enviado por meio do _branch_ padrão/principal, lembre-se de mudar para o _branch_ de revisão enviado antes de iniciar sua revisão. Nesse caso, você também deverá pesquisar o pacote localmente, pois a pesquisa no GitHub é limitada ao _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 revisores 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 problema de revisão (_review issue_): `@ropensci-review-bot check package`. + +### Interações em outros contextos {#off-thread-interactions} + +Se você interagiu com os autores do pacote e falou sobre a revisão fora do contexto da revisão (em _chats_, mensagens diretas, pessoalmente, ou por problemas [_issues_] no repositório do projeto), certifique-se de que sua revisão capture e/ou vincule elementos dessas conversas que sejam relevantes para o processo. + +### Experiência de revisores anteriores {#experience-from-past-reviewers} + +Revisores iniciantes podem achar útil ler (sobre) algumas revisões anteriores. Em geral, você pode encontrar tópicos de envio de pacotes integrados [aqui](https://github.com/ropensci/software-review/issues?q=is%3Aissue+is%3Aclosed+label%3A6%2Fapproved). Aqui estão alguns exemplos escolhidos de revisões (observe que suas revisões não precisam ser tão longas quanto estes exemplos): + +- `rtika` [revisão 1](https://github.com/ropensci/software-review/issues/191#issuecomment-367166658) e [revisão2](https://github.com/ropensci/software-review/issues/191#issuecomment-368254623) + +- `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) (antes de termos um modelo de revisão) + +Você pode ler publicações de blog escritas por revisores sobre suas experiências por meio deste [link](https://ropensci.org/tags/reviewer/). Em particular, nesta [postagem do blog de Mara Averick](https://ropensci.org/blog/2017/08/22/first-package-review/) leia sobre o papel de "usuário ingênuo" que um revisor pode assumir para fornecer feedback útil, mesmo sem ser especialista no tópico ou na implementação do pacote, ao perguntar a si mesmo *"O que eu achei que essa coisa faria? Ela faz isso? Quais são as coisas que me assustam?"*. Em [outra postagem do blog](https://ropensci.org/blog/2017/09/08/first-review-experiences/), Verena Haunschmid explica como ela alternou entre usar o pacote e verificar seu código. + +Tanto como ex-revisor e autor de pacote, [Adam Sparks](https://adamhsparks.netlify.app/) [escreveu o seguinte](https://twitter.com/adamhsparks/status/898132036451303425) "\[escreva\] uma boa crítica da estrutura do pacote e das práticas recomendadas de codificação. Se você sabe como fazer algo melhor, diga-me. É fácil perder oportunidades de documentação como desenvolvedor; como revisor, você tem uma visão diferente. Você é um usuário que pode dar _feedback_. O que não está claro no pacote? Como você pode deixar isso mais claro? Se você estiver usando-o pela primeira vez, é fácil? Você conhece outro pacote de 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, ofereça." + +### Pacote de ajuda para revisores {#helper-package-for-reviewers} + +Se estiver trabalhando no RStudio, você pode otimizar seu 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`, você escreveria + +``` +remotes::install_github("ropensci-org/pkgreviewr") +library(pkgreviewr) +pkgreview_create(pkg_repo = "embruna/refnet", + review_parent = "~/Documents/workflows/rOpenSci/reviews/") +``` + +e + +- o repositório do pacote `refnet` no GitHub será clonado +- um projeto de revisão será criado, contendo um bloco de notas para você preencher e o modelo de revisão +- observe que, se o pacote não for enviado por meio da ramificação padrão/principal, você precisará mudar para a ramificação enviada antes de iniciar sua revisão + +### Comentários sobre o processo {#feedback-on-the-process} + +Incentivamos você a fazer perguntas e fornecer _feedback_ sobre o processo de revisão em nosso [fórum](https://discuss.ropensci.org). + +## Envio da revisão {#submitreview} + +- Quando sua revisão estiver concluída, cole-a como um comentário na secção de problemas do pacote (_package software-review issue_). +- Comentários adicionais são bem-vindos na mesma edição. Esperamos que as revisões de pacotes funcionem como uma conversa contínua com os autores, em vez de uma única rodada de revisões típica de manuscritos acadêmicos. +- Você também pode enviar problemas ou _pull requests_ diretamente para o repositório do pacote, se preferir, mas, se o fizer, comente sobre eles e coloque um link para eles no tópico de comentários do repositório de revisão de software para que tenhamos um registro centralizado e o texto da sua revisão. +- Inclua uma estimativa de quantas horas você gastou na revisão. + +## Acompanhamento da revisão {#followupreviewer} + +Os autores devem responder dentro de 2 semanas com alterações feitas no pacote em resposta a sua avaliação. Nesse estágio, pedimos que você responda se as alterações abordam suficientemente os problemas levantados na sua revisão. Incentivamos a discussão contínua entre autores de pacotes e revisores, e você também pode pedir aos editores que esclareçam os problemas no tópico (_thread_) de revisão. + +Você usará o [modelo de aprovação](#approval2template). + +