From 3f00cd15a5a1818ee2061dcc6ad3ed97927a2b1e Mon Sep 17 00:00:00 2001 From: Yanina Bellini Saibene Date: Thu, 17 Apr 2025 14:02:47 -0300 Subject: [PATCH 1/7] Portuguese translation --- .../2017-09-01-nsf-softwarereview/index.pt.md | 83 +++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 content/blog/2017-09-01-nsf-softwarereview/index.pt.md diff --git a/content/blog/2017-09-01-nsf-softwarereview/index.pt.md b/content/blog/2017-09-01-nsf-softwarereview/index.pt.md new file mode 100644 index 0000000000..3638ec863a --- /dev/null +++ b/content/blog/2017-09-01-nsf-softwarereview/index.pt.md @@ -0,0 +1,83 @@ +--- +slug: nf-softwarereview +title: Como a rOpenSci usa a revisão de código para promover a ciência reprodutível +crossposts: +- name: NumFOCUS blog + url: https://numfocus.org/blog/how-ropensci-uses-code-review-to-promote-reproducible-science +preface: NumFOCUS is a nonprofit that supports and promotes world-class, innovative, + open source scientific computing, including rOpenSci. +date: '2017-09-01' +author: +- Noam Ross +- Scott Chamberlain +- Karthik Ram +- Maëlle Salmon +topicid: 850 +tags: +- software +- Software Peer Review +- community +params: + doi: 10.59350/bqjqp-2be69 +--- + +Na rOpenSci, criamos e organizamos softwares para ajudar os cientistas no ciclo de vida dos dados. Essas ferramentas acessam, baixam, gerenciam e arquivam dados científicos de forma aberta e reproduzível. Logo no início, percebemos que isso só poderia ser um esforço da comunidade. A variedade de dados científicos e fluxos de trabalho só poderia ser resolvida com a contribuição de cientistas com conhecimentos específicos da área. + +Com a abordagem da comunidade, surgiram desafios. **Como poderíamos garantir a qualidade do código escrito por cientistas sem treinamento formal em práticas de desenvolvimento de software? Como poderíamos promover a adoção de práticas recomendadas entre nossos colaboradores? Como poderíamos criar uma comunidade que apoiaria uns aos outros nesse trabalho?** + +**Tivemos muito sucesso ao lidar com esses desafios por meio do *revisão por pares*.** Extraímos elementos de um processo que é familiar à nossa comunidade-alvo. *avaliação acadêmica por pares* - e uma prática do mundo do desenvolvimento de software - o *revisão do código de produção* - para criar um sistema que promova a qualidade do software, a educação contínua e o desenvolvimento da comunidade. + +## Um processo de revisão aberto + +**Revisão de software de produção** ocorre em equipes de desenvolvimento de software, de código aberto ou não. As contribuições para um projeto de software são revisadas por um ou mais membros da equipe antes de serem incorporadas ao código-fonte do projeto. Normalmente, as contribuições são pequenos patches, e a revisão serve como uma verificação da qualidade, bem como uma oportunidade de treinamento nos padrões da equipe. + +**Na revisão por pares acadêmica** os avaliadores externos criticam um produto completo, geralmente um manuscrito, com um mandato muito amplo para abordar quaisquer áreas que considerem deficientes. A revisão acadêmica geralmente é anônima e, ao passar por ela, o produto e o autor recebem uma marca pública de validação. + +**Nós combinamos essas abordagens.** Em nosso processo, os autores enviam pacotes completos do R para a rOpenSci. Os editores verificam se os pacotes se enquadram no escopo do nosso projeto, executam uma série de testes automatizados para garantir uma linha de base de qualidade e integridade do código e, em seguida, designam dois revisores independentes. Os revisores fazem comentários sobre a usabilidade, a qualidade e o estilo do código do software, bem como sobre a documentação. Os autores fazem alterações em resposta e, quando os revisores estiverem satisfeitos com as atualizações, o pacote recebe um selo de aprovação e passa a fazer parte do nosso pacote. + +Esse processo é bastante iterativo. Depois que os revisores publicam uma primeira rodada de revisões extensas, os autores e revisores conversam em um bate-papo informal, moderado apenas levemente por um editor. Isso permite que tanto os revisores quanto os autores façam perguntas uns aos outros e expliquem as diferenças de opinião. Isso pode ocorrer em um ritmo muito mais rápido do que a correspondência típica de revisão acadêmica. Usamos o sistema de problemas do GitHub para essa conversa, e as respostas levam de minutos a dias, em vez de semanas a meses. + +**A troca também é aberta e pública**. Autores, revisores e editores conhecem as identidades uns dos outros. A comunidade mais ampla pode ver ou até mesmo participar da conversa enquanto ela acontece. Isso incentiva você a ser minucioso e a fazer revisões construtivas e não contraditórias. Tanto os autores quanto os revisores relatam que gostam e aprendem mais com essa troca aberta e direta. Isso também traz o benefício de criar uma comunidade. Os participantes têm a oportunidade de se relacionar de forma significativa com novos colegas, e novas colaborações surgiram por meio de ideias geradas durante o processo de revisão. + +Estamos cientes de que os sistemas abertos podem ter desvantagens. Por exemplo, na revisão acadêmica tradicional, a revisão por pares duplamente cega [pode aumentar a representação de autores do sexo feminino](https://www.sciencedirect.com/science/article/pii/S0169534707002704) sugerindo preconceito em revisões não cegas. Também é possível que os revisores sejam menos críticos na revisão aberta. No entanto, afirmamos que a abertura da conversa sobre a revisão fornece uma verificação da qualidade e da parcialidade da revisão; é mais difícil injetar comentários subjetivos ou sem embasamento em público e sem a cobertura do anonimato. Em última análise, acreditamos que a capacidade dos autores e revisores de se comunicarem direta e publicamente melhora a qualidade e a imparcialidade. + +## Orientação e padrões + +**O rOpenSci fornece orientação sobre a revisão.** Isso se divide em duas categorias principais: **práticas recomendadas de alto nível** e **padrões de baixo nível**. As práticas recomendadas de alto nível são gerais e amplamente aplicáveis a todas as linguagens e aplicativos. São práticas como "Escreva funções reutilizáveis em vez de repetir o mesmo código", "Teste casos extremos" ou "Escreva documentação para todas as suas funções". Devido à sua natureza geral, elas podem ser extraídas de outras fontes e não desenvolvidas do zero. Nossas práticas recomendadas são baseadas em orientações originalmente desenvolvidas por [Laboratório de Ciências da Mozilla](https://mozillascience.github.io/codeReview/intro.html). + +Os padrões de baixo nível são específicos para uma linguagem (no nosso caso, R), aplicativos (interfaces de dados) e base de usuários (pesquisadores). Eles incluem itens específicos, como convenções de nomenclatura para funções, melhores escolhas de dependências para determinadas tarefas e adesão a um guia de estilo de código. Temos um conjunto extenso de padrões para nossos revisores verificarem. Eles mudam com o tempo, à medida que o ecossistema do software R evolui, as práticas recomendadas mudam e as ferramentas e os recursos educacionais disponibilizam novos métodos para os desenvolvedores. + +**Nossos padrões também mudam com base no feedback dos revisores.** Adotamos em nossos padrões sugestões que surgem de vários revisores em diferentes pacotes. Descobrimos que muitas delas têm a ver com a facilidade de uso e a consistência das APIs de software e com o tipo e o local das informações na documentação que facilitam a localização. Isso destaca uma das vantagens dos revisores externos: eles podem oferecer uma nova perspectiva sobre a usabilidade, além de testar o software em casos de uso diferentes dos imaginados pelo autor. + +**À medida que nossos padrões se tornaram mais abrangentes, passamos a confiar mais em ferramentas automatizadas.** O ecossistema do R, como a maioria das linguagens, tem um conjunto de ferramentas para code linting, teste de função, análise de código estático e integração contínua. Exigimos que os autores as utilizem, e os editores executam os envios por meio de um conjunto de testes antes de enviá-los para revisão. Isso libera os revisores do fardo das tarefas de baixo nível para que se concentrem nas críticas de alto nível, onde podem agregar mais valor. + +## A comunidade de revisores + +Um dos principais desafios e recompensas de nosso trabalho tem sido o desenvolvimento de uma comunidade de revisores. + +**A revisão é uma atividade de alta habilidade.** Os revisores precisam ter conhecimento dos métodos de programação usados em um pacote de software e também do campo científico de sua aplicação. ("Encontre-me alguém que conheça ecologia sensorial e estruturas de dados esparsas!") Eles precisam de boas habilidades de comunicação e de tempo e disposição para se voluntariar. Felizmente, os mundos da ciência aberta e do código aberto estão repletos de pessoas generosas e especializadas. Conseguimos expandir nosso grupo de revisores à medida que o ritmo dos envios e os domínios de suas aplicações aumentaram. + +O desenvolvimento do grupo de revisores exige recrutamento constante. Nossos editores se envolvem de forma ativa e ampla com as comunidades de desenvolvedores e pesquisadores para encontrar novos revisores. Recrutamos autores de envios anteriores, colegas de trabalho e colegas, em conferências, por meio de outros trabalhos colaborativos e nas mídias sociais. No ecossistema de software de código aberto, muitas vezes é possível identificar pessoas com conhecimentos específicos observando seus softwares publicados ou sua contribuição para outros projetos, e muitas vezes enviamos e-mails frios para possíveis revisores cujo trabalho publicado sugere que eles seriam uma boa opção para um envio. + +Cultivamos nosso grupo de revisores e também o expandimos. Trazemos revisores de volta para que eles possam desenvolver a revisão como uma habilidade, mas não com tanta frequência a ponto de sobrecarregá-los. Fornecemos orientação e feedback aos novos recrutas. Ao designar revisores para uma submissão, nosso objetivo é juntar revisores experientes com novos revisores, ou revisores com experiência nos métodos de programação de um pacote com aqueles experientes em seu campo de aplicação. **Esses revisores aprendem uns com os outros, e a diversidade de perspectivas é uma vantagem** Os desenvolvedores menos experientes geralmente fornecem insights que os mais experientes não têm sobre a usabilidade do software, o design da API e a documentação. Os desenvolvedores mais experientes identificarão com mais frequência ineficiências no código, armadilhas devido a casos extremos ou sugerirão abordagens de implementação alternativas. + +## Expansão da revisão por pares para código + +A revisão de código tem sido uma das melhores iniciativas da rOpenSci. Criamos software, desenvolvemos habilidades e criamos comunidade, e o processo de revisão por pares tem sido um importante catalisador para todos os três. Ele tornou o software que desenvolvemos internamente e o que aceitamos de colaboradores externos mais confiável, utilizável e passível de manutenção. Assim **estamos trabalhando para promover a revisão por pares aberta do código por mais organizações** que trabalham com software científico. Ajudamos a lançar o [O Journal of Open Source Software](https://joss.theoj.org/) que usa uma versão do nosso processo de revisão para oferecer um local de publicação favorável ao desenvolvedor. O sucesso do JOSS levou a um spin-off, o [Journal of Open Source Education (Jornal de Educação de Código Aberto)](https://jose.theoj.org/) que usa um processo aberto, semelhante à revisão de código, para fornecer feedback sobre currículos e materiais educacionais. Também estamos desenvolvendo um programa piloto em que os artigos de software enviados a uma revista acadêmica parceira recebem um selo por passarem pela revisão do rOpenSci. Somos incentivados por outras iniciativas de revisão, como [ReScience](https://rescience.github.io/) e [O historiador da programação](https://programminghistorian.org/). [BioConductor](https://www.bioconductor.org/) que antecedeu a nossa em vários anos, recentemente mudou para um modelo aberto. + +**Se a sua organização estiver desenvolvendo ou fazendo a curadoria de códigos científicos, você pode usar o modelo** acreditamos que a revisão de código, bem implementada, pode ser um grande benefício. Você pode precisar de um esforço considerável para começar, mas **aqui estão algumas das principais lições que aprendemos e que podem ajudar você:** + +- **Desenvolver padrões e diretrizes** Para que seus autores e revisores usem. Pegue-os emprestados livremente de outros projetos (sinta-se à vontade para usar os nossos) e modifique-os iterativamente à medida que você avança. +- **Use ferramentas automatizadas** como code linters, conjuntos de testes e medidas de cobertura de testes para reduzir ao máximo a carga dos autores, revisores e editores. +- **Tenha um escopo claro.** Explique a vocês mesmos e aos possíveis colaboradores o que o projeto aceitará e por quê. Isso evitará muita confusão e esforço no futuro. +- **Crie uma comunidade** por meio de incentivos de networking, oportunidades de aprendizado e gentileza. + +**A rOpenSci está ansiosa para trabalhar com outros grupos interessados em desenvolver processos de revisão semelhantes** O rOpenSci é um grupo de trabalho que tem como objetivo trabalhar com outros grupos interessados em desenvolver processos de revisão semelhantes, especialmente se você estiver interessado em revisar e curar software científico em linguagens diferentes do R ou além do nosso escopo de suporte ao ciclo de vida dos dados. O software que implementa algoritmos estatísticos, por exemplo, é uma área propícia para a revisão aberta de código por pares. Por favor [entre em contato conosco](/contact/) se você tiver dúvidas ou quiser co-pilotar um sistema de revisão para o seu projeto. + +E, é claro, se você quiser fazer revisões, estamos sempre procurando voluntários. Inscreva-se em /onboarding. + +*** + +Você pode apoiar a rOpenSci [tornando-se um membro do NumFOCUS](https://www.numfocus.org/community/donate/) ou fazendo uma doação de [doação para o projeto](https://www.numfocus.org/open-source-projects/). + + From 47167f1fcbc106e3d9bf670a41a58100366eef5a Mon Sep 17 00:00:00 2001 From: Yanina Bellini Saibene Date: Thu, 17 Apr 2025 14:19:58 -0300 Subject: [PATCH 2/7] =?UTF-8?q?Desafios=20e=20solu=C3=A7=C3=B5es=20editori?= =?UTF-8?q?ais=20na=20revis=C3=A3o=20por=20pares=20de=20software?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../index.pt.md | 97 +++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md diff --git a/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md b/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md new file mode 100644 index 0000000000..3a282522d5 --- /dev/null +++ b/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md @@ -0,0 +1,97 @@ +--- +title: Desafios e soluções editoriais na revisão por pares de software +author: +- Maëlle Salmon +- Noam Ross +date: '2022-04-19T00:00:02-07:00' +slug: software-review-editorial-challenges +tags: +- Software Peer Review +- editors +package_version: 0.1.0 +description: Os desafios encontrados pelos editores e as medidas que tomamos para + tentar aliviar esses problemas. +featured: true +params: + doi: 10.59350/yttbb-78v90 +--- + +rOpenSci [Revisão por pares de software](/software-review/) e [Revisão por pares de software estatístico](/software-review/) dependem do trabalho voluntário de revisores e editores. +Os editores gerenciam o fluxo diário de envios, recrutam revisores e orientam o processo de revisão por pares do início ao fim. (Sua função, como grande parte do nosso processo, é [codificada no Guia do desenvolvedor do rOpenSci](https://devguide.ropensci.org/editorguide.html)). Embora muitos membros da nossa comunidade tenham participado do processo de revisão por pares, apenas alguns se envolveram como editores e editores convidados. Aqui, pensamos em esclarecer alguns dos desafios que nossos editores enfrentam e algumas das soluções que encontramos ao longo dos anos, para tornar essa parte do nosso trabalho mais transparente. + +## Decisões de escopo + +Depois que um pacote é enviado, antes de receber um editor e revisores, o Editor-chefe rotativo deve avaliar se ele é *no escopo* para o processo de revisão. Tradicionalmente, o editor-chefe rotativo da rOpenSci [escopo](https://devguide.ropensci.org/policies.html#aims-and-scope) tem se concentrado em pacotes que gerenciam o ciclo de vida dos dados de pesquisa. Isso serve para que os pacotes do rOpenSci formem um conjunto coerente de ferramentas e também para nos limitar a pacotes que nossos editores e revisores possam analisar com padrões e conhecimentos relevantes. + +As decisões sobre o escopo podem ser complicadas e, embora não haja como contornar essa complexidade, descobrimos que ficou mais fácil ao refinar o [descrições de escopo](https://devguide.ropensci.org/policies.html#aims-and-scope) ao longo do tempo, pois temos mais casos extremos. +Melhores frases e exemplos também ajudam os autores a avaliar o possível escopo de seus pacotes antes de enviá-los. Agora que nosso escopo é [está se expandindo para incluir pacotes estatísticos](https://stats-devguide.ropensci.org/overview.html#overview-categories) esperamos continuar a refinar essas categorias nos próximos meses e anos. + +Quando o escopo de um pacote é ambíguo, o Editor-chefe conduz uma discussão no canal editorial do Slack com outros editores para chegar a um consenso. +Nessas discussões, reconhecemos que alguns de nós podem ter mais experiência em alguns tópicos e, às vezes, até consultamos especialistas externos à diretoria para obter mais insights. + +Observe que incentivamos os autores de pacotes a enviar um *consulta pré-submissão* antes de um envio completo, para esclarecer qualquer dúvida sobre o escopo. + +## Recrutamento e substituição de revisores + +A revisão de um pacote toma um tempo precioso das agendas ocupadas dos revisores. +Esperamos que a experiência seja valiosa para os avaliadores (e tentamos facilitar a tarefa com nosso [guia do revisor](https://devguide.ropensci.org/reviewerguide.html)), mas consideramos que é uma tarefa e tanto, que exige aproximadamente o mesmo tempo que a revisão de um artigo científico. +Para aumentar a dificuldade de encontrar revisores disponíveis, temos uma lista de [critérios para a escolha de revisores](https://devguide.ropensci.org/editorguide.html#criteria-for-choosing-a-reviewer) para garantir a diversidade (tanto em termos de habilidades quanto de formação) e para formar continuamente um grupo de revisores experientes sem sobrecarregar nenhum deles. + +No ano passado, lançamos um [novo formulário de voluntariado para revisores](/blog/2021/11/18/devguide-0.7.0/#a-new-form-for-volunteer-reviewing) que nos permite coletar dados mais refinados sobre conhecimentos técnicos e tópicos, bem como uma pergunta opcional: "Você se considera parte de um grupo sub-representado nas áreas de ciência de dados, programação ou em seu campo principal de trabalho? +Mantemos essas informações em um banco de dados (gerenciado pelo Airtable), juntamente com o histórico de avaliações de cada revisor. Esse banco de dados é um recurso para os editores, pois eles procuram revisores com conhecimentos específicos, experiência ou disponibilidade. + +Quando isso não for suficiente, por exemplo, após repetidas recusas ou não respostas de possíveis avaliadores, os editores podem solicitar recomendações de outros editores em nosso canal do Slack. (Alguns de nós somos editores de revistas científicas tradicionais e gostaríamos de ter um bate-papo tão útil com nossos coeditores lá!) + +Um desafio ao entrar em contato com os avaliadores é saber quando você deve seguir em frente depois de esperar por uma resposta. Por isso, acrescentamos a frase "Se eu não receber uma resposta sua dentro de uma semana, presumirei que você não pode fazer uma revisão no momento" ao nosso [modelo padrão de solicitação de revisão](https://devguide.ropensci.org/reviewrequesttemplate.html). Com isso, todos ficam na mesma página e você esclarece tanto os editores quanto os possíveis avaliadores. + +Por fim, quando um revisor sai do processo de revisão (ou não pode mais ser contatado), +o editor responsável pelo tratamento recruta um substituto, geralmente uma pessoa a quem ele pode pedir uma resposta rápida (digamos, outro editor!), ou o editor atua como um segundo revisor. +O objetivo é não atrasar muito o processo de revisão. + +## Desistência de autores + +É uma situação ainda mais triste quando o pacote *autores* param de responder, pois o processo de revisão precisa ser interrompido. +É especialmente decepcionante quando isso acontece depois que as revisões já foram feitas, pois os revisores podem sentir que seu trabalho foi desperdiçado. +No final, não há nada que possamos fazer a respeito, pois isso está fora do controle de nossos editores e revisores (e dos autores). + +No entanto, para evitar problemas simples com comunicações perdidas, recomendamos que os autores se certifiquem de que recebem notificações do GitHub, pois tentamos manter a comunicação transparente por meio do GitHub e geralmente não usamos e-mail. +Para lidar com problemas maiores relacionados a tempo e comprometimento, recentemente adicionamos frases à (versão de desenvolvimento de) [guia do autor](https://devdevguide.netlify.app/authors-guide.html) e aos modelos de envio: "Espero manter este pacote por pelo menos dois anos ou encontrar um substituto." +Isso deve fazer com que os autores de pacotes pensem na manutenção do pacote a longo prazo. +Embora isso não evite todos os problemas, esperamos que os autores de pacotes pensem na manutenção do pacote a longo prazo antes de enviar seus pacotes para revisão. + +Também entendemos que, embora os autores possam ter boas intenções, a vida pode se transformar inesperadamente. +Portanto, outro esforço que fazemos é suspender as revisões (aplicando rótulos de suspensão) conforme necessário. +Essas retenções são revisadas a cada três meses, até um ano. + +## Sobrecarga de trabalho dos editores (e revisores) + +A revisão de software exige trabalho de todos: editores, revisores e, obviamente, autores. + +Para reduzir o trabalho editorial em particular, aprimoramos a automação, que foi o tópico de uma chamada da comunidade, ["Aprimorando a revisão por pares de software com a automação do GitHub"](/commcalls/dec2021-automation/). +A rOpenSci trabalhou com o The Journal of Open Source Software para estender a abordagem do JOSS de publicação orientada por chatops para um novo chat-bot do GitHub que gerencia nosso processo editorial: atribuição de tarefas, marcação de problemas, execução de testes em envios de software, retorno de relatórios para revisores e editores e registro de revisões em um banco de dados externo (Airtable). Tudo isso no conforto de um comentário de problema do GitHub! +Por exemplo, você poderia clonar um repositório localmente, instalar dependências, executar verificações e publicar manualmente os resultados... **ou** você poderia simplesmente digitar o seguinte em um comentário de problema do GitHub: + +``` +@ropensci-review-bot check package +``` + +Da mesma forma, você pode usar o seguinte para registrar um revisor nos metadados do problema de envio, bem como em nosso banco de dados Airtable. + +``` +@ropensci-review-bot add @maelle to reviewers +``` + +Uma grande parte da limitação da carga de trabalho dos editores é ter editores suficientes! Nós temos [expandindo nossa equipe editorial](/tags/editors/) com o objetivo de esperar que os editores lidem apenas com [cerca de 4 envios por ano](https://devdevguide.netlify.app/editorguide.html#editors-responsabilities). +À medida que o volume de envios aumenta e os editores saem (pedimos compromissos de dois anos com opção de renovação), recrutamos novos editores, em grande parte a partir do nosso grupo de revisores. +Convidamos revisores experientes para editar como convidados e perguntamos se eles querem continuar se tudo der certo. +Nosso [guia do editor](https://devguide.ropensci.org/editorguide.html) facilita a integração... e a integração de novos editores leva a comentários e, portanto, a melhorias nesse guia. +Se você quiser tentar editar [comece sendo voluntário como revisor](/software-reviewer)! + +## Conclusão + +Resumimos aqui alguns problemas comuns de nossos conselhos editoriais. +Descobrimos que é muito importante automatizar os processos, mas também que os editores possam se comunicar diretamente uns com os outros para encontrar soluções, bem como para se solidarizar e incentivar uns aos outros. +À medida que a revisão de software continuar, certamente encontraremos novos desafios a serem enfrentados. +Esperamos que nossas experiências sejam úteis para outros editores e que possam ajudar a informar outros conselhos editoriais. + + From 965c7ed88b04efac5813faade49ae69ea56df660 Mon Sep 17 00:00:00 2001 From: Yanina Bellini Saibene Date: Thu, 17 Apr 2025 20:28:39 -0300 Subject: [PATCH 3/7] Update content/blog/2017-09-01-nsf-softwarereview/index.pt.md --- content/blog/2017-09-01-nsf-softwarereview/index.pt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/blog/2017-09-01-nsf-softwarereview/index.pt.md b/content/blog/2017-09-01-nsf-softwarereview/index.pt.md index 3638ec863a..6ee80484c1 100644 --- a/content/blog/2017-09-01-nsf-softwarereview/index.pt.md +++ b/content/blog/2017-09-01-nsf-softwarereview/index.pt.md @@ -18,7 +18,7 @@ tags: - Software Peer Review - community params: - doi: 10.59350/bqjqp-2be69 + doi: 10.59350/4y3kj-1re56 --- Na rOpenSci, criamos e organizamos softwares para ajudar os cientistas no ciclo de vida dos dados. Essas ferramentas acessam, baixam, gerenciam e arquivam dados científicos de forma aberta e reproduzível. Logo no início, percebemos que isso só poderia ser um esforço da comunidade. A variedade de dados científicos e fluxos de trabalho só poderia ser resolvida com a contribuição de cientistas com conhecimentos específicos da área. From 580e09e84069fb707b13012c6ba80a5c4f8fef6f Mon Sep 17 00:00:00 2001 From: Yanina Bellini Saibene Date: Thu, 17 Apr 2025 20:29:27 -0300 Subject: [PATCH 4/7] Update content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md --- .../2022-04-19-software-review-editorial-challenges/index.pt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md b/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md index 3a282522d5..df35b0c6b2 100644 --- a/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md +++ b/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md @@ -13,7 +13,7 @@ description: Os desafios encontrados pelos editores e as medidas que tomamos par tentar aliviar esses problemas. featured: true params: - doi: 10.59350/yttbb-78v90 + doi: 10.59350/tfy8g-0e676 --- rOpenSci [Revisão por pares de software](/software-review/) e [Revisão por pares de software estatístico](/software-review/) dependem do trabalho voluntário de revisores e editores. From 782740e6f0a77e05e8f4054ae05005a457b63b5e Mon Sep 17 00:00:00 2001 From: Yanina Bellini Saibene Date: Thu, 19 Jun 2025 11:23:04 -0300 Subject: [PATCH 5/7] Apply suggestions from code review Co-authored-by: Francesca Palmeira --- .../2017-09-01-nsf-softwarereview/index.pt.md | 46 ++++++------ .../index.pt.md | 74 +++++++++---------- 2 files changed, 60 insertions(+), 60 deletions(-) diff --git a/content/blog/2017-09-01-nsf-softwarereview/index.pt.md b/content/blog/2017-09-01-nsf-softwarereview/index.pt.md index 6ee80484c1..bbb18cd06f 100644 --- a/content/blog/2017-09-01-nsf-softwarereview/index.pt.md +++ b/content/blog/2017-09-01-nsf-softwarereview/index.pt.md @@ -21,63 +21,63 @@ params: doi: 10.59350/4y3kj-1re56 --- -Na rOpenSci, criamos e organizamos softwares para ajudar os cientistas no ciclo de vida dos dados. Essas ferramentas acessam, baixam, gerenciam e arquivam dados científicos de forma aberta e reproduzível. Logo no início, percebemos que isso só poderia ser um esforço da comunidade. A variedade de dados científicos e fluxos de trabalho só poderia ser resolvida com a contribuição de cientistas com conhecimentos específicos da área. +Na rOpenSci, criamos e organizamos softwares para ajudar os(as) cientistas no ciclo de vida dos dados. Essas ferramentas acessam, baixam, gerenciam e arquivam dados científicos de forma aberta e reprodutível. Logo no início, percebemos que isso só poderia ser um esforço da comunidade. A variedade de dados científicos e fluxos de trabalho só poderia ser resolvida com a contribuição de cientistas com conhecimentos específicos da área. -Com a abordagem da comunidade, surgiram desafios. **Como poderíamos garantir a qualidade do código escrito por cientistas sem treinamento formal em práticas de desenvolvimento de software? Como poderíamos promover a adoção de práticas recomendadas entre nossos colaboradores? Como poderíamos criar uma comunidade que apoiaria uns aos outros nesse trabalho?** +Com a abordagem da comunidade, surgiram desafios. **Como poderíamos garantir a qualidade do código escrito por cientistas sem treinamento formal em práticas de desenvolvimento de software? Como poderíamos promover a adoção de práticas recomendadas entre nossos(as) colaboradores(as)? Como poderíamos criar uma comunidade com pessoas que apoiariam umas as outras nesse trabalho?** -**Tivemos muito sucesso ao lidar com esses desafios por meio do *revisão por pares*.** Extraímos elementos de um processo que é familiar à nossa comunidade-alvo. *avaliação acadêmica por pares* - e uma prática do mundo do desenvolvimento de software - o *revisão do código de produção* - para criar um sistema que promova a qualidade do software, a educação contínua e o desenvolvimento da comunidade. +**Tivemos muito sucesso ao lidar com esses desafios por meio da *revisão por pares*.** Extraímos elementos de um processo familiar à nossa comunidade-alvo - a *avaliação acadêmica por pares* - e uma prática do mundo do desenvolvimento de software - a *revisão do código de produção* - para criar um sistema que promova a qualidade do software, a educação contínua e o desenvolvimento da comunidade. ## Um processo de revisão aberto **Revisão de software de produção** ocorre em equipes de desenvolvimento de software, de código aberto ou não. As contribuições para um projeto de software são revisadas por um ou mais membros da equipe antes de serem incorporadas ao código-fonte do projeto. Normalmente, as contribuições são pequenos patches, e a revisão serve como uma verificação da qualidade, bem como uma oportunidade de treinamento nos padrões da equipe. -**Na revisão por pares acadêmica** os avaliadores externos criticam um produto completo, geralmente um manuscrito, com um mandato muito amplo para abordar quaisquer áreas que considerem deficientes. A revisão acadêmica geralmente é anônima e, ao passar por ela, o produto e o autor recebem uma marca pública de validação. +**Na revisão acadêmica por pares** as pessoas avaliadoras externas criticam um produto completo, geralmente um manuscrito, com um mandato muito amplo para abordar quaisquer áreas que considerem deficientes. A revisão acadêmica geralmente é anônima e, ao passar por ela, o produto e o(a) autor(a) recebem uma marca pública de validação. -**Nós combinamos essas abordagens.** Em nosso processo, os autores enviam pacotes completos do R para a rOpenSci. Os editores verificam se os pacotes se enquadram no escopo do nosso projeto, executam uma série de testes automatizados para garantir uma linha de base de qualidade e integridade do código e, em seguida, designam dois revisores independentes. Os revisores fazem comentários sobre a usabilidade, a qualidade e o estilo do código do software, bem como sobre a documentação. Os autores fazem alterações em resposta e, quando os revisores estiverem satisfeitos com as atualizações, o pacote recebe um selo de aprovação e passa a fazer parte do nosso pacote. +**Nós combinamos essas abordagens.** Em nosso processo, as pessoas autoras enviam pacotes completos do R para a rOpenSci. Os(As) editores(as) verificam se os pacotes se enquadram no escopo do nosso projeto, executam uma série de testes automatizados para garantir uma linha de base de qualidade e integridade do código e, em seguida, designam duas pessoas revisoras independentes. Os(As) revisores(as) fazem comentários sobre a usabilidade, a qualidade e o estilo do código do software, bem como sobre a documentação. Os(As) autores(as) fazem alterações em resposta e, quando os(as) revisores(as) estiverem satisfeitos com as atualizações, o pacote recebe um selo de aprovação e passa a fazer parte do nosso pacote. -Esse processo é bastante iterativo. Depois que os revisores publicam uma primeira rodada de revisões extensas, os autores e revisores conversam em um bate-papo informal, moderado apenas levemente por um editor. Isso permite que tanto os revisores quanto os autores façam perguntas uns aos outros e expliquem as diferenças de opinião. Isso pode ocorrer em um ritmo muito mais rápido do que a correspondência típica de revisão acadêmica. Usamos o sistema de problemas do GitHub para essa conversa, e as respostas levam de minutos a dias, em vez de semanas a meses. +Esse processo é bastante iterativo. Depois que os(as) revisores(as) publicam uma primeira rodada de revisões extensas, os(as) autores(as) e revisores(as) conversam em um bate-papo informal, moderado apenas levemente por um(a) editor(a). Isso permite que tanto as pessoas revisoras quanto as autoras façam perguntas umas as outras e expliquem as diferenças de opinião. Isso pode ocorrer em um ritmo muito mais rápido do que a correspondência típica de revisão acadêmica. Usamos o sistema de problemas do GitHub para essa conversa, e as respostas levam de minutos a dias, em vez de semanas a meses. -**A troca também é aberta e pública**. Autores, revisores e editores conhecem as identidades uns dos outros. A comunidade mais ampla pode ver ou até mesmo participar da conversa enquanto ela acontece. Isso incentiva você a ser minucioso e a fazer revisões construtivas e não contraditórias. Tanto os autores quanto os revisores relatam que gostam e aprendem mais com essa troca aberta e direta. Isso também traz o benefício de criar uma comunidade. Os participantes têm a oportunidade de se relacionar de forma significativa com novos colegas, e novas colaborações surgiram por meio de ideias geradas durante o processo de revisão. +**A troca também é aberta e pública**. Pessoas autoras, revisoras e editoras conhecem as identidades umas das outras. A comunidade mais ampla pode ver ou até mesmo participar da conversa enquanto ela acontece. Isso incentiva você a ser minucioso e a fazer revisões construtivas e não contraditórias. Tanto as pessoas autoras quanto as revisoras relatam que gostam e aprendem mais com essa troca aberta e direta. Isso também traz o benefício de criar uma comunidade. As pessoas participantes têm a oportunidade de se relacionar de forma significativa com novos(as) colegas, e novas colaborações surgiram por meio de ideias geradas durante o processo de revisão. -Estamos cientes de que os sistemas abertos podem ter desvantagens. Por exemplo, na revisão acadêmica tradicional, a revisão por pares duplamente cega [pode aumentar a representação de autores do sexo feminino](https://www.sciencedirect.com/science/article/pii/S0169534707002704) sugerindo preconceito em revisões não cegas. Também é possível que os revisores sejam menos críticos na revisão aberta. No entanto, afirmamos que a abertura da conversa sobre a revisão fornece uma verificação da qualidade e da parcialidade da revisão; é mais difícil injetar comentários subjetivos ou sem embasamento em público e sem a cobertura do anonimato. Em última análise, acreditamos que a capacidade dos autores e revisores de se comunicarem direta e publicamente melhora a qualidade e a imparcialidade. +Estamos cientes de que os sistemas abertos podem ter desvantagens. Por exemplo, na revisão acadêmica tradicional, a revisão por pares duplamente cega [pode aumentar a representação de autoras do sexo feminino](https://www.sciencedirect.com/science/article/pii/S0169534707002704) sugerindo preconceito em revisões não cegas. Também é possível que as pessoas revisoras sejam menos críticas na revisão aberta. No entanto, afirmamos que a abertura da conversa sobre a revisão fornece uma verificação da qualidade e da parcialidade da revisão; é mais difícil injetar comentários subjetivos ou sem embasamento em público e sem a cobertura do anonimato. Em última análise, acreditamos que a capacidade das pessoas autoras e revisoras de se comunicarem direta e publicamente melhora a qualidade e a imparcialidade. ## Orientação e padrões -**O rOpenSci fornece orientação sobre a revisão.** Isso se divide em duas categorias principais: **práticas recomendadas de alto nível** e **padrões de baixo nível**. As práticas recomendadas de alto nível são gerais e amplamente aplicáveis a todas as linguagens e aplicativos. São práticas como "Escreva funções reutilizáveis em vez de repetir o mesmo código", "Teste casos extremos" ou "Escreva documentação para todas as suas funções". Devido à sua natureza geral, elas podem ser extraídas de outras fontes e não desenvolvidas do zero. Nossas práticas recomendadas são baseadas em orientações originalmente desenvolvidas por [Laboratório de Ciências da Mozilla](https://mozillascience.github.io/codeReview/intro.html). +**A rOpenSci fornece orientação sobre a revisão.** Isso se divide em duas categorias principais: **práticas recomendadas de alto nível** e **padrões de baixo nível**. As práticas recomendadas de alto nível são gerais e amplamente aplicáveis a todas as linguagens e aplicativos. São práticas como "Escreva funções reutilizáveis em vez de repetir o mesmo código", "Teste casos extremos" ou "Escreva documentação para todas as suas funções". Devido à sua natureza geral, elas podem ser extraídas de outras fontes e não desenvolvidas do zero. Nossas práticas recomendadas são baseadas em orientações originalmente desenvolvidas pelo [Laboratório de Ciências da Mozilla](https://mozillascience.github.io/codeReview/intro.html). -Os padrões de baixo nível são específicos para uma linguagem (no nosso caso, R), aplicativos (interfaces de dados) e base de usuários (pesquisadores). Eles incluem itens específicos, como convenções de nomenclatura para funções, melhores escolhas de dependências para determinadas tarefas e adesão a um guia de estilo de código. Temos um conjunto extenso de padrões para nossos revisores verificarem. Eles mudam com o tempo, à medida que o ecossistema do software R evolui, as práticas recomendadas mudam e as ferramentas e os recursos educacionais disponibilizam novos métodos para os desenvolvedores. +Os padrões de baixo nível são específicos para uma linguagem (no nosso caso, R), aplicativos (interfaces de dados) e base de usuários(as) (pesquisadores). Eles incluem itens específicos, como convenções de nomenclatura para funções, melhores escolhas de dependências para determinadas tarefas e adesão a um guia de estilo de código. Temos um conjunto extenso de padrões para nossos(as) revisores(as) verificarem. Eles mudam com o tempo, à medida que o ecossistema do software R evolui, as práticas recomendadas mudam e as ferramentas e os recursos educacionais disponibilizam novos métodos para as pessoas desenvolvedoras. -**Nossos padrões também mudam com base no feedback dos revisores.** Adotamos em nossos padrões sugestões que surgem de vários revisores em diferentes pacotes. Descobrimos que muitas delas têm a ver com a facilidade de uso e a consistência das APIs de software e com o tipo e o local das informações na documentação que facilitam a localização. Isso destaca uma das vantagens dos revisores externos: eles podem oferecer uma nova perspectiva sobre a usabilidade, além de testar o software em casos de uso diferentes dos imaginados pelo autor. +**Nossos padrões também mudam com base no feedback dos(as) revisores(as).** Adotamos em nossos padrões sugestões que surgem de várias pessoas revisoras em diferentes pacotes. Descobrimos que muitas delas têm a ver com a facilidade de uso e a consistência das APIs de software e com o tipo e o local das informações na documentação que facilitam a localização. Isso destaca uma das vantagens de pessoas revisoras externas: elas podem oferecer uma nova perspectiva sobre a usabilidade, além de testar o software em casos de uso diferentes dos imaginados pelo(a) autor(a). -**À medida que nossos padrões se tornaram mais abrangentes, passamos a confiar mais em ferramentas automatizadas.** O ecossistema do R, como a maioria das linguagens, tem um conjunto de ferramentas para code linting, teste de função, análise de código estático e integração contínua. Exigimos que os autores as utilizem, e os editores executam os envios por meio de um conjunto de testes antes de enviá-los para revisão. Isso libera os revisores do fardo das tarefas de baixo nível para que se concentrem nas críticas de alto nível, onde podem agregar mais valor. +**À medida que os nossos padrões se tornaram mais abrangentes, passamos a confiar mais em ferramentas automatizadas.** O ecossistema do R, como a maioria das linguagens, tem um conjunto de ferramentas para code linting, teste de função, análise de código estático e integração contínua. Exigimos que os(as) autores(as) as utilizem, e os(as) editores(as) executam os envios por meio de um conjunto de testes antes de enviá-los para revisão. Isso libera as pessoas revisoras do fardo das tarefas de menor nível para que se concentrem nas críticas de maior nível, onde podem agregar mais valor. ## A comunidade de revisores Um dos principais desafios e recompensas de nosso trabalho tem sido o desenvolvimento de uma comunidade de revisores. -**A revisão é uma atividade de alta habilidade.** Os revisores precisam ter conhecimento dos métodos de programação usados em um pacote de software e também do campo científico de sua aplicação. ("Encontre-me alguém que conheça ecologia sensorial e estruturas de dados esparsas!") Eles precisam de boas habilidades de comunicação e de tempo e disposição para se voluntariar. Felizmente, os mundos da ciência aberta e do código aberto estão repletos de pessoas generosas e especializadas. Conseguimos expandir nosso grupo de revisores à medida que o ritmo dos envios e os domínios de suas aplicações aumentaram. +**A revisão é uma atividade de alta habilidade.** As pessoas revisoras precisam ter conhecimento dos métodos de programação usados em um pacote de software e também do campo científico de sua aplicação ("Encontre-me alguém que conheça ecologia sensorial e estruturas de dados esparsas!"). Elas precisam de boas habilidades de comunicação e de tempo e disposição para se voluntariar. Felizmente, os mundos da ciência aberta e do código aberto estão repletos de pessoas generosas e especializadas. Conseguimos expandir o nosso grupo de revisores à medida que o ritmo dos envios e os domínios de suas aplicações aumentaram. -O desenvolvimento do grupo de revisores exige recrutamento constante. Nossos editores se envolvem de forma ativa e ampla com as comunidades de desenvolvedores e pesquisadores para encontrar novos revisores. Recrutamos autores de envios anteriores, colegas de trabalho e colegas, em conferências, por meio de outros trabalhos colaborativos e nas mídias sociais. No ecossistema de software de código aberto, muitas vezes é possível identificar pessoas com conhecimentos específicos observando seus softwares publicados ou sua contribuição para outros projetos, e muitas vezes enviamos e-mails frios para possíveis revisores cujo trabalho publicado sugere que eles seriam uma boa opção para um envio. +O desenvolvimento do grupo de revisores exige recrutamento constante. Nossos(as) editores(as) se envolvem de forma ativa e ampla com as comunidades de desenvolvedores e pesquisadores para encontrar novas pessoas revisoras. Recrutamos autores de envios anteriores, colegas de trabalho e colegas, em conferências, por meio de outros trabalhos colaborativos e nas mídias sociais. No ecossistema de software de código aberto, muitas vezes é possível identificar pessoas com conhecimentos específicos observando seus softwares publicados ou sua contribuição para outros projetos, e muitas vezes enviamos e-mails sem contato prévio para possíveis revisores cujo os trabalhos publicados sugerem que essas pessoas seriam uma boa opção para um envio. -Cultivamos nosso grupo de revisores e também o expandimos. Trazemos revisores de volta para que eles possam desenvolver a revisão como uma habilidade, mas não com tanta frequência a ponto de sobrecarregá-los. Fornecemos orientação e feedback aos novos recrutas. Ao designar revisores para uma submissão, nosso objetivo é juntar revisores experientes com novos revisores, ou revisores com experiência nos métodos de programação de um pacote com aqueles experientes em seu campo de aplicação. **Esses revisores aprendem uns com os outros, e a diversidade de perspectivas é uma vantagem** Os desenvolvedores menos experientes geralmente fornecem insights que os mais experientes não têm sobre a usabilidade do software, o design da API e a documentação. Os desenvolvedores mais experientes identificarão com mais frequência ineficiências no código, armadilhas devido a casos extremos ou sugerirão abordagens de implementação alternativas. +Cultivamos nosso grupo de revisores e também o expandimos. Trazemos pessoas revisoras de volta para que elas possam desenvolver a revisão como habilidade, mas não com tanta frequência a ponto de sobrecarregá-las. Fornecemos orientação e feedback a recrutas iniciantes. Ao designar revisores para uma submissão, o nosso objetivo é juntar pessoas revisoras experientes com as iniciantes, ou as com experiência nos métodos de programação de um pacote com aquelas experientes em seu campo de aplicação. **Essas pessoas revisoras aprendem umas com as outras, e a diversidade de perspectivas é uma vantagem.** As pessoas desenvolvedoras menos experientes geralmente fornecem insights que as mais experientes não têm sobre a usabilidade do software, o design da API e a documentação. As pessoas desenvolvedoras mais experientes identificarão com mais frequência ineficiências no código, armadilhas devido a casos extremos ou sugerirão abordagens de implementação alternativas. ## Expansão da revisão por pares para código -A revisão de código tem sido uma das melhores iniciativas da rOpenSci. Criamos software, desenvolvemos habilidades e criamos comunidade, e o processo de revisão por pares tem sido um importante catalisador para todos os três. Ele tornou o software que desenvolvemos internamente e o que aceitamos de colaboradores externos mais confiável, utilizável e passível de manutenção. Assim **estamos trabalhando para promover a revisão por pares aberta do código por mais organizações** que trabalham com software científico. Ajudamos a lançar o [O Journal of Open Source Software](https://joss.theoj.org/) que usa uma versão do nosso processo de revisão para oferecer um local de publicação favorável ao desenvolvedor. O sucesso do JOSS levou a um spin-off, o [Journal of Open Source Education (Jornal de Educação de Código Aberto)](https://jose.theoj.org/) que usa um processo aberto, semelhante à revisão de código, para fornecer feedback sobre currículos e materiais educacionais. Também estamos desenvolvendo um programa piloto em que os artigos de software enviados a uma revista acadêmica parceira recebem um selo por passarem pela revisão do rOpenSci. Somos incentivados por outras iniciativas de revisão, como [ReScience](https://rescience.github.io/) e [O historiador da programação](https://programminghistorian.org/). [BioConductor](https://www.bioconductor.org/) que antecedeu a nossa em vários anos, recentemente mudou para um modelo aberto. +A revisão de código tem sido uma das melhores iniciativas da rOpenSci. Criamos software, desenvolvemos habilidades e criamos comunidade, e o processo de revisão por pares tem sido um importante catalisador para todos os três. Ele tornou o software que desenvolvemos internamente e o que aceitamos de pessoas colaboradoras externas mais confiável, utilizável e passível de manutenção. Assim **estamos trabalhando para promover a revisão aberta de código por pares por mais organizações** que trabalham com software científico. Ajudamos a lançar o [The Journal of Open Source Software](https://joss.theoj.org/) que usa uma versão do nosso processo de revisão para oferecer um local de publicação favorável à pessoa desenvolvedora. O sucesso do JOSS levou a um spin-off, o [The Journal of Open Source Education](https://jose.theoj.org/) que usa um processo aberto, semelhante à revisão de código, para fornecer feedback sobre currículos e materiais educacionais. Também estamos desenvolvendo um programa piloto em que os artigos de software enviados a uma revista acadêmica parceira recebem um selo por passarem pela revisão da rOpenSci. Somos incentivados por outras iniciativas de revisão, como [ReScience](https://rescience.github.io/) e [O historiador da programação](https://programminghistorian.org/). As revisões de código da [BioConductor](https://www.bioconductor.org/), que antecedem as nossas por vários anos, recentemente mudaram para um modelo aberto. -**Se a sua organização estiver desenvolvendo ou fazendo a curadoria de códigos científicos, você pode usar o modelo** acreditamos que a revisão de código, bem implementada, pode ser um grande benefício. Você pode precisar de um esforço considerável para começar, mas **aqui estão algumas das principais lições que aprendemos e que podem ajudar você:** +**Se a sua organização estiver desenvolvendo ou fazendo a curadoria de códigos científicos, acreditamos que a revisão de código, bem implementada, pode ser um grande benefício. Você pode precisar de um esforço considerável para começar, mas **aqui estão algumas das principais lições que aprendemos e que podem ajudar você:** -- **Desenvolver padrões e diretrizes** Para que seus autores e revisores usem. Pegue-os emprestados livremente de outros projetos (sinta-se à vontade para usar os nossos) e modifique-os iterativamente à medida que você avança. -- **Use ferramentas automatizadas** como code linters, conjuntos de testes e medidas de cobertura de testes para reduzir ao máximo a carga dos autores, revisores e editores. -- **Tenha um escopo claro.** Explique a vocês mesmos e aos possíveis colaboradores o que o projeto aceitará e por quê. Isso evitará muita confusão e esforço no futuro. +- **Desenvolver padrões e diretrizes** para que autores e revisores da sua organização usem. Pegue-os emprestados livremente de outros projetos (sinta-se à vontade para usar os nossos) e modifique-os iterativamente à medida que você avança. +- **Use ferramentas automatizadas** como code linters, conjuntos de testes e medidas de cobertura de testes para reduzir ao máximo a carga das pessoas autoras, revisoras e editoras. +- **Tenha um escopo claro.** Explique a vocês mesmos e as possíveis pessoas colaboradoras o que o projeto aceitará e por quê. Isso evitará muita confusão e esforço no futuro. - **Crie uma comunidade** por meio de incentivos de networking, oportunidades de aprendizado e gentileza. -**A rOpenSci está ansiosa para trabalhar com outros grupos interessados em desenvolver processos de revisão semelhantes** O rOpenSci é um grupo de trabalho que tem como objetivo trabalhar com outros grupos interessados em desenvolver processos de revisão semelhantes, especialmente se você estiver interessado em revisar e curar software científico em linguagens diferentes do R ou além do nosso escopo de suporte ao ciclo de vida dos dados. O software que implementa algoritmos estatísticos, por exemplo, é uma área propícia para a revisão aberta de código por pares. Por favor [entre em contato conosco](/contact/) se você tiver dúvidas ou quiser co-pilotar um sistema de revisão para o seu projeto. +**A rOpenSci está ansiosa para trabalhar com outros grupos interessados em desenvolver processos de revisão semelhantes**, especialmente se você tiver interesse em revisar e curar software científico em linguagens diferentes do R ou além do nosso escopo de suporte ao ciclo de vida dos dados. O software que implementa algoritmos estatísticos, por exemplo, é uma área propícia para a revisão aberta de código por pares. Por favor, [entre em contato conosco](/contact/) se você tiver dúvidas ou quiser co-pilotar um sistema de revisão para o seu projeto. -E, é claro, se você quiser fazer revisões, estamos sempre procurando voluntários. Inscreva-se em /onboarding. +E, é claro, se você quiser fazer revisões, estamos sempre procurando voluntários(as). Inscreva-se em /onboarding. *** -Você pode apoiar a rOpenSci [tornando-se um membro do NumFOCUS](https://www.numfocus.org/community/donate/) ou fazendo uma doação de [doação para o projeto](https://www.numfocus.org/open-source-projects/). +Você pode apoiar a rOpenSci [tornando-se uma pessoa membro do NumFOCUS](https://www.numfocus.org/community/donate/) ou fazendo uma [doação para o projeto](https://www.numfocus.org/open-source-projects/). diff --git a/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md b/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md index df35b0c6b2..95c2da3d4d 100644 --- a/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md +++ b/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md @@ -1,5 +1,5 @@ --- -title: Desafios e soluções editoriais na revisão por pares de software +title: Desafios e soluções editoriais na revisão de software por pares author: - Maëlle Salmon - Noam Ross @@ -9,65 +9,65 @@ tags: - Software Peer Review - editors package_version: 0.1.0 -description: Os desafios encontrados pelos editores e as medidas que tomamos para +description: Os desafios encontrados pelas pessoas editoras e as medidas que tomamos para tentar aliviar esses problemas. featured: true params: doi: 10.59350/tfy8g-0e676 --- -rOpenSci [Revisão por pares de software](/software-review/) e [Revisão por pares de software estatístico](/software-review/) dependem do trabalho voluntário de revisores e editores. -Os editores gerenciam o fluxo diário de envios, recrutam revisores e orientam o processo de revisão por pares do início ao fim. (Sua função, como grande parte do nosso processo, é [codificada no Guia do desenvolvedor do rOpenSci](https://devguide.ropensci.org/editorguide.html)). Embora muitos membros da nossa comunidade tenham participado do processo de revisão por pares, apenas alguns se envolveram como editores e editores convidados. Aqui, pensamos em esclarecer alguns dos desafios que nossos editores enfrentam e algumas das soluções que encontramos ao longo dos anos, para tornar essa parte do nosso trabalho mais transparente. +rOpenSci [Revisão de software por pares](/software-review/) e [Revisão de software estatístico por pares](/software-review/) dependem do trabalho voluntário de revisores(as) e editores(as). +Os(As) editores(as) gerenciam o fluxo diário de envios, recrutam revisores(as) e orientam o processo de revisão por pares do início ao fim (Sua função, como grande parte do nosso processo, é [codificada no Guia do Desenvolvedor da rOpenSci](https://devguide.ropensci.org/editorguide.html)). Embora muitas pessoas membros da nossa comunidade tenham participado do processo de revisão por pares, apenas algumas se envolveram como editoras convidadas. Aqui, pensamos em esclarecer alguns dos desafios que nossos(as) editores(as) enfrentam e algumas das soluções que encontramos ao longo dos anos, para tornar essa parte do nosso trabalho mais transparente. ## Decisões de escopo -Depois que um pacote é enviado, antes de receber um editor e revisores, o Editor-chefe rotativo deve avaliar se ele é *no escopo* para o processo de revisão. Tradicionalmente, o editor-chefe rotativo da rOpenSci [escopo](https://devguide.ropensci.org/policies.html#aims-and-scope) tem se concentrado em pacotes que gerenciam o ciclo de vida dos dados de pesquisa. Isso serve para que os pacotes do rOpenSci formem um conjunto coerente de ferramentas e também para nos limitar a pacotes que nossos editores e revisores possam analisar com padrões e conhecimentos relevantes. +Depois que um pacote é enviado, antes de receber um(a) editor(a) e revisores, o(a) Editor(a)-chefe rotativo(a) deve avaliar se ele está *no escopo* para o processo de revisão. Tradicionalmente, o [escopo](https://devguide.ropensci.org/policies.html#aims-and-scope) da rOpenSci tem se concentrado em pacotes que gerenciam o ciclo de vida dos dados de pesquisa. Isso serve para que os pacotes da rOpenSci formem um conjunto coerente de ferramentas e também para nos limitar a pacotes que nossos(as) editores(as) e revisores(as) possam analisar com padrões e conhecimentos relevantes. -As decisões sobre o escopo podem ser complicadas e, embora não haja como contornar essa complexidade, descobrimos que ficou mais fácil ao refinar o [descrições de escopo](https://devguide.ropensci.org/policies.html#aims-and-scope) ao longo do tempo, pois temos mais casos extremos. -Melhores frases e exemplos também ajudam os autores a avaliar o possível escopo de seus pacotes antes de enviá-los. Agora que nosso escopo é [está se expandindo para incluir pacotes estatísticos](https://stats-devguide.ropensci.org/overview.html#overview-categories) esperamos continuar a refinar essas categorias nos próximos meses e anos. +As decisões sobre o escopo podem ser complicadas e, embora não haja como contornar essa complexidade, descobrimos que ficou mais fácil ao refinar as [descrições de escopo](https://devguide.ropensci.org/policies.html#aims-and-scope) ao longo do tempo, à medida que temos mais casos extremos. +Melhores frases e exemplos também ajudam as pessoas autoras a avaliar o possível escopo de seus pacotes antes de enviá-los. Agora que o nosso escopo [está se expandindo para incluir pacotes estatísticos](https://stats-devguide.ropensci.org/overview.html#overview-categories) esperamos continuar a refinar essas categorias nos próximos meses e anos. -Quando o escopo de um pacote é ambíguo, o Editor-chefe conduz uma discussão no canal editorial do Slack com outros editores para chegar a um consenso. +Quando o escopo de um pacote é ambíguo, a pessoa Editora-chefe conduz uma discussão no canal editorial do Slack com outros(as) editores(as) para chegar a um consenso. Nessas discussões, reconhecemos que alguns de nós podem ter mais experiência em alguns tópicos e, às vezes, até consultamos especialistas externos à diretoria para obter mais insights. -Observe que incentivamos os autores de pacotes a enviar um *consulta pré-submissão* antes de um envio completo, para esclarecer qualquer dúvida sobre o escopo. +Observe que incentivamos as pessoas autoras de pacotes a enviar uma *consulta pré-submissão* antes de um envio completo, para esclarecer qualquer dúvida sobre o escopo. ## Recrutamento e substituição de revisores -A revisão de um pacote toma um tempo precioso das agendas ocupadas dos revisores. -Esperamos que a experiência seja valiosa para os avaliadores (e tentamos facilitar a tarefa com nosso [guia do revisor](https://devguide.ropensci.org/reviewerguide.html)), mas consideramos que é uma tarefa e tanto, que exige aproximadamente o mesmo tempo que a revisão de um artigo científico. -Para aumentar a dificuldade de encontrar revisores disponíveis, temos uma lista de [critérios para a escolha de revisores](https://devguide.ropensci.org/editorguide.html#criteria-for-choosing-a-reviewer) para garantir a diversidade (tanto em termos de habilidades quanto de formação) e para formar continuamente um grupo de revisores experientes sem sobrecarregar nenhum deles. +A revisão de um pacote toma um tempo precioso das agendas ocupadas das pessoas revisoras. +Esperamos que a experiência seja valiosa para as pessoas avaliadoras (e tentamos facilitar a tarefa com o nosso [guia da pessoa revisora](https://devguide.ropensci.org/reviewerguide.html)), mas consideramos que é uma tarefa e tanto, que exige aproximadamente o mesmo tempo que a revisão de um artigo científico. +Embora isto possa aumentar a dificuldade de encontrar revisores disponíveis, temos uma lista de [critérios para a escolha de revisores](https://devguide.ropensci.org/editorguide.html#criteria-for-choosing-a-reviewer) para garantir a diversidade (tanto em termos de habilidades quanto de formação) e para formar continuamente um grupo de pessoas revisoras experientes sem sobrecarregar nenhuma delas. -No ano passado, lançamos um [novo formulário de voluntariado para revisores](/blog/2021/11/18/devguide-0.7.0/#a-new-form-for-volunteer-reviewing) que nos permite coletar dados mais refinados sobre conhecimentos técnicos e tópicos, bem como uma pergunta opcional: "Você se considera parte de um grupo sub-representado nas áreas de ciência de dados, programação ou em seu campo principal de trabalho? -Mantemos essas informações em um banco de dados (gerenciado pelo Airtable), juntamente com o histórico de avaliações de cada revisor. Esse banco de dados é um recurso para os editores, pois eles procuram revisores com conhecimentos específicos, experiência ou disponibilidade. +No ano passado, lançamos um [novo formulário de voluntariado para revisores](/blog/2021/11/18/devguide-0.7.0/#a-new-form-for-volunteer-reviewing) que nos permite coletar dados mais refinados sobre conhecimentos técnicos e tópicos, bem como uma pergunta opcional: "Você se considera parte de um grupo subrepresentado nas áreas de ciência de dados, programação ou em seu campo principal de trabalho? +Mantemos essas informações em um banco de dados (gerenciado pelo Airtable), juntamente com o histórico de avaliações de cada pessoa revisora. Esse banco de dados é um recurso para os(as) editores(as), pois eles(as) procuram pessoas revisoras com conhecimentos específicos, experiência ou disponibilidade. -Quando isso não for suficiente, por exemplo, após repetidas recusas ou não respostas de possíveis avaliadores, os editores podem solicitar recomendações de outros editores em nosso canal do Slack. (Alguns de nós somos editores de revistas científicas tradicionais e gostaríamos de ter um bate-papo tão útil com nossos coeditores lá!) +Quando isso não for suficiente, por exemplo, após repetidas recusas ou não respostas de possíveis avaliadores, os(as) editores(as) podem solicitar recomendações de outros(a) editores(as) em nosso canal do Slack (Alguns de nós somos editores(as) de revistas científicas tradicionais e gostaríamos de ter um bate-papo tão útil com nossos(as) coeditores(as) lá!) -Um desafio ao entrar em contato com os avaliadores é saber quando você deve seguir em frente depois de esperar por uma resposta. Por isso, acrescentamos a frase "Se eu não receber uma resposta sua dentro de uma semana, presumirei que você não pode fazer uma revisão no momento" ao nosso [modelo padrão de solicitação de revisão](https://devguide.ropensci.org/reviewrequesttemplate.html). Com isso, todos ficam na mesma página e você esclarece tanto os editores quanto os possíveis avaliadores. +Um desafio ao entrar em contato com as pessoas avaliadoras é saber quando você deve seguir em frente depois de esperar por uma resposta. Por isso, acrescentamos a frase "Se eu não receber uma resposta sua dentro de uma semana, presumirei que você não pode fazer uma revisão no momento" ao nosso [modelo padrão de solicitação de revisão](https://devguide.ropensci.org/reviewrequesttemplate.html). Com isso, todas as pessoas ficam na mesma página e você esclarece tanto os(as) editores(as) quanto as possíveis pessoas avaliadoras. -Por fim, quando um revisor sai do processo de revisão (ou não pode mais ser contatado), -o editor responsável pelo tratamento recruta um substituto, geralmente uma pessoa a quem ele pode pedir uma resposta rápida (digamos, outro editor!), ou o editor atua como um segundo revisor. +Por fim, quando uma pessoa revisora sai do processo de revisão (ou não pode mais ser contatada), +o(a) editor(a) responsável pelo tratamento recruta um(a) substituto(a), geralmente uma pessoa a quem ele(a) pode pedir uma resposta rápida (digamos, outro(a) editor(a)!), ou o(a) editor(a) atua como um(a) segundo(a) revisor(a). O objetivo é não atrasar muito o processo de revisão. ## Desistência de autores -É uma situação ainda mais triste quando o pacote *autores* param de responder, pois o processo de revisão precisa ser interrompido. -É especialmente decepcionante quando isso acontece depois que as revisões já foram feitas, pois os revisores podem sentir que seu trabalho foi desperdiçado. -No final, não há nada que possamos fazer a respeito, pois isso está fora do controle de nossos editores e revisores (e dos autores). +É uma situação ainda mais triste quando o pacote *autores* para de responder, pois o processo de revisão precisa ser interrompido. +É especialmente decepcionante quando isso acontece depois que as revisões já foram feitas, pois os(as) revisores(as) podem sentir que o seu trabalho foi desperdiçado. +No final, não há nada que possamos fazer a respeito, pois isso está fora do controle de nossos(as) editores(as) e revisores(as) (e das pessoas autoras). -No entanto, para evitar problemas simples com comunicações perdidas, recomendamos que os autores se certifiquem de que recebem notificações do GitHub, pois tentamos manter a comunicação transparente por meio do GitHub e geralmente não usamos e-mail. -Para lidar com problemas maiores relacionados a tempo e comprometimento, recentemente adicionamos frases à (versão de desenvolvimento de) [guia do autor](https://devdevguide.netlify.app/authors-guide.html) e aos modelos de envio: "Espero manter este pacote por pelo menos dois anos ou encontrar um substituto." -Isso deve fazer com que os autores de pacotes pensem na manutenção do pacote a longo prazo. -Embora isso não evite todos os problemas, esperamos que os autores de pacotes pensem na manutenção do pacote a longo prazo antes de enviar seus pacotes para revisão. +No entanto, para evitar problemas simples com comunicações perdidas, recomendamos que os(as) autores(as) se certifiquem de que recebem notificações do GitHub, pois tentamos manter a comunicação transparente por meio do GitHub e geralmente não usamos e-mail. +Para lidar com problemas maiores relacionados a tempo e comprometimento, recentemente adicionamos frases à (versão de desenvolvimento de) [guia da pessoa autora](https://devdevguide.netlify.app/authors-guide.html) e aos modelos de envio: "Espero manter este pacote por pelo menos dois anos ou encontrar uma pessoa substituta". +Isso deve fazer com que as pessoas autoras de pacotes pensem na manutenção do pacote a longo prazo. +Embora isso não evite todos os problemas, esperamos que as pessoas autoras de pacotes pensem na manutenção do pacote a longo prazo antes de enviar os seus pacotes para a revisão. -Também entendemos que, embora os autores possam ter boas intenções, a vida pode se transformar inesperadamente. +Também entendemos que, embora as pessoas autoras possam ter boas intenções, a vida pode se transformar inesperadamente. Portanto, outro esforço que fazemos é suspender as revisões (aplicando rótulos de suspensão) conforme necessário. Essas retenções são revisadas a cada três meses, até um ano. -## Sobrecarga de trabalho dos editores (e revisores) +## Sobrecarga de trabalho das pessoas editoras (e revisoras) -A revisão de software exige trabalho de todos: editores, revisores e, obviamente, autores. +A revisão de software exige trabalho de todas as pessoas: editores, revisores e, obviamente, autores. -Para reduzir o trabalho editorial em particular, aprimoramos a automação, que foi o tópico de uma chamada da comunidade, ["Aprimorando a revisão por pares de software com a automação do GitHub"](/commcalls/dec2021-automation/). +Para reduzir o trabalho editorial em particular, aprimoramos a automação, que foi o tópico de uma chamada da comunidade, ["Aprimorando a revisão de software por pares com a automação do GitHub"](/commcalls/dec2021-automation/). A rOpenSci trabalhou com o The Journal of Open Source Software para estender a abordagem do JOSS de publicação orientada por chatops para um novo chat-bot do GitHub que gerencia nosso processo editorial: atribuição de tarefas, marcação de problemas, execução de testes em envios de software, retorno de relatórios para revisores e editores e registro de revisões em um banco de dados externo (Airtable). Tudo isso no conforto de um comentário de problema do GitHub! Por exemplo, você poderia clonar um repositório localmente, instalar dependências, executar verificações e publicar manualmente os resultados... **ou** você poderia simplesmente digitar o seguinte em um comentário de problema do GitHub: @@ -75,23 +75,23 @@ Por exemplo, você poderia clonar um repositório localmente, instalar dependên @ropensci-review-bot check package ``` -Da mesma forma, você pode usar o seguinte para registrar um revisor nos metadados do problema de envio, bem como em nosso banco de dados Airtable. +Da mesma forma, você pode usar o seguinte para registrar uma pessoa revisora nos metadados do problema de envio, bem como em nosso banco de dados Airtable. ``` @ropensci-review-bot add @maelle to reviewers ``` -Uma grande parte da limitação da carga de trabalho dos editores é ter editores suficientes! Nós temos [expandindo nossa equipe editorial](/tags/editors/) com o objetivo de esperar que os editores lidem apenas com [cerca de 4 envios por ano](https://devdevguide.netlify.app/editorguide.html#editors-responsabilities). -À medida que o volume de envios aumenta e os editores saem (pedimos compromissos de dois anos com opção de renovação), recrutamos novos editores, em grande parte a partir do nosso grupo de revisores. -Convidamos revisores experientes para editar como convidados e perguntamos se eles querem continuar se tudo der certo. -Nosso [guia do editor](https://devguide.ropensci.org/editorguide.html) facilita a integração... e a integração de novos editores leva a comentários e, portanto, a melhorias nesse guia. -Se você quiser tentar editar [comece sendo voluntário como revisor](/software-reviewer)! +Uma grande parte da limitação da carga de trabalho das pessoas editoras é ter editores suficientes! Nós temos [expandindo nossa equipe editorial](/tags/editors/) com o objetivo de esperar que os(as) editores(as) lidem apenas com [cerca de 4 envios por ano](https://devdevguide.netlify.app/editorguide.html#editors-responsabilities). +À medida que o volume de envios aumenta e os(as) editores(as) saem (pedimos compromissos de dois anos com opção de renovação), recrutamos novas pessoas editoras, em grande parte a partir do nosso grupo de revisores. +Convidamos pessoas revisoras experientes para editar como convidadas e perguntamos se elas querem continuar se tudo der certo. +Nosso [guia da pessoa editora](https://devguide.ropensci.org/editorguide.html) facilita a integração... e a integração de novas pessoas editoras leva a comentários e, portanto, a melhorias nesse guia. +Se você quiser tentar editar [comece sendo revisor(a) voluntário(a)](/software-reviewer)! ## Conclusão Resumimos aqui alguns problemas comuns de nossos conselhos editoriais. -Descobrimos que é muito importante automatizar os processos, mas também que os editores possam se comunicar diretamente uns com os outros para encontrar soluções, bem como para se solidarizar e incentivar uns aos outros. +Descobrimos que é muito importante automatizar os processos, mas também que as pessoas editoras possam se comunicar diretamente umas com as outras para encontrar soluções, bem como para se solidarizar e incentivar umas as outras. À medida que a revisão de software continuar, certamente encontraremos novos desafios a serem enfrentados. -Esperamos que nossas experiências sejam úteis para outros editores e que possam ajudar a informar outros conselhos editoriais. +Esperamos que as nossas experiências sejam úteis para outras pessoas editoras e que possam ajudar a informar outros conselhos editoriais. From 6fbda0cf26ac39473a2f9fed2b52ec241bbb428f Mon Sep 17 00:00:00 2001 From: Yanina Bellini Saibene Date: Thu, 19 Jun 2025 11:35:45 -0300 Subject: [PATCH 6/7] Update content/blog/2017-09-01-nsf-softwarereview/index.pt.md --- content/blog/2017-09-01-nsf-softwarereview/index.pt.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/blog/2017-09-01-nsf-softwarereview/index.pt.md b/content/blog/2017-09-01-nsf-softwarereview/index.pt.md index bbb18cd06f..a8c73a7cf7 100644 --- a/content/blog/2017-09-01-nsf-softwarereview/index.pt.md +++ b/content/blog/2017-09-01-nsf-softwarereview/index.pt.md @@ -13,6 +13,7 @@ author: - Karthik Ram - Maëlle Salmon topicid: 850 +translator: Francesca Belem Lopes Palmeira tags: - software - Software Peer Review From df2cb63de0f6c0097862298b050b3f61cd3412cb Mon Sep 17 00:00:00 2001 From: Yanina Bellini Saibene Date: Thu, 19 Jun 2025 11:36:18 -0300 Subject: [PATCH 7/7] Update content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md --- .../2022-04-19-software-review-editorial-challenges/index.pt.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md b/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md index 95c2da3d4d..9520326107 100644 --- a/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md +++ b/content/blog/2022-04-19-software-review-editorial-challenges/index.pt.md @@ -5,6 +5,7 @@ author: - Noam Ross date: '2022-04-19T00:00:02-07:00' slug: software-review-editorial-challenges +translator: Francesca Belem Lopes Palmeira tags: - Software Peer Review - editors