diff --git a/maintenance_curation.pt.Rmd b/maintenance_curation.pt.Rmd index 851786f8c..6027648bc 100644 --- a/maintenance_curation.pt.Rmd +++ b/maintenance_curation.pt.Rmd @@ -1,218 +1,220 @@ --- -aliases: +aliases: - curationpolicy.html --- -# Package Curation Policy {#curationpolicy} +# Política de curadoria de pacotes {#curationpolicy} ```{block, type="summaryblock"} -This chapter summarizes a proposed curation policy for rOpenSci's -ongoing maintenance of packages developed as part of rOpenSci activities -and/or under the rOpenSci GitHub organization. This curation policy aims -to support these goals: +Este capítulo resume uma proposta de política de curadoria para a manutenção contínua de +pacotes desenvolvidos como parte das atividades da rOpenSci +e/ou sob a organização da rOpenSci no GitHub. Essa política de curadoria visa +apoiar os seguintes objetivos: -- Ensure packages provided by rOpenSci are up-to-date and high quality +- Garantir que os pacotes fornecidos pela rOpenSci estejam atualizados e sejam de alta qualidade -- Provide clarity as to the development status and and review status - of any software in rOpenSci repositories +- Fornecer clareza quanto ao status de desenvolvimento e revisão + de qualquer software nos repositórios da rOpenSci -- Manage maintenance effort for rOpenSci staff, package authors, and - volunteer contributors +- Gerenciar o esforço de manutenção para a equipe da rOpenSci, para os(as) autores(as) de pacotes e + para os(as) colaboradores(as) voluntários(as) -- Provide a mechanism to gracefully sunset packages while maintaining - peer-review badging +- Fornecer um mecanismo para que os pacotes sejam descontinuados de forma adequada, mantendo + o selo de revisão por pares ``` -Elements of infrastructure described -below needed for implementation of the policy are in some cases partly -built and in other cases not yet begun. We aim to adopt this policy in -part to prioritize work on these components. +Elementos de infraestrutura descritos +abaixo necessários para a implementação da política foram, em alguns casos, parcialmente +construídos e, em outros casos, ainda não foram iniciados. Nosso objetivo é adotar essa política em +parte para priorizar o trabalho nesses componentes. -## The package registry {#the-package-registry} +## O registro de pacotes {#the-package-registry} -- The rOpenSci package +- O pacote rOpenSci [registry](https://github.com/ropensci/roregistry) - is a central listing of R packages currently or formerly - maintained or reviewed by rOpenSci. It contains essential package - metadata including development and review status, and will be the - source of data for display on websites, badges, etc. It will allow - this listing to be maintained independently of package or - infrastructure hosting platforms. - -## Staff-maintained packages {#staff-maintained-packages} - -Staff-maintained packages are developed and maintained by rOpenSci staff -as part of rOpenSci projects. These packages may also be peer-reviewed -packages, but are not necessarily peer reviewed. Many are infrastructure -packages that fall out of scope for peer review. - -- Staff-maintained packages will be listed in the registry with tag - "staff\_maintained" and listed on rOpenSci's packages web page or similar - venues with tag "staff-maintained" - -- These packages will be stored in the "ropensci" GitHub - organization - -- Staff-maintained packages and their docs will be built by rOpenSci - [system](https://status.ropensci.org/). This system does not send notifications - but it outputs results as GitHub commit status (red check mark or red cross). - -- When the packages fail checks, rOpenSci staff will endeavor to fix - changes, prioritizing packages based on user base (downloads), - reverse dependencies, or strategic goals. - -- On a biannual or annual basis, rOpenSci will review all packages - that have been failing for over a month to determine whether to transfer them to the ["ropensci-archive" GitHub organization](https://github.com/ropensci-archive). - -- Packages consistently failing and without an ongoing plan to return - to active maintenance will move to "archive" status. When - archived, staff packages will move to the "ropensci-archive" - repository (to be created) and and gain the "archived" type in - the registry. They will not be built on rOpenSci system. - -- Archived packages will not be displayed by default on the packages - web page. A special tab of packages pages will display - these with `"type": "archived"` - that were either peer-reviewed or staff-maintained. - -- Archived packages can be unarchived when the old or a new maintainer - is willing to address the problems and wants to revive the - package. For that please [contact rOpenSci](https://ropensci.org/contact/). - They are transferred to the ropenscilabs organization. - -## Peer-reviewed packages {#peer-reviewed-packages} - -Peer-reviewed packages are those contributed to the rOpenSci by the -community and have passed through peer review. They need to be -[in-scope](#aims-and-scope) -at the time of submission to be reviewed. - -- Upon acceptance, these peer-reviewed packages are transferred from - the author's GitHub to the "ropensci" GitHub organization - -- Peer-reviewed packages will be in the registry tagged as - "peer-reviewed" and have a peer-reviewed badge in their README. + é uma lista centralizada dos pacotes R que são mantidos atualmente (ou que foram + mantidos anteriormente) pela rOpenSci. + Ele contém metadados essenciais sobre os pacotes, incluindo o status de desenvolvimento e de revisão, + e será a fonte de dados para exibição em sites, *badges*, etc. Ele permite + que essa lista seja mantida de forma independente do pacote ou das + plataformas de hospedagem de infraestrutura. + +## Pacotes mantidos pela equipe {#staff-maintained-packages} + +Os pacotes mantidos pela equipe são pacotes desenvolvidos e mantidos pela equipe da rOpenSci +como parte dos projetos internos da rOpenSci. Esses pacotes também podem ser revisados por pares +mas não são necessariamente revisados por pares. Muitos desses pacotes +estão fora do escopo da revisão por pares. + +- Os pacotes mantidos pela equipe serão listados no registro com a tag + "staff\_maintained" e listados na página da Web de pacotes da rOpenSci, ou em locais similares + com a tag "staff-maintained" (mantido pela equipe) + +- Esses pacotes serão armazenados no dentro da organização no GitHub + chamada "ropensci" + + +- Os pacotes mantidos pela equipe e seus documentos serão criados pelo [sistema](https://status.ropensci.org/) + da rOpenSci. Esse sistema não envia notificações, + mas gera resultados como status de commit do GitHub (o *red check mark* ou o *red cross*). + +- Quando os pacotes falham nas verificações, a equipe da rOpenSci se esforça para corrigir + as alterações, priorizando os pacotes com base no volume de usuários (isto é, o volume de *downloads*), de + dependências reversas ou de objetivos estratégicos. + +- Em uma base semestral ou anual, a rOpenSci analisará todos os pacotes + que estão falhando há mais de um mês para determinar se você deve + transferi-los para a [organização "ropensci-archive" no GitHub](https://github.com/ropensci-archive). + +- Pacotes que falham consistentemente e sem um plano contínuo para retornar + para uma manutenção ativa, vão passar para o status de "archive". Quando + arquivados, os pacotes da equipe serão movidos para o diretório "ropensci-archive" + (a ser criado) e ganharão o tipo "archived" + no registro. Eles não serão construídos no sistema da rOpenSci. + +- Os pacotes arquivados não serão exibidos por padrão na seção de pacotes da + página da Web. Esses pacotes serão exibidos em uma guia especial das páginas de pacotes + com `"type": "archived"` + que foram revisados por pares ou que foram mantidos pela equipe. + +- Os pacotes arquivados podem ser desarquivados quando o mantenedor antigo ou um novo mantenedor + estiver disposto a resolver os problemas e quiser reviver o pacote. + Para isso, você deve [entrar em contato com a rOpenSci](https://ropensci.org/contact/). + Esses pacotes serão transferidos para a organização ropenscilabs. + +## Pacotes revisados por pares {#peer-reviewed-packages} + +Os pacotes revisados por pares são aqueles contribuídos para a rOpenSci +pela comunidade e que passaram pela revisão por pares. Eles precisam estar +[dentro do escopo](#aims-and-scope) no momento em que eles são enviados para serem revisados. + +- Após a aceitação, esses pacotes revisados por pares são transferidos + do GitHub do(a) autor(a) para dentro da organização "ropensci" no GitHub + +- Os pacotes revisados por pares estarão marcados no registro como + "peer-reviewed", e terão um selo de revisão por pares em seu README. + +- Os pacotes revisados por pares serão listados na página da Web da rOpenSci, ou + em locais semelhantes, com a tag "peer-reviewed" (revisado por pares) + +- Os pacotes revisados por pares e seus documentos serão construídos pelo + [sistema](https://status.ropensci.org/) da rOpenSci. Esse sistema não envia notificações + mas gera resultados como o status de commit do GitHub (o *red check mark* ou o *red cross*). + +- Anualmente ou semestralmente, a equipe da rOpenSci revisará os pacotes que estão em + estado de falha ou que estão falhando já por longos períodos, e + entrará em contato com os autores para determinar o status da manutenção e das + atualizações esperadas. Com base nesse intercâmbio, a rOpenSci pode optar por + manter o status atual do pacote com a expectativa de uma + atualização, ou contribuir com algum suporte, ou ainda, buscar um novo mantenedor, ou transferir + o pacote para o status "archived". -- Peer-reviewed packages will be listed on rOpenSci's web page or - similar venues with tag "peer-reviewed" +- Com base no volume de usuários (isto é, o volume de *downloads* do pacote), ou das dependências reversas, ou + dos objetivos estratégicos da rOpenSci, a equipe da rOpenSci pode apoiar os + pacotes que estiverem com problemas e falhas, por meio de PRs que são revisados pelos autores dos pacotes, + ou ainda, com alterações diretas + (se os autores não responderem por aproximadamente um mês). A rOpenSci + também fornecerá suporte aos autores de pacotes mediante solicitação, tanto pela + equipe interna, quanto por voluntários da comunidade, de acordo com o tempo disponível. -- Peer-reviewed packages and their docs will be built by rOpenSci - [system](https://status.ropensci.org/). This system does not send notifications - but it outputs results as GitHub commit status (red check mark or red cross). +- A pedido do autor, ou se os autores não responderem às consultas por aproximadamente um mês, + a rOpenSci poderá procurar um novo + mantenedor para os pacotes selecionados, que sejam revisados por pares, e que a rOpenSci considere ter alta + valor para a comunidade, com base no volume de usuários/*downloads*, ou nas + dependências reversas, ou nos objetivos estratégicos da rOpenSci. -- Annually or bi-annually, rOpenSci staff will review packages in a - failing state or have been failing for extended periods, and - contact the authors to determine ongoing maintenance status and - expected updates. Based on this exchange, rOpenSci may opt to - retain the package's current status with the expectation of an - updates, contribute support or seek a new maintainer, or transfer - the package to "archived" status. +- Quando arquivados, esses pacotes serão movidos da organização "ropensci" + para a organização "ropensci-archive" no GitHub (ou para a conta do autor + no GitHub, caso for de desejo do autor), seguindo as [orientações de transferência](#archivalguidance). + Elas ganharão o tipo "archived" + no registro. Esses pacotes vão manter as tags "peer-reviewed" (revisado por pares) e + e *badges*. Eles não serão construídos no sistema da rOpenSci. -- Based on user base (measured by downloads), reverse dependencies, or - rOpenSci strategic goals, rOpenSci staff may support failing - packages via PRs reviewed by package authors, or direct changes - (if authors are unresponsive for approximately a month). rOpenSci - will also provide support to package authors on request, both by - staff and community volunteers, based on time available. +- Os pacotes arquivados não serão exibidos por padrão na seção de pacotes da + página da Web. Esses pacotes serão exibidos em uma guia especial das páginas de pacotes + com `"type": "archived"` que foram revisados por pares, ou que foram mantidos pela equipe. -- At the author's request, or if authors are unresponsive to - inquiries for approximately a month, rOpenSci may seek a new - maintainer for select peer-reviewed packages it deems have high - community value based on user base/downloads, reverse - dependencies, or rOpenSci strategic goals. +## Pacotes legado que foram adquiridos {#legacy-acquired-packages} -- When archived, these packages will move from the "ropensci" GitHub - organization to the "ropensci-archive" organization (or author - GitHub accounts if desired), following [transfer guidance](#archivalguidance). They will gain the "archived" type - in the registry. They will retain "peer-reviewed" tags and - badges. They will not be built on rOpenSci system. +Os pacotes "legado" são pacotes que não foram criados ou mantidos pela rOpenSci +e que também não são revisados por pares, mas que estão sob o controle da rOpenSci no GitHub +devido a razões históricas. (Antes de estabelecer a organização, e o seu +processo de revisão por pares e o seu escopo, a rOpenSci absorveu pacotes de +vários desenvolvedores sem critérios bem definidos). -- Archived packages will not be displayed by default. A special tab of packages - pages will display these with `"type": "archived"` - that were either peer-reviewed or staff-maintained. +- A rOpenSci transferirá os pacotes legado de volta para as organizações + e repositórios dos autores. Se os autores não tiverem interesse, transferiremos + para o repositório "ropensci-archive", seguindo as regras das [orientações de transferência](#archivalguidance). Se os pacotes estiverem + [no escopo](https://devguide.ropensci.org/policies.html#aims-and-scope), + a rOpenSci perguntará se os autores gostariam de submetê-los ao + processo de revisão de software. -## Legacy acquired packages {#legacy-acquired-packages} +- Os pacotes legado não serão listados no registro de pacotes. -"Legacy" packages are packages not created or maintained by rOpenSci -staff and not peer reviewed, but are under the rOpenSci GitHub -organization(s) due to historical reasons. (Prior to establishing the -peer review process and its scope, rOpenSci absorbed packages from -various developers without well-defined criteria.) +- Exceções podem ser feitas para pacotes que sejam partes vitais do ecossistema de pacotes do R e/ou da rOpenSci, e que sejam ativamente monitorados pela equipe. -- rOpenSci will transfer legacy packages back to author organizations - and repositories. If authors are uninterested, we will transfer - them to the "ropensci-archive" repository following [transfer guidance](#archivalguidance). If packages are - [in-scope](https://devguide.ropensci.org/policies.html#aims-and-scope), - rOpenSci will inquire if authors would like to submit them to the - Software Review process. +## Pacotes de incubadora {#incubator-packages} -- Legacy packages will not be listed in the package registry. +Os pacotes de "incubadora" são pacotes em desenvolvimento criados pela equipe ou por +membros da comunidade como parte de projetos comunitários, como os criados por +em desconferências. -- Exceptions may be made for packages that are vital parts of the R and/or rOpenSci package ecosystem which are actively monitored by staff. +- Os pacotes de incubadora ficarão na organização "ropenscilabs" no GitHub. -## Incubator packages {#incubator-packages} +- Os pacotes de incubadora aparecerão no registro de pacotes com a + tag "incubator". -"Incubator" packages are in-development packages created by staff or -community members as part of community projects, such as those created -at unconferences +- Os pacotes de incubadora não serão exibidos no site por padrão, mas + as páginas de pacotes incluem uma guia especial de "pacotes experimentais". -- Incubator packages will live in the "ropenscilabs" organization. +- Os pacotes da incubadora e seus documentos serão criados pelo + [sistema](https://status.ropensci.org/) da rOpenSci. Esse sistema não envia notificações + mas gera resultados como o status de commit do GitHub (o *red check mark* ou o *red cross*). + Os documentos indicarão claramente que o pacote é experimental. -- Incubator packages will appear in the package registry with the - "incubator" tag +- Semestralmente ou anualmente, a rOpenSci entrará em contato com os mantenedores desses pacotes de incubadora + sobre repositórios que tenham pelo menos três meses de idade, perguntando + sobre o status de desenvolvimento e as preferências dos autores sobre uma migração para o + processo de revisão por pares, ou para o "ropensci-archive", ou para uma organização dos autores. Baseado em + nas respostas, o pacote será migrado imediatamente, e a revisão por pares + será iniciada, ou a migração será adiada para a próxima + revisão. Os pacotes de incubadora serão migrados para o "ropensci-archive" + por padrão, seguindo as [orientações de transferência](#archivalguidance). -- Incubator packages will not appear on the website by default, but - packages pages will include an "experimental packages" tab. +- Os pacotes de incubadora arquivados ganharão o tipo "archived". -- Incubator packages and their docs will be built by rOpenSci - [system](https://status.ropensci.org/). This system does not send notifications - but it outputs results as GitHub commit status (red check mark or red cross). - The docs will indicate clearly the package is experimental. +### Pacotes de incubadora que não sejam pacotes de R {#incubator-non-r-packages} -- Biannually or annually, rOpenSci will contact incubator maintainers - about repositories at least three months old, inquiring about - development status and author preferences for migration to - peer-review, ropensci-archive, or to author organizations. Based - on response, package will be migrated immediately, peer review - will be initiated, or migration will be deferred to the next - review. Incubator packages will be migrated to ropensci-archive by - default after one year, following [transfer guidance](#archivalguidance). +- A organização da "incubadora" também pode incluir pacotes que não sejam pacotes de R. -- Archived incubator packages will gain the "archived" type. +- Esses projetos não serão listados no registro, e não vão aparecer no site da rOpenSci, + e também não serão construídos automaticamente. -### Incubator non-R-packages {#incubator-non-r-packages} +- A política de migração para esses pacotes será a mesma dos pacotes de R, com + locais de migração apropriados (por exemplo, "ropensci-books") -- The "incubator" organization will also include non-R-package - projects. +- Se um pacote que não for um pacote de R for arquivado, ele será movido para + a organização "ropensci-archive", seguindo as [orientações de transferência](#archivalguidance). -- These projects will not be listed in the registry or appear on a web - page, and will not be automatically built. +## Livros {#books} -- Migration policy will be the same as for R packages, with - appropriate migration locations (e.g., ropensci-books) +Os livros da rOpenSci são documentações longas, geralmente no formato `bookdown`, e +estão relacionados a pacotes, projetos ou temas da rOpenSci, criados tanto pelos autores de pacotes, quanto pela +equipe da rOpenSci, e também por membros da comunidade. -- If archived, non-R-packages will move to "ropensci-archive" following [transfer guidance](#archivalguidance). +- Os livros ficarão dentro da organização "ropensci-books" no GitHub. -## Books {#books} +- Os livros serão hospedados no domínio books.ropensci.org -rOpenSci books are long-form documentation, often bookdown-formatted, -related to rOpenSci packages, projects, or themes, created by both -rOpenSci staff and community members. +- Os livros podem estar maduros ou em desenvolvimento, mas devem ter um mínimo de + esboços/conteúdo antes de serem migrados da organização "ropenscilabs" para + dentro da organização "ropensci-books". -- Books will live in the "ropensci-books" organization +- A autoria e o status de desenvolvimento de um livro devem ser claramente + descritos em sua página inicial e no README. -- Books will be hosted at books.ropensci.org - -- Books may be mature or in-development, but must have minimal - outlines/content before migrating into "ropensci-books" (e.g. - from "ropenscilabs"). - -- The authorship and development status of a book should be clearly - described on its home page and README. - -- rOpenSci may provide badges or templates (e.g., "In development," - "Community Maintained,") for authors to use on book home pages - in the future +- A rOpenSci pode fornecer *badges* ou modelos (por exemplo, "Em desenvolvimento," + "Mantido pela comunidade") para os autores usarem nas páginas iniciais de seus livros. diff --git a/maintenance_evolution.Rmd b/maintenance_evolution.Rmd index 44dc28230..c1351f4ca 100644 --- a/maintenance_evolution.Rmd +++ b/maintenance_evolution.Rmd @@ -38,7 +38,7 @@ foo_bar(x = 5) #> Error in foo_bar(x = 5) : use 'y' instead of 'x' ``` -If you want to be more helpful, you could emit a warning but automatically take the necessary action: +If you want the function to be more helpful, you could change it to emit a warning but automatically take the necessary action: ```r foo_bar <- function(x, y) { diff --git a/maintenance_github_grooming.pt.Rmd b/maintenance_github_grooming.pt.Rmd new file mode 100644 index 000000000..4f8dc5436 --- /dev/null +++ b/maintenance_github_grooming.pt.Rmd @@ -0,0 +1,45 @@ + +# Preparação do GitHub {#grooming} + +```{block, type="summaryblock"} +Atualmente, os pacotes da rOpenSci são, em sua grande maioria, desenvolvidos no GitHub. Aqui, estão algumas dicas para aproveitar a plataforma em uma seção sobre [tornar seu repositório mais detectável](#repodiscoverability) e uma seção sobre [comercializar sua própria conta do GitHub após passar pela revisão por pares](#marketown). + +``` + +## Torne seu repositório mais detectável {#repodiscoverability} + +### Tópicos do repositório do GitHub {#git-hub-repo-topics} + +Os [tópicos de repositórios](https://blog.github.com/2017-01-31-introducing-topics/) do GitHub ajudam a navegar e pesquisar repositórios do GitHub, são usados pelo [R-universe em páginas de pacotes e para resultados de pesquisa](https://github.com/r-universe-org/help#how-to-add-keyword-labels-to-an-r-package) e são processados pelo [`codemetar`](https://github.com/ropensci/codemetar) para palavras-chave de registro da rOpenSci. + +Recomendamos: + +- Adicionar "r", "r-package" e "rstats" como tópicos ao repositório de seu pacote. + +- Adicionar quaisquer outros tópicos relevantes ao repositório do seu pacote. + +Poderemos fazer sugestões a você depois que seu pacote for integrado. + +### GitHub linguist {#git-hub-linguist} + +O [GitHub linguist](https://github.com/github/linguist) atribuirá uma linguagem ao seu repositório com base nos arquivos que ele contém. Alguns pacotes que contêm muito código em C++ podem ser classificados como pacotes C++ em vez de pacotes R, o que é bom e mostra a necessidade de adicionar os tópicos "r", "r-package" e "rstats". + +Recomendamos que você substitua o GitHub linguist adicionando ou modificando um .gitattributes ao seu repositório em dois casos: + +- Se você armazenar arquivos html em locais diferentes do padrão (não em docs/, por exemplo, em vignettes/), use as substituições de documentação. Adicione `*.html linguist-documentation=true` ao arquivo .gitattributes ([Exemplo em uso real](https://github.com/ropensci/ecoengine/blob/56b64d8d29dfae430a776d1dd440b240452eb1bf/.gitattributes#L5)) + +- Se o seu repositório contiver código que você não criou, por exemplo, código JavaScript, adicione `inst/js/* linguist-vendored` a .gitattributes ([Exemplo em uso real](https://github.com/ropensci/wellknown/blob/4435eb620eeae346d2cab7d62276c29dee29a898/.gitattributes#L1)) + +Dessa forma, a classificação da linguagem e as estatísticas do seu repositório refletirão melhor o código-fonte que ele contém, além de torná-lo mais detectável. Notavelmente, se o GitHub linguist não reconhecer corretamente que seu repositório contém principalmente código R, seu pacote não aparecerá nos resultados de pesquisa usando o filtro `language:R`. Da mesma forma, seu repositório não poderá ser listado entre os [repositórios R em alta](https://github.com/trending/r). + +Mais informações sobre as substituições do GitHub linguist podem ser encontradas [aqui](https://github.com/github/linguist#overrides). + +## Comercialize sua própria conta {#marketown} + +- Como autor de um pacote integrado, você agora é membro da organização "ropensci" da rOpenSci no GitHub. Por padrão, as participações da organização são privadas; consulte [como torná-la pública na documentação do GitHub](https://help.github.com/articles/publicizing-or-hiding-organization-membership/). + +- Mesmo após o repositório do seu pacote ser transferido para a rOpenSci, você pode [fixá-lo em sua conta pessoal](https://help.github.com/articles/pinning-repositories-to-your-profile/). + +- Em geral, recomendamos que você adicione pelo menos um avatar (que não precisa ser seu rosto!) e seu nome [no seu perfil do GitHub](https://help.github.com/articles/customizing-your-profile/). + + diff --git a/maintenance_marketing.pt.Rmd b/maintenance_marketing.pt.Rmd index b882f984a..6139a194c 100644 --- a/maintenance_marketing.pt.Rmd +++ b/maintenance_marketing.pt.Rmd @@ -4,25 +4,25 @@ aliases: - marketing.html --- -# Marketing your package {#marketing} +# Marketing do seu pacote {#marketing} ```{block, type="summaryblock"} -We will help you promoting your package but here are some more things to keep in mind. +Ajudaremos você a promover o seu pacote, mas aqui estão mais algumas coisas que você deve ter em mente. ``` -- If you hear of an use case of your package, please encourage its author to post the link to our [discussion forum in the Use Cases category](https://discuss.ropensci.org/c/usecases), [for a tweet from rOpenSci and possible inclusion in the rOpenSci biweekly newsletter](https://discuss.ropensci.org/t/about-the-usecases-category/33). We also recommend you to add a link to the use case in a "use cases in the wild" section of your README. +- Se você souber de um caso de uso de seu pacote, incentive o autor a publicar o link em nosso [fórum de discussão na categoria *Use Cases*](https://discuss.ropensci.org/c/usecases), [para um post no Mastodon da rOpenSci e possível inclusão no boletim quinzenal da rOpenSci](https://discuss.ropensci.org/t/about-the-usecases-category/33). Também recomendamos que você adicione um link para o caso de uso em uma seção "use cases in the wild" do seu README. -- When you [release](#releasing) a new version of your package or release it to CRAN for the first time, +- Quando você [liberar](#releasing) uma nova versão do seu pacote ou você lançá-lo pela primeira vez no CRAN, - - Make a pull request to [R Weekly](https://github.com/rweekly/rweekly.org) with a line about the release under the "New Releases" section (or "New Packages" for the first GitHub/CRAN release). + - Faça um *pull request* para a [R Weekly](https://github.com/rweekly/rweekly.org) com uma linha sobre essa nova versão na seção "New Releases" (ou "New Packages" para a primeira versão do GitHub/CRAN). - - Tweet about it using the "#rstats" hashtag and tag rOpenSci! This might help with contributor/user engagement. [Example](https://twitter.com/opencpu/status/1003934871830622208). + - Tweet sobre isso usando a hashtag "#rstats" e marque rOpenSci! Isso pode ajudar no envolvimento do colaborador/usuário. [Exemplo](https://twitter.com/opencpu/status/1003934871830622208). - - Consider submitting a short post about the release to [rOpenSci tech notes](https://ropensci.org/technotes/). Contact rOpenSci Community Manager, (e.g. via Slack or [info@ropensci.org](mailto:info@ropensci.org)). Refer to [the guidelines about contributing a blog post](https://blogguide.ropensci.org)). + - Considere a possibilidade de enviar um breve post sobre o lançamento para as [Notas técnicas da rOpenSci](https://ropensci.org/technotes/). Entre em contato com o/a gerente da comunidade do rOpenSci (por exemplo, via Slack ou [info@ropensci.org](mailto:info@ropensci.org)). Consulte [as diretrizes sobre como contribuir com um *blog post*](https://blogguide.ropensci.org)). - - Submit your package to lists of packages such as [CRAN Task Views](https://cran.r-project.org/web/views/), and [rOpenSci non-CRAN Task Views](https://github.com/search?utf8=%E2%9C%93&q=user%3Aropensci+%22task+view%22&type=Repositories&ref=searchresults). + - Envie seu pacote para listas de pacotes, como a [Visão de tarefas do CRAN](https://cran.r-project.org/web/views/). -- If you choose to market your package by giving a talk about it at a meetup or conference (excellent idea!) - read [this article of Jenny Bryan's and Mara Averick's](https://www.tidyverse.org/articles/2018/07/carpe-talk/). +- Se você optar por divulgar o seu pacote dando uma palestra sobre ele em um encontro ou conferência (excelente ideia!) + leia [este artigo de Jenny Bryan e Mara Averick](https://www.tidyverse.org/articles/2018/07/carpe-talk/). diff --git a/newstemplate.pt.Rmd b/newstemplate.pt.Rmd index 7781c7384..6375cab85 100644 --- a/newstemplate.pt.Rmd +++ b/newstemplate.pt.Rmd @@ -2,11 +2,11 @@ repo-actions: true --- -# NEWS template {#newstemplate} +# Modelo de notícias {#newstemplate} ````markdown ```{r} -#| child: "templates/news.md" +#| child: "templates/news.pt.md" ``` ```` diff --git a/pkg_building.Rmd b/pkg_building.Rmd index 2f24d0476..fd8bf23ad 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -286,15 +286,10 @@ You can make the names of (some) authors clickable by adding their URL, and you You can make your website content easier to browse by tweaking the navbar, refer to [`pkgdown` documentation](https://pkgdown.r-lib.org/articles/pkgdown.html#navigation-bar). In particular, note that if you name the main vignette of your package "pkg-name.Rmd", it'll be accessible from the navbar as a `Get started` link instead of via `Articles > Vignette Title`. -### Mathjax {#mathjax} +### Math rendering {#mathjax} -Once your package is transferred and it gets a website using our `pkgdown` template, if you want to use Mathjax you'll need to specify it in the `pkgdown` config file like so: - -```yaml -template: - params: - mathjax: true -``` +Please refer to [pkgdown documentation](https://pkgdown.r-lib.org/dev/articles/customise.html#math-rendering). +Our template is compatible with this configuration. ### Package logo {#package-logo} diff --git a/pkg_building.es.Rmd b/pkg_building.es.Rmd index d7bd633a6..f8ee22ce5 100644 --- a/pkg_building.es.Rmd +++ b/pkg_building.es.Rmd @@ -327,15 +327,10 @@ Ver la [documentación de `pkgdown`](https://pkgdown.r-lib.org/reference/build_h Puedes hacer que el contenido de tu sitio web sea más fácil de navegar modificando la barra de navegación, consulta [`pkgdown` documentación](https://pkgdown.r-lib.org/articles/pkgdown.html#navigation-bar). En particular, ten en cuenta que si el nombre de la viñeta principal de tu paquete es "pkg-name.Rmd", ésta será accesible desde la barra de navegación en la sección `Para empezar` en vez de en `Artículos > Título de la Viñeta`. -### Mathjax {#mathjax} +### Renderización de matemáticas {#mathjax} -Una vez que tu paquete sea transferido y obtenga un sitio web utilizando nuestra plantilla de `pkgdown`, si quieres utilizar Mathjax tendrás que especificarlo en el archivo de configuración de `pkgdown` de la siguiente manera - -```yaml -template: - params: - mathjax: true -``` +Lee la [documentación de pkgdown](https://pkgdown.r-lib.org/dev/articles/customise.html#math-rendering). +Nuestra plantilla es compatible con esta configuración. ### Logo del paquete {#package-logo} diff --git a/reviewrequesttemplate.pt.Rmd b/reviewrequesttemplate.pt.Rmd index e0b64460e..38511b769 100644 --- a/reviewrequesttemplate.pt.Rmd +++ b/reviewrequesttemplate.pt.Rmd @@ -2,9 +2,9 @@ repo-actions: true --- -# Review request template {#reviewrequesttemplate} +# Modelo de solicitação de revisão {#reviewrequesttemplate} -Editors may make use of the e-mail template below in recruiting reviewers. +Os editores podem usar o modelo de e-mail abaixo para recrutar revisores. ::: {.content-hidden when-format="pdf"} @@ -12,7 +12,7 @@ Editors may make use of the e-mail template below in recruiting reviewers. ```{r} #| results: 'asis' #| echo: false -#| child: "templates/request.md" +#| child: "templates/request.pt.md" ``` ```` @@ -21,7 +21,7 @@ Editors may make use of the e-mail template below in recruiting reviewers. ::: {.content-visible when-format="pdf"} ```{r} -#| child: "templates/request.md" +#| child: "templates/request.pt.md" ``` diff --git a/reviewtemplate.pt.Rmd b/reviewtemplate.pt.Rmd index 76e696697..d047fc48e 100644 --- a/reviewtemplate.pt.Rmd +++ b/reviewtemplate.pt.Rmd @@ -2,9 +2,9 @@ repo-actions: true --- -# Review template {#reviewtemplate} +# Modelo de revisão {#reviewtemplate} -You can save this as an R Markdown file, or delete the YAML and save it as a Markdown file. +Você pode salvar isso como um arquivo RMarkdown ou excluir o YAML e salvá-lo como um arquivo Markdown. ::: {.content-hidden when-format="pdf"} @@ -12,7 +12,7 @@ You can save this as an R Markdown file, or delete the YAML and save it as a Mar ```{r} #| results: 'asis' #| echo: false -cat(readLines("templates/review.md"), sep = "\n") +cat(readLines("templates/review.pt.md"), sep = "\n") ``` ```` @@ -21,7 +21,7 @@ cat(readLines("templates/review.md"), sep = "\n") ::: {.content-visible when-format="pdf"} ```{r} -#| child: "templates/review.md" +#| child: "templates/review.pt.md" ``` ::: diff --git a/scripts/airtable-get-reviewers.R b/scripts/airtable-get-reviewers.R index 7b7f681cb..da30334ee 100644 --- a/scripts/airtable-get-reviewers.R +++ b/scripts/airtable-get-reviewers.R @@ -1,13 +1,7 @@ - -editors <- c( - "Noam Ross", "Karthik Ram", "Maëlle Salmon", - "Anna Krystalli", "Mauro Lepore", - "Laura DeCicco", "Julia Gustavsen", - "Emily Riederer", "Adam Sparks", "Jeff Hollister" -) reviewers <- airtabler::airtable(base = "app8dssb6a7PG6Vwj", table = "reviewers-prod") -reviewers <- reviewers$`reviewers-prod`$select_all(fields = list("reviews", "name", "github")) +reviewers <- reviewers$`reviewers-prod`$select_all(fields = list("reviews", "editor", "name", "github")) +editors <- reviewers[lengths(reviewers$editor) > 0,][["name"]] reviewers <- reviewers[purrr::map_lgl(reviewers$reviews, ~!is.null(.)) & !(reviewers$name %in% c(editors, "???")), ] diff --git a/softwarereview_author.Rmd b/softwarereview_author.Rmd index a5a52483a..de1417d8a 100644 --- a/softwarereview_author.Rmd +++ b/softwarereview_author.Rmd @@ -53,7 +53,7 @@ This concise guide presents the software peer review process for you as a packag - An [editor](#editors) will review your submission within 5 business days and respond with next steps. The editor may assign the package to reviewers, request that the package be updated to meet minimal criteria before review, or reject the package due to lack of fit or overlap. - If your package meets minimal criteria, the editor will assign 1-3 reviewers. They will be asked to provide reviews as comments on your issue within 3 weeks. -- We ask that you respond to reviewers' comments within 2 weeks of the last-submitted review, but you may make updates to your package or respond at any time. Your response should include a link to the updated [NEWS.md](#news) of your package. Here is [an author response example](https://github.com/ropensci/software-review/issues/160#issuecomment-355043656). We encourage ongoing conversations between authors and reviewers. See the [reviewing guide](#reviewerguide) for more details. +- We ask that you respond to reviewers' comments within 2 weeks of the last-submitted review, but you may make updates to your package or respond at any time. Your response should include a link to the updated [NEWS.md](#news) of your package. Here is [an author response example](https://github.com/ropensci/software-review/issues/160#issuecomment-355043656). Once the response is commited, [submit it using the bot](bot_cheatsheet.html#submit-response-to-reviewers). We encourage ongoing conversations between authors and reviewers. See the [reviewing guide](#reviewerguide) for more details. - Any time package changes are likely to alter the results of [the automated `pkgcheck` checks](https://docs.ropensci.org/pkgcheck), authors can request a re-check with the command, `@ropensci-review-bot check package`. - Please notify us immediately if you are no longer able to maintain your package or to respond to reviews. You will then be expected to either retract a submission, or to find alternative package maintainers. You can also discuss maintenance issues in the rOpenSci slack workspace. - Once your package is approved, we will provide further instructions about the transfer of your repository to the rOpenSci repository. diff --git a/softwarereview_author.es.Rmd b/softwarereview_author.es.Rmd index 85dfecbd8..16976e125 100644 --- a/softwarereview_author.es.Rmd +++ b/softwarereview_author.es.Rmd @@ -47,7 +47,7 @@ Esta guía condensa el proceso de revisión por pares desde el punto de vista de - Una persona realizará la [edición](#editors) y revisará tu envío en un plazo de 5 días laborables y te responderá con los siguientes pasos a seguir. Puede asignar el paquete a personas para que lo revisen, solicitar que el paquete se actualice para cumplir los criterios mínimos antes de la revisión, o rechazar el paquete porque el mismo no encaja en rOpenSci o porque se solapa con uno ya existente. - Si tu paquete cumple con los criterios mínimos, se le asignará de 1 a 3 personas para hacer la revisión, a quienes se les pedirá proporcionar revisiones en forma de comentarios sobre tu *issue* en un plazo máximo de 3 semanas. -- Te pedimos que respondas a estos comentarios en un plazo máximo de 2 semanas desde la última revisión presentada, pero puedes actualizar tu paquete o responder en cualquier momento. Tu respuesta debe incluir un enlace a la actualización del archivo [*NEWS.md*](#news) de tu paquete. Aquí tienes [un ejemplo de respuesta](https://github.com/ropensci/software-review/issues/593#issuecomment-1714421144). Fomentamos las conversaciones continuas entre quienes envían el paquete y quienes lo revisan. Consulta la [guía de revisión](#reviewerguide) para más detalles. +- Te pedimos que respondas a estos comentarios en un plazo máximo de 2 semanas desde la última revisión presentada, pero puedes actualizar tu paquete o responder en cualquier momento. Tu respuesta debe incluir un enlace a la actualización del archivo [*NEWS.md*](#news) de tu paquete. Aquí tienes [un ejemplo de respuesta](https://github.com/ropensci/software-review/issues/593#issuecomment-1714421144). Una vez hayas respondido, [enviala a nuestra base de datos usando nuestro bot](/es/bot_cheatsheet.es#submit-response-to-reviewers). Animamos a la continuación de conversaciones entre autores y revisores. Consulta la [guía de revisión](#reviewerguide) para más detalles. - Si algún cambio en el paquete puede modificar los resultados de [`pkgcheck`](https://docs.ropensci.org/pkgcheck), se puede solicitar un nuevo chequeo con el comando `@ropensci-review-bot check package`. - Por favor, notifícanos inmediatamente si ya no puedes mantener tu paquete o responder a las revisiones. En ese caso, se espera que retractes el envío o que encuentres responsables alternativos para mantener del paquete. También puedes discutir los problemas de mantenimiento en el Slack de rOpenSci. - Una vez que tu paquete sea aceptado, te proporcionaremos más instrucciones sobre la transferencia de tu repositorio al repositorio de rOpenSci. diff --git a/softwarereview_editor.Rmd b/softwarereview_editor.Rmd index f37c5bac7..56246aaa4 100644 --- a/softwarereview_editor.Rmd +++ b/softwarereview_editor.Rmd @@ -6,8 +6,9 @@ aliases: # Guide for Editors {#editorguide} ```{block, type="summaryblock"} -Software Peer Review at rOpenSci is managed by a team of editors. We are piloting -a system of a rotating Editor-in-Chief (EiC). +Software Peer Review at rOpenSci is managed by a team of editors. +The Editor-in-Chief (EiC) role is rotated (generally quarterly) amongst experienced members of our editorial board. +Information on current and recent editors and their activities can be viewed on our editorial dashboard at [dashboard.ropensci.org](https://dashboard.ropensci.org). This chapter presents the responsabilities [of the Editor-in-Chief](#eicchecklist), of [any editor in charge of a submission](#editorchecklist), [how to respond to an out-of-scope submission](#outofscoperesponse) and [how to manage a dev guide release](#bookrelease). @@ -20,32 +21,28 @@ If you're a guest editor, thanks for helping! Please contact the editor who invi - In addition to handling packages (about 4 a year), editors weigh in on group editorial decisions, such as whether a package is in-scope, and determining updates to our policies. We generally do this through Slack, which we expect editors to be able to check regularly. -- We also rotate [Editor-in-Chief responsibilities](#eicchecklist) (first-pass scope decisions and assigning editors) amongst the board about quarterly. - -- You do not have to keep track of other submissions, but if you do notice an issue with a package that is being handled by another editor, feel free to raise that issue directly with the other editor, or post the concern to editors-only channel on slack. Examples: +- You only need to keep track of your own submissions, but if you do notice an issue with a package that is being handled by another editor, feel free to raise that issue directly with the other editor, or post the concern to editors-only channel on slack. Examples: - You know of an overlapping package, that hasn't been mentioned in the process yet. - - You see a question to which you have an expert answer that hasn't been given after a few days (e.g. you know of a blog post tackling how to add images to package docs). - - Concerns related to e.g. the speed of the process should be tackled by the editor-in-chief so that's who you'd turn to for such questions. + - You see a question to which you have an expert answer that hasn't been given after a few days (such as linking to a blog post which may answer a question). + - Concerns related to general review progress, including aspects such as the speed of the process, should be directed to the current Editor-in-Chief. ## Handling Editor's Checklist {#editorchecklist} ### Upon submission: {#upon-submission} -- If you're the EiC or the first editor to respond, assign an editor with a comment of `@ropensci-review-bot assign @username as editor`. This will also add tag `1/editor-checks` to the issue. -- For statistical submissions (identifiable as "Submission Type: Stats" in issue template), add the "stats" label to the issue. -- Submission will automatically generate package check output from ropensci-review-bot which should be examined for any outstanding issues (most exceptions will need to be justified by the author in the particular context of their package.). If you want to re-run checks after any package change post a comment `@ropensci-review-bot check package`. +- Submission will automatically generate package check output from ropensci-review-bot. The check results should be examined for any outstanding issues (most exceptions will need to be justified by the author in the particular context of their package). Checks can be re-run after any package change with the comment `@ropensci-review-bot check package`. +- For statistical submissions (identifiable as "Submission Type: Stats" in issue template), add the "stats" label to the issue (if not already added). +- Check that issue template has been properly filled out. Most common oversights and omissions should be caught and noted by the bot, but a manual check always helps. Editors can edit templates directly for minor fixes, or may direct authors to fill any mandatory template fields that may be missing. - The checking system is rebuilt at every Tuesday at 00:01 UTC, and can take a couple of hours. If automatic checks fail around that time, wait a few hours and try again. - After automatic checks are posted, use the [editor template](#editortemplate) to guide initial checks and record your response to the submission. You can also streamline your editor checks by using the [`pkgreviewr` package created by associate editor Anna Krystalli](https://docs.ropensci.org/pkgreviewr/articles/editors.html). Please strive to finish the checks and start looking for reviewers within 5 working days. -- Check that template has been properly filled out. - Check against policies for [fit](#aims-and-scope) and [overlap](#overlap). Initiate discussion via Slack #software-review channel if needed for edge cases that haven't been caught by previous checks by the EiC. If reject, see [this section](#outofscoperesponse) about how to respond. -- Check that mandatory parts of template are complete. If not, direct authors toward appropriate instructions. -- For packages needing continuous integration on multiple platforms (cf [criteria in this section of the CI chapter](#whichci)) make sure the package gets tested on multiple platforms (having the package built on several operating systems via GitHub Actions for instance). -- Wherever possible when asking for changes, direct authors to automatic tools such as [`usethis`](https://usethis.r-lib.org/) and [`styler`](https://styler.r-lib.org/), and to online resources (sections of this guide, sections of the [R packages book](https://r-pkgs.org/)) to make your feedback easier to use. [Example of editor's checks](https://github.com/ropensci/software-review/issues/207#issuecomment-379909739). -- Ideally, the remarks you make should be tackled before reviewers start reviewing. -- If initial checks show major gaps, request changes before assigning reviewers. If the author mentions changes might take time, [apply the holding label via typing `@ropensci-review-bot put on hold`](#policiesreviewprocess). You'll get a reminder every 90 days (in the issue) to check in with the package author(s). +- Ensure that the package gets tested on multiple platforms (having the package built on several operating systems via GitHub Actions for instance; see [criteria in this section of the CI chapter](#whichci) for further details and options). +- Wherever possible when asking for changes, direct authors to automatic tools such as [`usethis`](https://usethis.r-lib.org/) and [`styler`](https://styler.r-lib.org/), and to online resources (sections of this guide, sections of the [R packages book](https://r-pkgs.org/)) to make your feedback easier to use. See this [example of editor's checks](https://github.com/ropensci/software-review/issues/207#issuecomment-379909739). +- Ideally, any remarks you make as editor should be addressed before assigning reviewers. +- If initial checks show major gaps, request changes before assigning reviewers. If the author mentions changes might take time, [apply the holding label by calling `@ropensci-review-bot put on hold`](#policiesreviewprocess). You'll get a reminder in the issue every 90 days to check in with the package author(s). - If the package raises a new issue for rOpenSci policy, start a conversation in Slack or open a discussion on the [rOpenSci forum](https://discuss.ropensci.org/) to discuss it with other editors ([example of policy discussion](https://discuss.ropensci.org/t/overlap-policy-for-package-onboarding/368)). ### Look for and assign two reviewers: {#look-for-and-assign-two-reviewers} @@ -114,7 +111,7 @@ Each submission should be reviewed by *two* package reviewers. Although it is fi ### After review: {#after-review} - `@ropensci-review-bot approve ` -- *If the original repository owner opposes transfer, add a line with its address to [this repos list](https://github.com/ropensci/roregistry/blob/gh-pages/info/not_transferred.json) to ensure the package gets included in rOpenSci package registry.* +- *If the original repository wishes to keep the package in their own GitHub organization rather than transfer to ropensci, add a line with the repository URL to [this repos list](https://github.com/ropensci/roregistry/blob/gh-pages/info/not_transferred.json) to ensure the package gets included in rOpenSci package registry.* - Nominate a package to be featured in an rOpenSci blog post or tech note if you think it might be of high interest. Please note in the software review issue one or two things the author could highlight, and tag `@ropensci/blog-editors` for follow-up. - If authors maintain a gitbook that is at least partly about their package, contact [an rOpenSci staff member](https://ropensci.org/about/#team) so they might contact the authors @@ -126,48 +123,55 @@ Each submission should be reviewed by *two* package reviewers. Although it is fi ## EiC Responsibilities {#eicchecklist} -The EiC serves for 3 months or a time agreed to by all members of the editorial board. -The EiC is entitled to taking scope and overlap decisions as independently as possible (but can still request help/advice). -In details, the EiC plays the following roles +Rotating Editors-in-Chief (EiCs) generally serve for 3 months or a time agreed to by all members of the editorial board. +The EiC is entitled to taking scope and overlap decisions as independently as possible (but can still request help and advice). +Information on current status of all editorial team members is presented on our [*Editorial Dashboard*](https://dashboard.ropensci.org). +The EiC is responsible for the following tasks: + +- On assuming EiC rotation, reviewing the status of current open reviews as detailed on the [*Dashboard* page](https://dashboard.ropensci.org/reviews.html), and issuing reminders to other editors or package authors as needed. See [the following sub-section for more details](#eic-dashboard) -- Watches all issues posted to the software-review repo (either subscribe to repo notifications on GitHub, or watch the `#software-peer-review-feed` channel on Slack). +- Watching all new issues posted to the software-review repo, for which the EiC must either subscribe to repo notifications on GitHub, or watch the `#software-peer-review-feed` channel on Slack. -- Tags issue with ` 0/editorial-team-prep` +- Tagging each new full submission with ` 0/editorial-team-prep` -- Calls `@ropensci-review-bot check srr` on pre-submission enquiries for statistical software. See corresponding [*Stats Dev Guide* chapter](https://stats-devguide.ropensci.org/pkgsubmission.html#editor-in-chief) for details. +- Calling `@ropensci-review-bot check srr` on pre-submission enquiries for statistical software. See corresponding [*Stats Dev Guide* chapter](https://stats-devguide.ropensci.org/pkgsubmission.html#editor-in-chief) for details. -- Assigns package submissions to other editors, including self, to handle. Mostly this just rotates among editors, unless the EiC thinks an editor is particularly suited to a package, or an editor declines handling the submission due to being too busy or because of conflicting interests. +- Finding an editor (potentially including yourself) to handle each submission. Currently available editors are indicated on the [*Editorial Dashboard*](https://dashboard.ropensci.org), and editorial workloads should be distributed as evenly as possible, through referring to the [*Dashboard* charts of recent editorial load](https://dashboard.ropensci.org/editors.html#past-ed-load). +- Assigning editors by issuing the command: ``` @ropensci-review-bot assign @username as editor ``` + This will also add tag `1/editor-checks` to the issue. -- Regularly (for instance weekly) monitors pace of review process thanks to [devguider](#eic-report) and reminds other editors to move packages along as needed. +- Regularly (for instance weekly) monitoring the pace of all open reviews by keeping an eye on the [*Dashboard* page](https://dashboard.ropensci.org/reviews.html), and reminding other editors to move packages along as needed. -- On assuming EiC rotation, reviews status of current open reviews thanks to [devguider](#eic-report) and reminds editors to respond or update status as needed. +- Responding to issues posted to [the software-review-meta repo -- Responds to issues posted to the software-review-meta repo - -- Makes decisions on scope/overlap for pre-submission inquiries, referrals from JOSS or other publication partners, and submissions if they see an ambiguous case (This last case may also be done by handling editors (see below)). To initiate discussion, this is posted to the rOpenSci Slack editors-only channel along with a small summary of what the (pre-)submitted/referred submission is about, what doubts the EiC has i.e. digesting information a bit. If after one day or two the EiC feels they haven't received enough answers, they can ping all editors. +- Making decisions on scope and overlap for pre-submission inquiries, referrals from JOSS or other publication partners, and submissions. Discussions should be initiated in the rOpenSci Slack editors-only channel through summarising the (pre-)submitted/referred software, along with any concerns the EiC might have. If after the EiC feels they haven't received enough answers after a day or two, they can ping all editors. - Any editor should feel free to step in on these. See [this section](#outofscoperesponse) about how to respond to out-of-scope (pre-) submissions. - - After explaining the out-of-scope decision, write an issue comment `@ropensci-review-bot out-of-scope`. - -- Requests a new EiC when their rotation is up (set a calendar reminder ahead of your expected end date and ask for volunteers in the editors' Slack channel) + - After explaining an out-of-scope decision, write an issue comment `@ropensci-review-bot out-of-scope`. -### Using `devguider::devguide_eic_report()` {#eic-report} +### The rOpenSci Editorial Dashboard {#eic-dashboard} -Install devguider and run `devguider::devguide_eic_report()`, open the HTML report in a browser. +The [*rOpenSci Editorial Dashboard*](https://dashboard.ropensci.org) is updated daily, primary by extracting information on all software review issues on GitHub, along with additional information from Slack and our Airtable database. +The dashboard provides an up-to-date overview of our editorial team, their recent reponsibilities, and the current state of all software review issues. +The EiC (or any editors who are interested) can gain an overview of the editorial team status, availability, and recent workloads on [the *editors* page](https://dashboard.ropensci.org/editors.html). +This should be used to find and assign editors for new software review issues. +An overview of all current software reviews is on [the **Software Review* page](https://dashboard.ropensci.org/reviews.html). +Entries on this page are colored by a measure of "urgency", summarised in the [table at the bottom of that page](https://dashboard.ropensci.org/reviews.html#urgency-of-reviews). -- Look over submissions in "presubmission" and "editorial-team-prep". Check whether any action needs to be taken (polling editors, making a decision, putting the issue on hold, pinging the submitter for an update, finding and assigning an editor). +Specific tasks for reviews in the specific review stages include: -- Rows in each section are colored by "urgency" from white (ignore) to yellow (not urgent) to red (most urgent). +- Looking over submissions in "0\/presubmission" and "1\/editorial-team-prep", to check whether any action needs to be taken (such as polling editors, making decisions, putting issues on hold, pinging for updates, or finding and assigning editors). -- Look over submissions in "seeking-reviewer(s)". If the reviewer search has been going for unusually long (red color), check whether the submission is on hold, read the thread to gather context, and contact the editor in private to ask for more information / whether the submission fell through the cracks. +- Looking over submissions in "2\/seeking-reviewer(s)" to ensure things are progressing quickly. +If the reviewer search has been going for unusually long (red color), check whether the submission is on hold, read the thread to gather context, and contact the editor in private to ask for more information. -- Look over submissions in "reviewer(s)-assigned". If there are still missing reviews after an unusually long time (red color), check whether the submission is on hold, read the thread to gather context, and contact the editor in private to ask for more information / whether the submission fell through the cracks. +- Looking over submissions in "3\/reviewer(s)-assigned". If there are still missing reviews after an unusually long time (red color), check whether the submission is on hold, read the thread to gather context, and contact the editor in private to ask for more information. -- Look over submissions in "review(s)-in-awaiting-changes". If some are still lacking an author response after an unusually long time (red color), check whether the submission is on hold, read the thread, and contact the editor in private to ask for more information / whether the submission fell through the cracks. +- Looking over submissions in "4\/review(s)-in-awaiting-changes". If some are still lacking an author response after an unusually long time (red color), check whether the submission is on hold, read the thread, and contact the editor in private to ask for more information. ### Asking for more details {#asking-for-more-details} diff --git a/softwarereview_intro.Rmd b/softwarereview_intro.Rmd index 47821e5ab..97a098dd6 100644 --- a/softwarereview_intro.Rmd +++ b/softwarereview_intro.Rmd @@ -20,7 +20,7 @@ Technically, we make the most of [GitHub](https://github.com/) infrastructure: e - First, and foremost, we hope you submit your package for review **because you value the feedback**. We aim to provide useful feedback to package authors and for our review process to be open, non-adversarial, and focused on improving software quality. - Once aboard, your package will continue to receive **support from rOpenSci members**. You'll retain ownership and control of your package, but we can help with ongoing maintenance issues such as those associated with updates to R and dependencies and CRAN policies. -- rOpenSci will **promote your package** through our [webpage](https://ropensci.org/packages/), [blog](https://ropensci.org/blog/), and social media (like [Mastodon](https://fosstodon.org/@ropensci) and [Twitter](https://twitter.com/ropensci)). Packages in our suite also get a [documentation website that is automatically built and deployed after each push](#docsropensci). +- rOpenSci will **promote your package** through our [webpage](https://ropensci.org/packages/), [blog](https://ropensci.org/blog/), and social media (like [Mastodon](https://fosstodon.org/@ropensci) and [LinkedIn](https://www.linkedin.com/company/ropensci/)). Packages in our suite also get a [documentation website that is automatically built and deployed after each push](#docsropensci). - rOpenSci **packages can be cross-listed** with other repositories such as CRAN and BioConductor. - rOpenSci packages that are in scope for the [Journal of Open-Source Software](https://joss.theoj.org/) and add the necessary accompanying short paper, would, at the discretion of JOSS editors, benefit from a fast-tracked review process. - If you write one, rOpenSci will **promote gitbooks related to your package**: the source of such books can be transferred to [the `ropensci-books` GitHub organisation](https://github.com/ropensci-books) for books to be listed [at books.ropensci.org](https://books.ropensci.org/). diff --git a/softwarereview_intro.es.Rmd b/softwarereview_intro.es.Rmd index eb9005cb3..e42592ca4 100644 --- a/softwarereview_intro.es.Rmd +++ b/softwarereview_intro.es.Rmd @@ -29,7 +29,7 @@ Además, utilizamos funcionalidades de GitHub como las plantillas de *issues* (c - En primer lugar, y sobre todo, esperamos que envíes tu paquete para su revisión **porque valoras la devolución**. Nuestro objetivo es proporcionar una devolución útil a las personas que crearon el paquetes y que nuestro proceso de revisión sea abierto, no conflictivo y centrado en la mejora de la calidad del software. - Una vez a aceptado, tu paquete seguirá recibiendo **apoyo de los miembros de rOpenSci**. Mantendrás la propiedad y el control de tu paquete, pero podemos ayudarte con los problemas de mantenimiento continuo, como los relacionados con las actualizaciones de R y las dependencias, y las políticas de CRAN. -- rOpenSci **promoverá tu paquete** a través de nuestra [página web](https://ropensci.org/packages/), [blog](https://ropensci.org/blog/) y redes sociales (como [Mastodon](https://fosstodon.org/@ropensci) y [Twitter](https://twitter.com/ropensci)). Los paquetes de nuestra suite también tienen un [sitio web de documentación que se construye y despliega automáticamente después de cada *push*](#docsropensci). +- rOpenSci **promoverá tu paquete** a través de nuestra [página web](https://ropensci.org/packages/), [blog](https://ropensci.org/blog/) y redes sociales (como [Mastodon](https://fosstodon.org/@ropensci) y [LinkedIn](https://www.linkedin.com/company/ropensci/)). Los paquetes de nuestra suite también tienen un [sitio web de documentación que se construye y despliega automáticamente después de cada *push*](#docsropensci). - Los paquete de rOpenSci **se pueden incluir** en otros repositorios como CRAN y BioConductor. - Los paquetes de rOpenSci que son relevantes para el [Journal of Open-Source Software](https://joss.theoj.org/) y añaden un artículo corto de acompañamiento pueden beneficiarse, a discreción del equipo editorial de JOSS, de un proceso de revisión acelerado. - Si escribes un ***gitbook* relacionado a tu paquete**, rOpenSci lo difundirá: se puede transferir su código fuente a [la organización de GitHub `ropensci-books`](https://github.com/ropensci-books) para ser listado en [books.ropensci.org](https://books.ropensci.org/). diff --git a/softwarereview_policies.Rmd b/softwarereview_policies.Rmd index 58e205852..3f1cb8bc9 100644 --- a/softwarereview_policies.Rmd +++ b/softwarereview_policies.Rmd @@ -40,7 +40,7 @@ Last but not least, you'll find the [code of conduct of rOpenSci Software Peer R Following criteria are meant to be a guide for what constitutes a conflict of interest for an editor or reviewer. The potential editor or reviewer has a conflict of interest if: - The potential reviewer/editor are from the same institution or institutional component (e.g., department) as any author with a major role. -- The potential reviewer/editor has been a collaborator or has had other professional relationships with at least one person on the package who has a major role within in the past three year. +- The potential reviewer/editor has been a collaborator or has had other professional relationships with at least one person on the package who has a major role within in the past three years. - The potential reviewer/editor serves, or has served, as a member of the advisory board for the project under review. - The potential reviewer/editor would receive a direct or indirect financial benefit if the package were accepted. - The potential reviewer/editor has significantly contributed to a competitor project. diff --git a/softwarereview_reviewer.Rmd b/softwarereview_reviewer.Rmd index b4cfc77b8..051f801c2 100644 --- a/softwarereview_reviewer.Rmd +++ b/softwarereview_reviewer.Rmd @@ -82,7 +82,7 @@ First-time reviewers may find it helpful to read (about) some previous reviews. You can read blog posts written by reviewers about their experiences [via this link](https://ropensci.org/tags/reviewer/). In particular, in [this blog post by Mara Averick](https://ropensci.org/blog/2017/08/22/first-package-review/) read about the "naive user" role a reviewer can take to provide useful feedback even without being experts of the package's topic or implementation, by asking themselves *"What did I think this thing would do? Does it do it? What are things that scare me off?"*. In [another blog post](https://ropensci.org/blog/2017/09/08/first-review-experiences/) Verena Haunschmid explains how she alternated between using the package and checking its code. -As both a former reviewer and package author [Adam Sparks](https://adamhsparks.netlify.app/) [wrote this](https://twitter.com/adamhsparks/status/898132036451303425) "\[write\] a good critique of the package structure and best coding practices. If you know how to do something better, tell me. It's easy to miss documentation opportunities as a developer, as a reviewer, you have a different view. You're a user that can give feedback. What's not clear in the package? How can it be made more clear? If you're using it for the first time, is it easy? Do you know another R package that maybe I should be using? Or is there one I'm using that perhaps I shouldn't be? If you can contribute to the package, offer." +As both a former reviewer and package author, and now editor, [Adam Sparks](https://adamhsparks.netlify.app/) wrote "\[write\] a good critique of the package structure and best coding practices. If you know how to do something better, tell me. It's easy to miss documentation opportunities as a developer, as a reviewer, you have a different view. You're a user that can give feedback. What's not clear in the package? How can it be made more clear? If you're using it for the first time, is it easy? Do you know another R package that maybe I should be using? Or is there one I'm using that perhaps I shouldn't be? If you can contribute to the package, offer." ### Helper package for reviewers {#helper-package-for-reviewers} diff --git a/softwarereview_reviewer.pt.Rmd b/softwarereview_reviewer.pt.Rmd index 1dcddaaa8..ec58c76bd 100644 --- a/softwarereview_reviewer.pt.Rmd +++ b/softwarereview_reviewer.pt.Rmd @@ -1,91 +1,81 @@ ---- -aliases: reviewerguide.html ---- -# Guia para revisores {#reviewerguide} +# Guia para Revisores {#reviewerguide} ```{block, type="summaryblock"} -Obrigado por você ter aceitado 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. +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. -Esforce-se para concluir sua avaliação em até 3 semanas após a aceitação da solicitação de avaliação. Procuraremos lembrar os revisores das datas de vencimento futuras e passadas. Os editores podem designar -Os editores podem designar revisores adicionais ou alternativos se uma revisão estiver excessivamente atrasada. +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 o [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. +**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 padrões/listas de verificação etc. ao revisar um software em outro lugar, informe aos destinatários (por exemplo, editores de periódicos, estudantes, revisão interna de código) que eles 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/). +_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/)._ ``` -## Como voluntário como revisor {#volunteering-as-a-reviewer} +## Voluntariando como revisor {#volunteering-as-a-reviewer} -Obrigado pelo seu desejo de participar da revisão por pares do software rOpenSci como revisor! +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). +Por favor preencha nosso [formulário de voluntariado](https://ropensci.org/software-reviewer). -Se você vir um envio atual que seja particularmente relevante para 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, e é bem possível que o editor já tenha enviado um e-mail para as pessoas. -Não se voluntarie para todas as edições e não se voluntarie por meio da interface do GitHub. +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 [Guia de contribuição do rOpenSci](https://contributing.ropensci.org/). +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`. Observe que, ao instalar o pacote para revisá-lo, você deve se certificar de que tem todas as dependências disponíveis (por exemplo, execute `pak::pak()`). +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 usá-lo como uma lista de verificação de alto nível. Além de marcar os critérios mínimos, pedimos que você forneça comentários gerais abordando o seguinte: +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á de acordo com os requisitos do [guia de embalagem da rOpenSci](#building)? -- Você acha que há melhorias que poderiam ser feitas no estilo do código? +- 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? -- Você poderia fazer melhorias no desempenho? -- A documentação (instruções de instalação/vinhetas/exemplos/demonstrações) é clara e suficiente? Você usa o princípio de *vários pontos de entrada* ou seja, 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? +- 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 arestas e casos de uso nos quais o autor não pensou. +- 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. -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 tópico de envio para informá-lo sobre possíveis atrasos. +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: +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 de testes é justificada (por exemplo `skip_on_cran()` 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 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 terá que pesquisar o pacote localmente, pois a pesquisa no GitHub é limitada ao branch padrão. Além disso, a documentação hospedada em um branch `pkgdown` não está necessariamente atualizada, e recomendamos que você inspecione a documentação do pacote localmente, executando `pkgdown::build_site()`. +- 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: `@ropensci-review-bot check package`. +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 fora da linha {#off-thread-interactions} +### Interações em outros contextos {#off-thread-interactions} -Se você interagiu com os autores do pacote e falou sobre a revisão fora de um tópico de revisão (em chats, mensagens diretas, pessoalmente, problemas 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. +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} -Os avaliadores iniciantes podem achar útil ler (sobre) algumas avaliaçõ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 avaliações (observe que suas avaliações não precisam ser tão longas quanto esses exemplos): +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). +- `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 avaliação) +- `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 avaliadores sobre suas experiências [por meio deste link](https://ropensci.org/tags/reviewer/). Em particular, em [esta 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, perguntando a si mesmo *"O que eu achava 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. +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. -Como ex-revisora e autora do 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ê souber 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 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." +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 o fluxo de trabalho de revisão usando o pacote [`pkgreviewr` pacote](https://github.com/ropensci-org/pkgreviewr) criado pela editora associada Anna Krystalli. Digamos que você tenha aceitado revisar o `refnet` pacote, você escreveria +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") @@ -96,25 +86,25 @@ pkgreview_create(pkg_repo = "embruna/refnet", e -- o repositório do GitHub do `refnet` 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 a revisão. +- 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). +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 no pacote software-review issue. -- Outros comentários 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 de pacotes, 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. +- 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 avaliação {#followupreviewer} +## Acompanhamento da revisão {#followupreviewer} -Os autores devem responder dentro de duas semanas com as alterações feitas no pacote em resposta à 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 de revisão. +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á a seção [modelo de aprovação](#approval2template). +Você usará o [modelo de aprovação](#approval2template). diff --git a/templates/news.pt.md b/templates/news.pt.md new file mode 100644 index 000000000..5d9a562d2 --- /dev/null +++ b/templates/news.pt.md @@ -0,0 +1,35 @@ +foobar 0.2.0 (2016-04-01) +========================= + +### NOVAS FUNCIONALIDADES + + * Nova função adicionada `do_things()` para fazer coisas (#5) + +### MELHORIAS PEQUENAS + + * Documentação foi aprimorada para a função `things()` (#4) + +### CORREÇÕES DE BUGS + + * Correção de um bug de parseamento em `parse()` (#3) + +### DEPRECADO E EXTINTO + + * `hello_world()` está deprecada agora e será removida em + uma futura versão, utilize `hello_mars()` + +### CORREÇÕES EM DOCUMENTAÇÃO + + * Papel de `hello_mars()` versus `goodbye_mars()` está melhor esclarecido. + + +### (um especial: qualquer cabeçalho que agrupa um número grande de mudanças sobre uma única coisa) + + * blablabla. + +foobar 0.1.0 (2016-01-01) +========================= + +### NOVAS FUNCIONALIDADES + + * lançamento no CRAN diff --git a/templates/request.pt.md b/templates/request.pt.md new file mode 100644 index 000000000..c559a2d59 --- /dev/null +++ b/templates/request.pt.md @@ -0,0 +1,27 @@ +Caro [REVISOR(A)] + +Olá, aqui é [EDITOR(A)]. [BRINCADEIRA AMIGÁVEL]. Estou escrevendo para perguntar se você gostaria de revisar um pacote para a rOpenSci. Como você provavelmente sabe, a rOpenSci realiza revisão por pares de pacotes de R contribuídos para nossa coleção, de maneira semelhante aos periódicos. + +O pacote, [PACOTE] de [AUTOR(ES)], faz [FUNÇÃO]. Você pode encontrá-lo no GitHub aqui: [LINK PARA REPOSITÓRIO]. Também conduzimos nosso processo de revisão aberta via GitHub, aqui: [ISSUE DE ONBOARDING] + +Se você aceitar, observe que pedimos aos revisores que concluam as avaliações em três semanas. (Descobrimos que a revisão de um pacote leva um tempo semelhante ao de um trabalho acadêmico.) + +Nosso [guia para revisores] detalha o que procuramos em uma revisão de pacote e inclui links para exemplos de revisão. Nossos padrões estão detalhados em nosso [guia de pacotes] e fornecemos um [modelo] de revisão para você usar. Certifique-se de que não haja um [conflito de interesses](https://devguide.ropensci.org/policies.html#coi) que lhe impeça de revisar este pacote. Se você tiver dúvidas ou comentários, sinta-se à vontade para me perguntar ou postar no [fórum da rOpenSci]. + +A comunidade da rOpenSci é o nosso melhor ativo. Nosso objetivo é que as revisões sejam abertas, não adversas e focadas na melhoria da qualidade do software. Seja respeitoso(a) e gentil! Consulte nosso guia para revisores e o nosso [código de conduta](https://ropensci.org/code-of-conduct/) para mais informações. + + +[SE MENTORIA FOR REQUISITADA: Você indicou em seu formulário que prefere ter uma orientação para sua primeira revisão. Você é livre para me usar como recurso durante esse processo, incluindo fazer perguntas por e-mail e Slack (você receberá um convite para o Slack da rOpenSci) e compartilhar os rascunhos de sua revisão para feedback antes de postá-los. Também estarei feliz de fazer uma breve videochamada para lhe explicar o processo. Por favor, me avise em sua resposta se você deseja agendar uma videochamada dessas.] + +Você consegue revisar? Caso não consiga, você tem alguma sugestão de revisor(a)? Se eu não receber uma resposta sua dentro de uma semana, vou presumir que você não pode revisar neste momento. + +Agradeço pelo seu tempo. + +Atenciosamente + +[EDITOR(A)] + +[guia para revisores]: https://devguide.ropensci.org/reviewerguide.html +[guia para pacotes]: https://devguide.ropensci.org/building.html +[modelo]: https://devguide.ropensci.org/reviewtemplate.html +[fórum da rOpenSci]: https://discuss.ropensci.org/ diff --git a/templates/review.pt.md b/templates/review.pt.md new file mode 100644 index 000000000..faadefe2e --- /dev/null +++ b/templates/review.pt.md @@ -0,0 +1,42 @@ +--- +title: "review" +output: + rmarkdown::md_document: + pandoc_args: [ + "--wrap=none" + ] +--- + +## Revisão do pacote + +*Marque as caixas conforme aplicável e elabore nos comentários abaixo. Sua avaliação não se limita a estes tópicos, conforme descrito no guia do(a) revisor(a)* + +- **Descreva resumidamente qualquer relacionamento de trabalho que você tem (teve) com as pessoas autoras do pacote.** +- [ ] Como revisor(a), confirmo que não há [conflitos de interesse](https://devguide.ropensci.org/policies.html#coi) para que eu revise este trabalho (se você não tiver certeza se está em conflito, fale com seu(sua) editor(a) _antes_ de iniciar sua revisão) + +#### Documentação + +O pacote inclui todas as seguintes formas de documentação: + +- [ ] **Uma declaração de necessidade:** declarando claramente os problemas que o software foi projetado para resolver além do seu público-alvo no README +- [ ] **Instruções de instalação:** para a versão de desenvolvimento do pacote e quaisquer dependências que sejam fora do padrão no README +- [ ] **Vignette(s):** demonstrando as principais funcionalidades com exemplos que são executados localmente com sucesso +- [ ] **Documentação de funções:** para todas as funções exportadas +- [ ] **Exemplos:** (que são executados localmente com sucesso) para todas as funções exportadas +- [ ] **Diretrizes da comunidade:** incluindo diretrizes de contribuição no README ou CONTRIBUTING, e DESCRIPTION com `URL`, `BugReports` e `Maintainer` (o qual pode ser gerado automaticamente via `Authors@R`). + +#### Funcionalidade + +- [ ] **Instalação:** Processo de instalação documentado conclui com sucesso. +- [ ] **Funcionalidade:** Qualquer funcionalidade que foi assumida pelo software foi confirmada. +- [ ] **Desempenho:** Qualquer desempenho a mais que foi assumido pelo software foi confirmado. +- [ ] **Testes automatizados:**Os testes unitários cobrem funções essenciais do pacote e uma gama razoável de *inputs* e condições. Todos os testes passam na máquina local. +- [ ] **Diretrizes de empacotamento**: O pacote está em conformidade com as diretrizes de empacotamento da rOpenSci. + +Horas estimadas gastas na revisão: + +- [ ] Caso as pessoas autoras do pacote considerem apropriado, concordo em ser reconhecido(a) como revisor(a) do pacote (função "rev") no arquivo DESCRIPTION do pacote. + +--- + +### Comentários da revisão