diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 000000000..71ca925ec --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,4 @@ +*.pt.Rmd @ropensci/pt-translators +*.pt.qmd @ropensci/pt-translators +*.es.Rmd @ropensci/es-translators +*.es.qmd @ropensci/es-translators diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..adee0ed14 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "monthly" \ No newline at end of file diff --git a/.github/workflows/dev.yml b/.github/workflows/dev.yml index c3d2df725..d4a39a4c4 100644 --- a/.github/workflows/dev.yml +++ b/.github/workflows/dev.yml @@ -15,7 +15,7 @@ jobs: name: Render-Book runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - uses: r-lib/actions/setup-r@v2 @@ -35,8 +35,10 @@ jobs: - name: Render book run: Rscript -e 'babelquarto::render_book()' env: # Set the secret as an input + AIRTABLE_ID: ${{ secrets.AIRTABLE_ID }} AIRTABLE_API_KEY: ${{ secrets.AIRTABLE_API_KEY }} ZENODO_TOKEN: ${{ secrets.ZENODO_TOKEN }} + BABELQUARTO_CI_URL: https://devdevguide.netlify.app - name: Move English files run: Rscript -e 'file.copy(from = "_book/rOpenSci-Packages--Development,-Maintenance,-and-Peer-Review.pdf", to = "_book/ropensci-dev-guide.pdf")' -e 'purrr::walk(list.files("images", full.names = TRUE), file.copy, to = "_book/images")' diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index da91510b6..e06b30226 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -18,7 +18,7 @@ jobs: run: | fork=$(jq --raw-output .pull_request.head.repo.fork "${GITHUB_EVENT_PATH}");echo "fork=${fork}" >> $GITHUB_ENV - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - uses: r-lib/actions/setup-r@v2 @@ -37,8 +37,10 @@ jobs: - name: Render book run: Rscript -e 'babelquarto::render_book()' env: # Set the secret as an input + AIRTABLE_ID: ${{ secrets.AIRTABLE_ID }} AIRTABLE_API_KEY: ${{ secrets.AIRTABLE_API_KEY }} ZENODO_TOKEN: ${{ secrets.ZENODO_TOKEN }} + BABELQUARTO_CI_URL: "" - name: Move English files run: Rscript -e 'file.copy(from = "_book/rOpenSci-Packages--Development,-Maintenance,-and-Peer-Review.pdf", to = "_book/ropensci-dev-guide.pdf")' -e 'purrr::walk(list.files("images", full.names = TRUE), file.copy, to = "_book/images")' diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d3d5dc065..d32099f1d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -10,7 +10,7 @@ jobs: name: Render-Book runs-on: macOS-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - uses: r-lib/actions/setup-r@v2 @@ -29,6 +29,7 @@ jobs: - name: Render book run: Rscript -e 'babelquarto::render_book()' env: # Set the secret as an input + AIRTABLE_ID: ${{ secrets.AIRTABLE_ID }} AIRTABLE_API_KEY: ${{ secrets.AIRTABLE_API_KEY }} ZENODO_TOKEN: ${{ secrets.ZENODO_TOKEN }} diff --git a/.github/workflows/scheduled-manual-main.yml b/.github/workflows/scheduled-manual-main.yml index e956f7020..d2fd8c677 100644 --- a/.github/workflows/scheduled-manual-main.yml +++ b/.github/workflows/scheduled-manual-main.yml @@ -13,10 +13,10 @@ jobs: name: Render-Book runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 with: fetch-depth: 0 - + - name: Checkout latest release tag run: | LATEST_TAG=$(git describe --tags `git rev-list --tags --max-count=1`) @@ -39,6 +39,7 @@ jobs: - name: Render book run: Rscript -e 'babelquarto::render_book()' env: # Set the secret as an input + AIRTABLE_ID: ${{ secrets.AIRTABLE_ID }} AIRTABLE_API_KEY: ${{ secrets.AIRTABLE_API_KEY }} ZENODO_TOKEN: ${{ secrets.ZENODO_TOKEN }} diff --git a/booknews.Rmd b/booknews.Rmd index 1b9e57639..84cc6a532 100644 --- a/booknews.Rmd +++ b/booknews.Rmd @@ -1,5 +1,37 @@ # NEWS {#booknews} +## dev version + +- 2025-04-10, add link to pkgcheck vignette on our testing environment (#589) + +- 2025-04-10, replace the link to the Mozilla Code Review guide with explicit items (#835) + +- 2025-04-03, document how to put the system on vacation(#865) + +- 2025-04-03, add details about MEE process and structure the author guide a bit more (`@robitalec`, #862) + +- 2025-03-11, add note in the packaging guide about checking maintenance status of dependencies (#881) + +- 2025-03-11, add item about "top level code" in packaging guide (#879) + +- 2025-03-11, explicitly mention need to acknowledge authors of bundled code (#873) + +- 2025-03-27, add guidance for packages wrapping external software (#866) + +- 2025-02-25, add official rule on submitting one package at once only (`@maurolepore`, #876) + +- 2025-03-11, mention the Air formatting tool wherever we mention the styler package (#875) + +- 2025-02-25, require the default git branch to not be called master (#863) + +- 2024-09-06, update math guidance for pkgdown based on pkgdown's update (#838) + +- 2024-08-30, remove mention of Twitter since rOpenSci no longer maintains an active Twitter account (`@yabellini`, #827) + +- 2024-07-17, document dashboard in editors' chapter (`@mpadge`, #829) + +- 2024-06-27, document the author's submit response step in the author guide (`@jmaspons`, #832). + ## 0.9.0 - 2024-01-09, update roxygen2 wording (`@vincentvanhees`, #792). diff --git a/maintenance_collaboration.Rmd b/maintenance_collaboration.Rmd index 05eac3813..92a97c8ba 100644 --- a/maintenance_collaboration.Rmd +++ b/maintenance_collaboration.Rmd @@ -40,7 +40,7 @@ These and other templates will generally need to be modified for use with an rOp Modifying a generic contributing guide to add a personal touch also tends to make it look less generic and more sincere. Personal preferences in a contributing guide include: -- Style preferences? You might however prefer to make style a configuration (of [lintr](https://github.com/jimhester/lintr), [styler](https://styler.r-lib.org/)) or to [fix code style yourself](https://github.com/rstudio/blogdown/pull/432#pullrequestreview-368391904) especially if you don't use a popular code style like the [tidyverse coding style](https://style.tidyverse.org/). +- Style preferences? You might however prefer to make style a configuration (of [Air](https://posit-dev.github.io/air/), [styler](https://styler.r-lib.org/), [lintr](https://github.com/jimhester/lintr)) or to [fix code style yourself](https://github.com/rstudio/blogdown/pull/432#pullrequestreview-368391904) especially if you don't use a popular code style like the [tidyverse coding style](https://style.tidyverse.org/). - Infrastructure like roxygen2? @@ -57,7 +57,7 @@ CONTRIBUTING.md files can also describe how you acknowledge contributions (see [ We encourage you to direct feedback that is not a bug report or a feature request to [rOpenSci forum](https://discuss.ropensci.org/), after making sure you'd see such questions on the forum. Users can use the forum to ask questions about use and report their use cases, and you can subscribe to individual categories and tags to receive notifications about your package. Feel free to mention this in the docs of your package and/or the contributing guidelines/issue template. Please direct your users to tag posts with the package name. -Once a pull request is closer to being merged, you could use [a GitHub Actions PR workflow to style the code with styler](https://github.com/r-lib/actions/blob/master/examples/pr-commands.yaml). +Once a pull request is closer to being merged, you could style the code using [Air](https://posit-dev.github.io/air/) or [styler](https://styler.r-lib.org). ### Issue management {#issue-management} diff --git a/maintenance_collaboration.es.Rmd b/maintenance_collaboration.es.Rmd index 3cd27bec6..54fee0f87 100644 --- a/maintenance_collaboration.es.Rmd +++ b/maintenance_collaboration.es.Rmd @@ -33,7 +33,7 @@ Estas y otras plantillas generalmente tendrán que ser modificadas para su uso c Modificar una guía de contribución genérica para añadir un toque propio también tiende a hacer que parezca menos impersonal y más sincera. Las preferencias personales en una guía de contribución incluyen -- Preferencias de estilo. Sin embargo, puedes preferir que el estilo sea uno automático (a través de [lintr](https://github.com/jimhester/lintr) o [styler](https://styler.r-lib.org/)) o bien [arreglar el estilo de código por tu cuenta](https://github.com/rstudio/blogdown/pull/432#pullrequestreview-368391904) especialmente si no utilizas un estilo de código popular como el [estilo de código tidyverse](https://style.tidyverse.org/). +- Preferencias de estilo. Sin embargo, puedes preferir que el estilo sea uno automático (a través de [Air](https://posit-dev.github.io/air/), [styler](https://styler.r-lib.org/) o [lintr](https://github.com/jimhester/lintr)) o bien [arreglar el estilo de código por tu cuenta](https://github.com/rstudio/blogdown/pull/432#pullrequestreview-368391904) especialmente si no utilizas un estilo de código popular como el [estilo de código tidyverse](https://style.tidyverse.org/). - Infraestructura, como roxygen2. @@ -53,7 +53,7 @@ El foro puede usarse para hacer preguntas sobre cómo usar el paquete e informar No dudes en mencionar esto en los documentos de tu paquete, ya sea en la guía de contribución o en la plantilla de *issue*. Pide etiquetar las publicaciones con el nombre del paquete. -Una vez que un *pull request* está más cerca de ser aceptado, puedes utilizar [un flujo de trabajo de *GitHub Actions PR* para aplicar el estilo al código con styler](https://github.com/r-lib/actions/blob/master/examples/pr-commands.yaml). +Una vez que un *pull request* está más cerca de ser aceptado, puedes mejorar el estilo con [Air](https://posit-dev.github.io/air/) o [styler](https://styler.r-lib.org/). ### Gestión de issues {#issue-management} diff --git a/maintenance_collaboration.pt.Rmd b/maintenance_collaboration.pt.Rmd index f0680a6d1..e9ea70bdf 100644 --- a/maintenance_collaboration.pt.Rmd +++ b/maintenance_collaboration.pt.Rmd @@ -40,7 +40,7 @@ Em geral, esses e outros modelos precisarão ser modificados para serem usados c Modificar um guia de contribuição genérico para adicionar um toque pessoal também tende a fazer com que ele pareça menos genérico e mais sincero. As preferências pessoais em um guia de contribuição incluem: -- Preferências de estilo? No entanto, você pode preferir tornar o estilo uma configuração (de [lintr](https://github.com/jimhester/lintr), [styler](https://styler.r-lib.org/)) ou para [corrigir você mesmo o estilo de código](https://github.com/rstudio/blogdown/pull/432#pullrequestreview-368391904) especialmente se você não usar um estilo de código popular como o [estilo de código do tidyverse](https://style.tidyverse.org/). +- Preferências de estilo? No entanto, você pode preferir tornar o estilo uma configuração (de [Air](https://posit-dev.github.io/air/), [styler](https://styler.r-lib.org/), [lintr](https://github.com/jimhester/lintr), ) ou para [corrigir você mesmo o estilo de código](https://github.com/rstudio/blogdown/pull/432#pullrequestreview-368391904) especialmente se você não usar um estilo de código popular como o [estilo de código do tidyverse](https://style.tidyverse.org/). - Infraestrutura como a do `roxygen2`? @@ -57,7 +57,7 @@ Os arquivos `CONTRIBUTING.md` também podem descrever como você reconhece as co Recomendamos que você envie comentários que não sejam um relatório de bug ou uma solicitação de *feature* para o [Fórum da rOpenSci](https://discuss.ropensci.org/) após certificar-se de que você verá essas perguntas no fórum. As pessoas usuárias podem usar o fórum para fazer perguntas sobre o uso e relatar seus casos de uso, e você pode se inscrever em categorias e tags individuais para receber notificações sobre o seu pacote. Sinta-se à vontade para mencionar isso nos documentos do seu pacote e/ou nas diretrizes de contribuição/modelo de *issue*. Oriente as pessoas que usam seu pacote a marcar as mensagens com o nome do pacote. -Quando uma pull request estiver mais perto de ser mesclada, você poderá usar [um *GitHub Actions PR workflow* para estilizar o código com o pacote `styler`](https://github.com/r-lib/actions/blob/master/examples/pr-commands.yaml). +Quando uma pull request estiver mais perto de ser mesclada, você poderá estilizar o código com [Air](https://posit-dev.github.io/air/) ou [styler](https://styler.r-lib.org/). ### Gerenciamento de *issues* {#issue-management} 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..93fd77015 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) { @@ -226,6 +226,6 @@ An example of a minimal README in an archived package is in [ropensci-archive/mo - [ ] Archive the repository on GitHub (also under repo settings). - [ ] Transfer the repository to [ropensci-archive](https://github.com/ropensci-archive), or request an [rOpenSci staff member](https://ropensci.org/about/#team) to transfer it (you can email `info@ropensci.org`). -Archived packages may be unarchived if authors or a new person opt to resume maintenance. For that please contact rOpenSci. They are transferred to the ropenscilabs organization. +Archived packages may be unarchived if authors or a new person opt to resume maintenance. For that please contact rOpenSci. diff --git a/maintenance_evolution.es.Rmd b/maintenance_evolution.es.Rmd index b43b37593..b5c7e3c10 100644 --- a/maintenance_evolution.es.Rmd +++ b/maintenance_evolution.es.Rmd @@ -236,6 +236,6 @@ Una vez que el *README* se ha copiado en otro lugar y se ha reducido a su forma - [ ] Transfiere el repositorio a [ropensci-archive](https://github.com/ropensci-archive) o solicita a un [miembro del equipo de rOpenSci](https://ropensci.org/about/#team) que lo haga (puedes enviar un correo electrónico a `info@ropensci.org`). Los paquetes archivados pueden ser desarchivados si quien lo mantenía, o una nueva persona, deciden reanudar el mantenimiento. -Para ello, ponte en contacto con rOpenSci y se transferirá el repo a la organización ropenscilabs. +Para ello, ponte en contacto con rOpenSci. diff --git a/maintenance_evolution.pt.Rmd b/maintenance_evolution.pt.Rmd index 44dc28230..259a80209 100644 --- a/maintenance_evolution.pt.Rmd +++ b/maintenance_evolution.pt.Rmd @@ -3,28 +3,28 @@ aliases: - evolution.html --- -# Package evolution - changing stuff in your package {#evolution} +# Evolução do pacote - alteração de itens em seu pacote {#evolution} ```{block, type="summaryblock"} -This chapter presents our guidance for changing stuff in your package: changing parameter names, changing function names, deprecating functions, and even retiring and archiving packages. +Este capítulo apresenta nossa orientação para alterar coisas em seu pacote: alterar nomes de parâmetros, alterar nomes de funções, descontinuar funções e até mesmo retirar e arquivar pacotes. -_This chapter was initially contributed as a tech note on rOpenSci website by [Scott Chamberlain](https://github.com/sckott); you can read the original version [here](https://ropensci.org/technotes/2017/01/05/package-evolution/)._ +_Este capítulo foi inicialmente contribuído como uma nota técnica no site da rOpenSci por [Scott Chamberlain](https://github.com/sckott); você pode ler a versão original [aqui](https://ropensci.org/technotes/2017/01/05/package-evolution/)._ ``` -## Philosophy of changes {#philosophy-of-changes} +## Filosofia das alterações {#philosophy-of-changes} -Everyone's free to have their own opinion about how freely parameters/functions/etc. are changed in a library - rules about package changes are not enforced by CRAN or otherwise. Generally, as a library gets more mature, changes to user facing methods (i.e., exported functions in an R package) should become very rare. Libraries that are dependencies of many other libraries are likely to be more careful about changes, and should be. +Todos são livres para ter sua própria opinião sobre a liberdade com que parâmetros/funções/etc. são alterados em uma biblioteca - as regras sobre alterações de pacotes não são impostas pelo CRAN ou de outra forma. Em geral, à medida que uma biblioteca se torna mais madura, as alterações nos métodos voltados para o usuário (ou seja, funções exportadas em um pacote R) devem se tornar muito raras. As bibliotecas que são dependências de muitas outras bibliotecas provavelmente serão mais cuidadosas com as alterações, e devem ser. -## The lifecycle package {#the-lifecycle-package} +## O pacote lifecycle {#the-lifecycle-package} -This chapter presents solutions that do not require the lifecycle package but you might still find it useful. -We recommend [reading the lifecycle documentation](https://lifecycle.r-lib.org/articles/stages.html). +Este capítulo apresenta soluções que não requerem o pacote lifecycle, mas que você ainda pode considerar úteis. +Recomendamos que você [leia a documentação do lifecycle](https://lifecycle.r-lib.org/articles/stages.html). -## Parameters: changing parameter names {#parameters-changing-parameter-names} +## Parâmetros: alteração dos nomes dos parâmetros {#parameters-changing-parameter-names} -Sometimes parameter names must be changed for clarity, or some other reason. +Às vezes, os nomes dos parâmetros precisam ser alterados para maior clareza ou por algum outro motivo. -A possible approach is check if deprecated arguments are not missing, and stop providing a meaningful message. +Uma abordagem possível é verificar se os argumentos descontinuados não estão faltando e parar de fornecer uma mensagem significativa. ```r foo_bar <- function(x, y) { @@ -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: +Se quiser que a função seja mais útil, você pode fazê-la emitir um aviso e tomar automaticamente a ação necessária: ```r foo_bar <- function(x, y) { @@ -53,21 +53,21 @@ foo_bar(x = 5) #> 25 ``` -Be aware of the parameter `...`. If your function has `...`, and you have already removed a parameter (lets call it `z`), a user may have older code that uses `z`. When they pass in `z`, it's not a parameter in the function definition, and will likely be silently ignored -- not what you want. Instead, leave the argument around, throwing an error if it used. +Esteja ciente do parâmetro `...`. Se sua função tiver `...` e você já tiver removido um parâmetro (vamos chamá-lo de `z`), um usuário pode ter um código mais antigo que usa `z`. Quando você passa o parâmetro `z` ele não é um parâmetro na definição da função e provavelmente será ignorado silenciosamente -- não é o que você deseja. Em vez disso, deixe o argumento presente, lançando um erro se ele for usado. -## Functions: changing function names {#functions-changing-function-names} +## Funções: alteração de nomes de funções {#functions-changing-function-names} -If you must change a function name, do it gradually, as with any other change in your package. +Se você precisar alterar o nome de uma função, faça-o gradualmente, como em qualquer outra alteração em seu pacote. -Let's say you have a function `foo`. +Digamos que você tenha uma função `foo`. ```r foo <- function(x) x + 1 ``` -However, you want to change the function name to `bar`. +No entanto, você deseja alterar o nome da função para `bar`. -Instead of simply changing the function name and `foo` no longer existing straight away, in the first version of the package where `bar` appears, make an alias like: +Em vez de simplesmente alterar o nome da função e `foo` deixar de existir imediatamente, na primeira versão do pacote em que o `bar` aparecer, crie um alias como: ```r #' foo - add 1 to an input @@ -79,9 +79,9 @@ foo <- function(x) x + 1 bar <- foo ``` -With the above solution, the user can use either `foo()` or `bar()` -- either will do the same thing, as they are the same function. +Com a solução acima, o usuário pode usar `foo()` ou `bar()` -- ambos farão a mesma coisa, pois são a mesma função. -It's also useful to have a message but then you'll only want to throw that message when they use the old function, e.g., +Também é útil ter uma mensagem, mas você só vai querer lançar essa mensagem quando eles usarem a função antiga, por exemplo, ```r #' foo - add 1 to an input @@ -96,7 +96,7 @@ foo <- function(x) { bar <- function(x) x + 1 ``` -After users have used the package version for a while (with both `foo` and `bar`), in the next version you can remove the old function name (`foo`), and only have `bar`. +Depois que os usuários tiverem usado a versão do pacote por algum tempo (com ambos os `foo` e `bar`), na próxima versão você poderá remover o nome da função antiga (`foo`), e você terá apenas `bar`. ```r #' bar - add 1 to an input @@ -104,13 +104,13 @@ After users have used the package version for a while (with both `foo` and `bar` bar <- function(x) x + 1 ``` -## Functions: deprecate \& defunct {#functions-deprecate-defunct} +## Funções: descontinuadas e removidas {#functions-deprecate-defunct} -To remove a function from a package (let's say your package name is `helloworld`), you can use the following protocol: +Para remover uma função de um pacote (digamos que o nome do seu pacote seja `helloworld`), você pode usar o seguinte protocolo: -- Mark the function as deprecated in package version `x` (e.g., `v0.2.0`) +- Marque a função como descontinuada na versão do pacote `x` (por exemplo, `v0.2.0`) -In the function itself, use `.Deprecated()` to point to the replacement function: +Na própria função, use `.Deprecated()` para apontar para a função de substituição: ```r foo <- function() { @@ -118,11 +118,11 @@ foo <- function() { } ``` -There's options in `.Deprecated` for specifying a new function name, as well as a new package name, which makes sense when moving functions into different packages. +Há opções em `.Deprecated` para especificar um novo nome de função, bem como um novo nome de pacote, o que faz sentido quando você move funções para pacotes diferentes. -The message that's given by `.Deprecated` is a warning, so can be suppressed by users with `suppressWarnings()` if desired. +A mensagem que é dada por `.Deprecated` é um aviso, portanto, pode ser suprimida por usuários com `suppressWarnings()` se você desejar. -Make a man page for deprecated functions like: +Crie uma página de manual para funções descontinuadas, como: ```r #' Deprecated functions in helloworld @@ -138,11 +138,11 @@ Make a man page for deprecated functions like: NULL ``` -This creates a man page that users can access like ``?`helloworld-deprecated` `` and they'll see in the documentation index. Add any functions to this page as needed, and take away as a function moves to defunct (see below). +Isso cria uma página de manual que os usuários podem acessar como ``?`helloworld-deprecated` `` e que você verá no índice da documentação. Adicione quaisquer funções a essa página conforme necessário e remova-as quando uma função se tornar "defunct" (veja abaixo). -- In the next version (`v0.3.0`) you can make the function defunct (that is, completely gone from the package, except for a man page with a note about it). +- Na próxima versão (`v0.3.0`), você pode tornar a função "defunct" (ou seja, completamente removida do pacote, exceto por uma página de manual com uma nota sobre ela). -In the function itself, use `.Defunct()` like: +Na própria função, use `.Defunct()` como: ```r foo <- function() { @@ -150,9 +150,9 @@ foo <- function() { } ``` -Note that the message in `.Defunct` is an error so that the function stops whereas `.Deprecated` uses a warning that let the function proceed. +Observe que a mensagem em `.Defunct` é um erro para que a função pare, enquanto `.Deprecated` usa um aviso que permite que a função continue. -In addition, it's good to add `...` to all defunct functions so that if users pass in any parameters they'll get the same defunct message instead of a `unused argument` message, so like: +Além disso, é bom adicionar `...` a todas as funções removidas para que, se os usuários passarem algum parâmetro, recebam a mesma mensagem de "defunct" em vez de um `unused argument` assim, por exemplo: ```r foo <- function(...) { @@ -160,21 +160,21 @@ foo <- function(...) { } ``` -Without `...` gives: +Sem `...` o resultado é: ```r foo(x = 5) #> Error in foo(x = 5) : unused argument (x = 5) ``` -And with `...` gives: +E com `...` o resultado é: ```r foo(x = 5) #> Error: 'foo' has been removed from this package ``` -Make a man page for defunct functions like: +Faça uma página de manual para funções "defunct", como: ```r #' Defunct functions in helloworld @@ -189,21 +189,21 @@ Make a man page for defunct functions like: NULL ``` -This creates a man page that users can access like ``?`helloworld-defunct` `` and they'll see in the documentation index. Add any functions to this page as needed. You'll likely want to keep this man page indefinitely. +Isso cria uma página de manual que os usuários podem acessar como ``?`helloworld-defunct` `` e que você verá no índice da documentação. Você pode adicionar quaisquer funções a essa página, conforme necessário. Você provavelmente desejará manter essa página de manual indefinidamente. -### Testing deprecated functions {#testing-deprecated-functions} +### Testando funções descontinuadas {#testing-deprecated-functions} -You don't have to change the tests of deprecated functions until they are made defunct. +Você não precisa alterar os testes de funções descontinuadas até que elas se tornem "defunct". -- Consider any changes made to a deprecated function. Along with using `.Deprecated` inside the function, did you change the parameters at all in the deprecated function, or create a new function that replaces the deprecated function, etc. Those changes should be tested if any made. -- Related to above, if the deprecated function is simply getting a name change, perhaps test that the old and new functions return identical results. -- [`suppressWarnings()` could be used](https://community.rstudio.com/t/unit-testing-of-a-deprecated-function/42837/2) to suppress the warning thrown from `.Deprecated`, but tests are not user facing, so it is not that bad if the warning is thrown in tests, and the warning could even be used as a reminder to the maintainer. +- Considere todas as alterações feitas em uma função descontinuada. Além de usar `.Deprecated` dentro da função, você alterou os parâmetros na função descontinuada ou criou uma nova função que substitui a função descontinuada, etc.? Essas alterações devem ser testadas, caso você as tenha feito. +- Em relação ao que foi dito acima, se a função descontinuada estiver apenas recebendo uma alteração de nome, talvez você possa testar se as funções antiga e nova retornam resultados idênticos. +- [`suppressWarnings()` poderia ser usado](https://community.rstudio.com/t/unit-testing-of-a-deprecated-function/42837/2) para suprimir o aviso lançado pelo `.Deprecated`, mas os testes não são voltados para o usuário e, portanto, não é tão ruim se o aviso for lançado nos testes, e o aviso pode até ser usado como um lembrete para o mantenedor. -Once a function is made defunct, its tests are simply removed. +Quando uma função se torna "defunct", seus testes são simplesmente removidos. -## Archiving packages {#archivalguidance} +## Arquivamento de pacotes {#archivalguidance} -Software generally has a finite lifespan, and packages may eventually need to be archived. Archived packages are [archived](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) and moved to a dedicated GitHub organization, [ropensci-archive](https://github.com/ropensci-archive). Prior to archiving, the contents of the README file should be moved to an alternative location (such as "README-OLD.md"), and replaced with minimal contents including something like the following: +Software geralmente tem uma vida útil finita, e os pacotes podem precisar ser arquivados. Os pacotes arquivados são [arquivados](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) e movidos para uma organização dedicada no GitHub, [ropensci-archive](https://github.com/ropensci-archive). Antes do arquivamento, o conteúdo do arquivo README deve ser movido para um local alternativo (como "README-OLD.md") e substituído por um conteúdo mínimo, incluindo algo como o seguinte: ```md # @@ -214,18 +214,18 @@ Software generally has a finite lifespan, and packages may eventually need to be This package has been archived. The former README is now in [README-old](). ``` -The repo status badge should be "unsupported" for formerly released packages, or "abandoned" for former concept or WIP packages, in which case the badge code above should be replaced with: +O *badge* de status do repositório deve estar como "unsupported" (sem suporte) para pacotes lançados anteriormente ou como "abandoned" (abandonado) para pacotes de conceito anterior ou WIP (trabalho em progresso), caso em que o código do *badge* acima deve ser substituído por: ```md [![Project Status: Abandoned](https://www.repostatus.org/badges/latest/abandoned.svg)](https://www.repostatus.org/#abandoned) ``` -An example of a minimal README in an archived package is in [ropensci-archive/monkeylearn](https://github.com/ropensci-archive/monkeylearn/blob/master/README.md). Once the README has been copied elsewhere and reduced to minimal form, the following steps should be followed: +Um exemplo de um README mínimo em um pacote arquivado está em [ropensci-archive/monkeylearn](https://github.com/ropensci-archive/monkeylearn/blob/master/README.md). Depois que o README tiver sido copiado em outro lugar e reduzido à forma mínima, você deverá seguir as etapas a seguir: -- [ ] Close issues with a sentence explaining the situation and linking to this guidance. -- [ ] Archive the repository on GitHub (also under repo settings). -- [ ] Transfer the repository to [ropensci-archive](https://github.com/ropensci-archive), or request an [rOpenSci staff member](https://ropensci.org/about/#team) to transfer it (you can email `info@ropensci.org`). +- [ ] Encerre os *issues* com uma frase que explique a situação e faça um link para este guia. +- [ ] Arquive o repositório no GitHub (também nas configurações do repositório). +- [ ] Transfira o repositório para [ropensci-archive](https://github.com/ropensci-archive) ou solicite um [membro da equipe do rOpenSci](https://ropensci.org/about/#team) para transferi-lo (você pode enviar um e-mail para `info@ropensci.org`). -Archived packages may be unarchived if authors or a new person opt to resume maintenance. For that please contact rOpenSci. They are transferred to the ropenscilabs organization. +Os pacotes arquivados podem ser desarquivados se os autores ou uma nova pessoa optarem por retomar a manutenção. Para isso, entre em contato com a rOpenSci. 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.Rmd b/maintenance_marketing.Rmd index ab6d90d6d..e8e27d9d1 100644 --- a/maintenance_marketing.Rmd +++ b/maintenance_marketing.Rmd @@ -6,20 +6,20 @@ aliases: # Marketing your package {#marketing} +Also refer to the blog post ["Marketing Ideas For Your Package"](https://ropensci.org/blog/2024/03/07/package-marketing/). + ```{block, type="summaryblock"} We will help you promoting your package but here are some more things to keep in mind. ``` - 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 toot (Mastodon post) from rOpenSci and inclusion in the rOpenSci monthly 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. -- Post about your package on Mastodon using the "#rstats" hashtag and tag rOpenSci! This might help with contributor/user engagement. Example posts from rOpenSci itself: [A package a day](hachyderm.io/@rOpenSci/111611705648653729), [Help wanted post](hachyderm.io/@rOpenSci/111460729804231877), [Use cases](hachyderm.io/@rOpenSci/111371091053569287), [Welcome post]( hachyderm.io/@rOpenSci/111342069863172097). +- Post about your package on social media (Mastodon, Bluesky, LinkedIn...) using the "#rstats" hashtag and tag rOpenSci if rOpenSci is present on that platform! This might help with contributor/user engagement. Example posts from rOpenSci itself: [A package a day](hachyderm.io/@rOpenSci/111611705648653729), [Help wanted post](hachyderm.io/@rOpenSci/111460729804231877), [Use cases](hachyderm.io/@rOpenSci/111371091053569287), [Welcome post]( hachyderm.io/@rOpenSci/111342069863172097). - When you [release](#releasing) a new version of your package or release it to CRAN for the first time, - 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). - - Post about it on social media. - - 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)). - Submit your package to lists of packages such as [CRAN Task Views](https://cran.r-project.org/web/views/). diff --git a/maintenance_marketing.es.Rmd b/maintenance_marketing.es.Rmd index 8e1dc4b12..5a57e3856 100644 --- a/maintenance_marketing.es.Rmd +++ b/maintenance_marketing.es.Rmd @@ -4,6 +4,8 @@ repo-actions: true # Promocionando tu paquete {#marketing} +Consulte también la entrada del blog [«Ideas de marketing para su paquete»](https://ropensci.org/blog/2024/03/07/package-marketing/). + ```{block, type="summaryblock"} Te ayudaremos a promocionar tu paquete, pero aquí hay algunas cosas más para tener en cuenta. @@ -12,14 +14,12 @@ Te ayudaremos a promocionar tu paquete, pero aquí hay algunas cosas más para t - Cuando [publiques](#releasing) una nueva versión de tu paquete o lo publiques en CRAN por primera vez, -- Comparte sobre el paquete en Mastodon utilizando el hashtag "#rstats" y etiqueta a rOpenSci! +- Comparte sobre el paquete en tus redes sociales (Mastodon, Bluesky, LinkedIn...) utilizando el hashtag "#rstats" y etiqueta a rOpenSci si rOpenSci esta presente en esa red! Esto puede ayudar llegar a gente que pueda colaborar o usar el paquete. Ejemplos enviados desde rOpenSci mismo: ["A package a day" (un paquete al dia)](hachyderm.io/@rOpenSci/111611705648653729), [Help wanted (se necesita ayuda)](hachyderm.io/@rOpenSci/111460729804231877), [Use case (caso de uso)](hachyderm.io/@rOpenSci/111371091053569287), [Welcome post (mensaje de bienvenida)]( hachyderm.io/@rOpenSci/111342069863172097). - haz un *pull request* a [R Weekly](https://github.com/rweekly/rweekly.org) con una mensaje sobre la versión en la sección "*New Releases*" (o "*New Packages*" para la primera versión de GitHub/CRAN). - - Comparte en tus redes sociales. - - Considera enviar un breve artículo sobre el lanzamiento a [rOpenSci tech notes](https://ropensci.org/technotes/). Ponte en contacto con la persona encargada de gestionar la comunidad de rOpenSci, (por ejemplo, a través de Slack o [info@ropensci.org](mailto:info@ropensci.org)). Consulta [las recomendaciones sobre cómo contribuir con un artículo en el blog](https://blogguide.ropensci.org)). diff --git a/maintenance_marketing.pt.Rmd b/maintenance_marketing.pt.Rmd index b882f984a..7bef115fc 100644 --- a/maintenance_marketing.pt.Rmd +++ b/maintenance_marketing.pt.Rmd @@ -4,25 +4,27 @@ aliases: - marketing.html --- -# Marketing your package {#marketing} +# Marketing do seu pacote {#marketing} + +Consulte também a postagem do blog [*Marketing Ideas For Your Package*](https://ropensci.org/blog/2024/03/07/package-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). + - Publique sobre seu pacote nas mídias sociais (Mastodon, Bluesky, LinkedIn...) usando a hashtag “#rstats” e marque a rOpenSci se ela estiver presente nessa plataforma! Isso pode ajudar no engajamento de pessoas colaboradoras e usuárias. [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..f4cce266a 100644 --- a/pkg_building.Rmd +++ b/pkg_building.Rmd @@ -86,12 +86,21 @@ If your package accesses a web API or another web resource, For more information refer to the blog post [Why You Should (or Shouldn't) Build an API Client](https://ropensci.org/blog/2022/06/16/publicize-api-client-yes-no). -## Code Style {#code-style} -- For more information on how to style your code, name functions, and R scripts inside the `R/` folder, we recommend reading the [code chapter in The R Packages book](https://r-pkgs.org/Code.html). We recommend the [`styler` package](https://github.com/r-lib/styler) for automating part of the code styling. We suggest reading the [Tidyverse style guide](https://style.tidyverse.org/). +### Packages wrapping external software {#external-software} + +- Document clearly how to install the package, including all required external packages or libraries, including where applicable explicit steps on common operating systems. +- Provide a situation report (sitrep) function checking whether the software has been installed, with hints in case something is missing. [Example in greta](https://github.com/greta-dev/greta/blob/50ef770a79f8c6d8b9090e94f15953f2ba155a18/R/greta-sitrep.R). +- If possible, provide a function helping with installation. [Example in hugodown](https://github.com/r-lib/hugodown/blob/main/R/hugo-install.R). + +## Code Style and best practices {#code-style} + +- For more information on how to style your code, name functions, and R scripts inside the `R/` folder, we recommend reading the [code chapter in The R Packages book](https://r-pkgs.org/Code.html). We recommend [Air](https://posit-dev.github.io/air/) or the [styler package](https://github.com/r-lib/styler) for automating part of the code styling. We suggest reading the [Tidyverse style guide](https://style.tidyverse.org/). - You can choose to use `=` over `<-` as long you are consistent with one choice within your package. We recommend avoiding the use of `->` for assignment within a package. If you do use `<-` throughout your package, and you also use `R6` in that package, you'll be forced to use `=` for assignment within your `R6Class` construction - this is not considered an inconsistency because you can't use `<-` in this case. +- You can use the [lintr package](https://lintr.r-lib.org/index.html) to identify some possible areas of improvement. [Example workflow](https://masalmon.eu/2024/08/28/lintr-3-steps/). + ## CITATION file {#citation-file} - If your package does not yet have a CITATION file, you can create one with `usethis::use_citation()`, and populate it with values generated by the `citation()` function. @@ -286,15 +295,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} @@ -303,7 +307,7 @@ If your package doesn't have any logo, the [rOpenSci docs builder](#docsropensci ## Authorship {#authorship} -The `DESCRIPTION` file of a package should list package authors and contributors to a package, using the `Authors@R` syntax to indicate their roles (author/creator/contributor etc.) if there is more than one author, and using the comment field to indicate the ORCID ID of each author, if they have one (cf [this post](https://ropensci.org/technotes/2018/10/08/orcid/)). See [this section of "Writing R Extensions"](https://cran.rstudio.com/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file) for details. If you feel that your reviewers have made a substantial contribution to the development of your package, you may list them in the `Authors@R` field with a Reviewer contributor type (`"rev"`), like so: +The DESCRIPTION file of a package should list package authors and contributors to a package, using the `Authors@R` syntax to indicate their roles (author/creator/contributor etc.) if there is more than one author, and using the comment field to indicate the ORCID ID of each author, if they have one (cf [this post](https://ropensci.org/technotes/2018/10/08/orcid/)). See [this section of "Writing R Extensions"](https://cran.rstudio.com/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file) for details. If you feel that your reviewers have made a substantial contribution to the development of your package, you may list them in the `Authors@R` field with a Reviewer contributor type (`"rev"`), like so: ``` person("Bea", "Hernández", role = "rev", @@ -327,7 +331,10 @@ Many packages include code from other software. Whether entire files or single f ## Licence {#licence} The package needs to have a [CRAN](https://svn.r-project.org/R/trunk/share/licenses/license.db) or [OSI](https://opensource.org/licenses) accepted license. -For more explanations around licensing, refer to the [R packages book](https://r-pkgs.org/license.html). +The [R packages book](https://r-pkgs.org/description.html#sec-description-authors-at-r) includes a helpful [section on licenses](https://r-pkgs.org/license.html). + +If your package bundles code from other sources, you also need to acknowledge authors of the original code in your DESCIPTION file, generally with a copyright-holder role: `role = "cph"`. +For how to update your DESCRIPTION file, see the [R packages book](https://r-pkgs.org/description.html#sec-description-authors-at-r). ## Testing {#testing} @@ -339,7 +346,7 @@ For more explanations around licensing, refer to the [R packages book](https://r - We recommend using [testthat](https://testthat.r-lib.org/) for writing tests. Strive to write tests as you write each new function. This serves the obvious need to have proper testing for the package, but allows you to think about various ways in which a function can fail, and to *defensively* code against those. [More information](https://r-pkgs.org/tests.html). -- Tests should be easy to understand. We suggest reading the blog post [*"Why Good Developers Write Bad Unit Tests"*](https://mtlynch.io/good-developers-bad-tests/) by Michael Lynch. +- Tests should be easy to understand, and as self-contained as possible. When using testthat, avoid using code outside of `test_that()` blocks (such as pre-processing steps). We recommend reading the [high-level principles for testing](https://r-pkgs.org/testing-design.html#sec-testing-design-principles) in the R Packages book. - Packages with Shiny apps should use a unit-testing framework such as [`shinytest2`](https://rstudio.github.io/shinytest2/) or [`shinytest`](https://rstudio.github.io/shinytest/articles/shinytest.html) to test that interactive interfaces behave as expected. @@ -366,20 +373,21 @@ For more explanations around licensing, refer to the [R packages book](https://r - You can run examples with `devtools::run_examples()`. Note that when you run R CMD CHECK or equivalent (e.g., `devtools::check()`) your examples that are not wrapped in `\dontrun{}` or `\donttest{}` are run. Refer to the [summary table](https://roxygen2.r-lib.org/articles/rd.html#functions) in roxygen2 docs. -- To safe-guard examples (e.g. requiring authentication) to be run on CRAN you need to use `\dontrun{}`. However, for a first submission CRAN won't let you have all examples escaped so. In this case you might add some small toy examples, or wrap example code in `try()`. Also refer to the `@exampleIf` tag present, at the time of writing, in roxygen2 development version. +- To safe-guard examples (e.g. requiring authentication) to be run on CRAN you need to use `\dontrun{}`. However, for a first submission CRAN won't let you have all examples escaped so. In this case you might add some small toy examples, or wrap example code in `try()`. Also refer to the `@exampleIf` tag. - In addition to running examples locally on your own computer, we strongly advise that you run examples on one of the [continuous integration systems](#ci). Again, examples that are not wrapped in `\dontrun{}` or `\donttest{}` will be run, but for those that are you can configure your continuous integration builds to run them via R CMD check arguments `--run-dontrun` and/or `--run-donttest`. ## Package dependencies {#pkgdependencies} +- It is very generally better to have fewer dependencies. - Consider the trade-offs involved in relying on a package as a dependency. On one hand, using dependencies reduces coding effort, and can build on useful functionality developed by others, especially if the dependency performs complex tasks, is high-performance, and/or is well vetted and tested. On the other hand, having many dependencies places a burden on the maintainer to keep up with changes in those packages, at risk to your package's long-term sustainability. It also - increases installation time and size, primarily a consideration on your and others' development cycle, and in automated build systems. "Heavy" packages - those with many dependencies themselves, and those with large amounts of compiled code - increase this cost. Here are some approaches to reducing - dependencies: + increases installation time and size, primarily a consideration on your and others' development cycle, and in automated build systems. "Heavy" packages - those with many dependencies themselves, and those with large amounts of compiled code - increase this cost. +- Approaches to reducing dependencies include: - Small, simple functions from a dependency package may be better copied into your own package if the dependency if you are using only a few functions @@ -397,7 +405,7 @@ For more explanations around licensing, refer to the [R packages book](https://r class(df) <- c("tbl_df", "tbl", "data.frame") ``` - (Note that this approach is [not universally endorsed](https://twitter.com/krlmlr/status/1067856118385381377).) + (Note that this approach should be very carefully used and tested, especially as it may break expected behaviour of re-classed objects.) - Ensure that you are using the package where the function is defined, rather than one where it is re-exported. For instance many functions in **devtools** can be found in smaller specialty packages such as **sessioninfo**. The `%>%` function @@ -414,7 +422,10 @@ For more explanations around licensing, refer to the [R packages book](https://r - More dependency-management tips can be found in the chapter ["Dependencies: Mindset and Background" of the R packages book](https://r-pkgs.org/dependencies-mindset-background.html) and in a [post by Scott Chamberlain](https://recology.info/2018/10/limiting-dependencies/). -- Use `Imports` instead of `Depends` for packages providing functions from other packages. Make sure to list packages used for testing (`testthat`), and documentation (`knitr`, roxygen2) in your `Suggests` section of package dependencies (if you use `usethis` for adding testing infrastructure via [`usethis::use_testthat()`](https://usethis.r-lib.org/reference/use_testthat.html) or a vignette via [usethis::use\_vignette()](https://usethis.r-lib.org/reference/use_vignette.html), the necessary packages will be added to `DESCRIPTION`). If you use any package in the examples or tests of your package, make sure to list it in `Suggests`, if not already listed in `Imports`. +- Use `Imports` instead of `Depends` for packages providing functions from other packages. Make sure to list packages used for testing (`testthat`), and documentation (`knitr`, roxygen2) in your `Suggests` section of package dependencies (if you use `usethis` for adding testing infrastructure via [`usethis::use_testthat()`](https://usethis.r-lib.org/reference/use_testthat.html) or a vignette via [usethis::use\_vignette()](https://usethis.r-lib.org/reference/use_vignette.html), the necessary packages will be added to DESCRIPTION). If you use any package in the examples or tests of your package, make sure to list it in `Suggests`, if not already listed in `Imports`. + +- Check the development status of any dependencies you add. + Especially for packages hosted on GitHub, it is very useful to check that they are actively maintained, and that they have [not been archived](https://ropensci.org/blog/2022/07/01/evaluating-github-activity-for-contributors/). - If your (not Bioconductor) package depends on Bioconductor packages, make sure the installation instructions in the README and vignette are clear enough even for an user who is not familiar with the Bioconductor release cycle. @@ -455,6 +466,8 @@ For more explanations around licensing, refer to the [R packages book](https://r - Your package source files have to be under version control, more specifically tracked with [Git](https://happygitwithr.com/). You might find the [gert package](https://docs.ropensci.org/gert/) relevant, as well as some of [usethis Git/GitHub related functionality](https://usethis.r-lib.org/reference/index.html#section-git-and-github); you can however use git as you want. +- The default branch name should not be `master`, as this can be offensive to some people. Refer to the [statement of the Git project and the Software Freedom Conservancy](https://sfconservancy.org/news/2020/jun/23/gitbranchname/) for more context. It is general practice to name a default branch `main`, although other names may also be used. See the tidyverse blog post ["Renaming the default branch"](https://www.tidyverse.org/blog/2021/10/renaming-default-branch/) to learn about usethis functionality to help with renaming default branches. + - Make sure to list "scrap" such as `.DS_Store` files in .gitignore. You might find the [`usethis::git_vaccinate()` function](https://usethis.r-lib.org/reference/git_vaccinate.html), and the [gitignore package](https://docs.ropensci.org/gitignore/) relevant. - A later section of this book contains some [git workflow tips](#gitflow). @@ -467,7 +480,7 @@ This is a collection of CRAN gotchas that are worth avoiding at the outset. - Do not put a period on the end of your title. - Do not put 'in R' or 'with R' in your title as this is obvious from packages hosted on CRAN. If you would like this information to be displayed on your website nonetheless, check the [`pkgdown` documentation](https://pkgdown.r-lib.org/reference/build_home.html#yaml-config-home) to learn how to override this. - Avoid starting the description with the package name or "This package ...". -- Make sure you include links to websites if you wrap a web API, scrape data from a site, etc. in the `Description` field of your `DESCRIPTION` file. URLs should be enclosed in angle brackets, e.g. ``. +- Make sure you include links to websites if you wrap a web API, scrape data from a site, etc. in the `Description` field of your DESCRIPTION file. URLs should be enclosed in angle brackets, e.g. ``. - In both the `Title` and `Description` fields, the names of packages or other external software must be quoted using single quotes (e.g., *'Rcpp' Integration for the 'Armadillo' Templated Linear Algebra Library*). - Avoid long running tests and examples. Consider `testthat::skip_on_cran` in tests to skip things that take a long time but still test them locally and on [continuous integration](#ci). - Include top-level files such as `paper.md`, continuous integration configuration files, in your `.Rbuildignore` file. diff --git a/pkg_building.es.Rmd b/pkg_building.es.Rmd index d7bd633a6..fb6262392 100644 --- a/pkg_building.es.Rmd +++ b/pkg_building.es.Rmd @@ -91,16 +91,24 @@ Si tu paquete accede a una API web o a otro recurso web, Para más información, consulta el artículo del blog [Por qué deberías (o no) crear un cliente API](https://ropensci.org/blog/2022/06/16/publicize-api-client-yes-no). -## Estilo del código {#code-style} +### Paquetes que envuelven software externo {#external-software} + +- Documenta claramente cómo instalar el paquete, incluidos todos los paquetes o bibliotecas externos necesarios, incluyendo, en su caso, los pasos explícitos en los sistemas operativos habituales. +- Proporciona una función de informe de situación (sitrep) que compruebe si se ha instalado el software, con pistas en caso de que falte algo. [Ejemplo en greta](https://github.com/greta-dev/greta/blob/50ef770a79f8c6d8b9090e94f15953f2ba155a18/R/greta-sitrep.R). +- Si es posible, proporciona una función que ayude en la instalación. [Ejemplo en hugodown](https://github.com/r-lib/hugodown/blob/main/R/hugo-install.R). + +## Estilo del código y mejores prácticas {#code-style} - Para más información sobre cómo dar estilo a tu código, nombrar funciones y scripts de R dentro de la carpeta `R` te recomendamos que leas el [capítulo "Code" (Código) del libro R Packages](https://r-pkgs.org/Code.html). - Recomendamos el paquete [`styler`](https://github.com/r-lib/styler) para automatizar parte del estilo del código. + Recomendamos [Air](https://posit-dev.github.io/air/) o el paquete [styler](https://github.com/r-lib/styler) para automatizar parte del estilo del código. También te sugerimos que leas la [Guía de estilo de Tidyverse (en inglés)](https://style.tidyverse.org/). - Puedes optar por utilizar `=` en lugar de `<-` siempre que seas coherente con esa elección dentro de tu paquete. Recomendamos evitar el uso de `->` para la asignación dentro del paquete. Si utilizas `<-` en todo tu paquete, y también utilizas `R6` en ese paquete, debrás utilizar `=` para la asignación dentro de la generación de la clase `R6Class` - esto no se considera una incoherencia porque no puedes usar `<-` en este caso. +- Puedes utilizar el [paquete lintr](https://lintr.r-lib.org/index.html) para identificar algunas posibles áreas de mejora. [Ejemplo de flujo de trabajo](https://masalmon.eu/2024/08/28/lintr-3-steps/). + ## Archivo CITATION {#citation-file} - Si tu paquete aún no tiene un archivo CITATION, puedes crear uno con `usethis::use_citation()`y llenarlo con los valores generados por la función `citation()`. @@ -327,15 +335,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} - -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 +### Renderización de matemáticas {#mathjax} -```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} @@ -377,7 +380,10 @@ Tanto si se incluyen archivos enteros como funciones individuales de otros paque ## Licencia {#licence} El paquete debe tener una licencia aceptada por [CRAN](https://svn.r-project.org/R/trunk/share/licenses/license.db) u [OSI](https://opensource.org/licenses). -Para más detalles sobre las licencias, consulta el libro [R packages](https://r-pkgs.org/license.html). +El libro [_R packages_ (Paquetes de R)](https://r-pkgs.org/description.html#sec-description-authors-at-r) incluye una sección muy útil sobre licencias. + +Si tu paquete incluye código de otras fuentes, también necesitas reconocer a los autores del código original en tu archivo DESCIPTION, generalmente con un rol de propietario del copyright: `role = "cph"`. +Para saber cómo actualizar tu archivo DESCRIPTION, consulta el libro [_R packages_ (Paquetes de R)](https://r-pkgs.org/description.html#sec-description-authors-at-r) en Inglés o puedes consultar también el libro en español [Introducción a la programación II](https://intro-programacion.netlify.app/09_paquetes-1.html#completando-el-archivo-description). ## Testeo {#testing} @@ -394,8 +400,7 @@ Para más detalles sobre las licencias, consulta el libro [R packages](https://r Esto responde a la necesidad obvia de tener *tests* adecuados para el paquete, pero te permite pensar en varias formas en las que una función puede fallar, y programar *defensivamente* contra esas fallas. [Más información sobre *tests*](https://r-pkgs.org/tests.html). -- Los *tests* deben ser fáciles de entender. - Te sugerimos que leas el artículo de blog [*Why Good Developers Write Bad Unit Tests* (Por qué las personas que son buenas desarrollando escriben malos tests)](https://mtlynch.io/good-developers-bad-tests/) de Michael Lynch. +- Los *tests* deben ser fáciles de entendery lo más autocontenidos posible. Si usas testthat, evita utilizar código de alto nivel, es decir, código fuera de bloques `test_that()` (como por ejemplo, pasos de preprocesamiento). Recomendamos leer los [_"high-level principles for testing"_ (principios de alto nivel para _tests_)](https://r-pkgs.org/testing-design.html#sec-testing-design-principles) en el libro _R Packages_ (Paquetes de R). - Los paquetes con aplicaciones Shiny deberán generar *tests* unitarios usando [`shinytest2`](https://rstudio.github.io/shinytest2/) o [`shinytest`](https://rstudio.github.io/shinytest/articles/shinytest.html) para comprobar que las interfaces interactivas funcionan como es esperado. @@ -434,7 +439,7 @@ Para más detalles sobre las licencias, consulta el libro [R packages](https://r - Para evitar que los ejemplos se ejecuten en CRAN (por ejemplo, si requieren autenticación), tienes que utilizar `\dontrun{}`. Sin embargo, para un primer envío, CRAN no te permitirá saltearte todos los ejemplos. En este caso puedes añadir algunos pequeños ejemplos de juguete, o encapsular el código de los ejemplos en `try()`. - Consulta también la etiqueta `@exampleIf`, que al momento de escribir este artículo, se encuentra en la versión de desarrollo de roxygen2. + Consulta también la etiqueta `@exampleIf`. - Además de ejecutar los ejemplos localmente en tu propia computadora, te aconsejamos fuertemente que ejecutes los ejemplos en uno de los [sistemas de integración continua](#ci). De nuevo, se ejecutarán los ejemplos que no estén incluidos en `\dontrun{}` o `\donttest{}`. @@ -442,12 +447,13 @@ Para más detalles sobre las licencias, consulta el libro [R packages](https://r ## Dependencias del paquete {#pkgdependencies} +- En general, es mejor tener la menor cantidad de dependencias posibles. - Pensa en las ventajas y desventajas de depender de un paquete. Por un lado, las dependencias reducen el esfuerzo de desarrollo, y permite construir en base a funcionalidades útiles desarrolladas por otras personas, especialmente si la dependencia realiza tareas complejas, es de alto rendimiento y/o está bien revisada y probada. Por otro lado, tener muchas dependencias supone una carga de mantenimiento ya que requiere estar al día con los cambios en esos paquetes, con riesgo para la sostenibilidad de tu paquete a largo plazo. También aumenta el tiempo y el tamaño de la instalación, lo que supone principalmente una consideración en el ciclo de desarrollo tuyo y del resto, y en los sistemas de compilación automatizados. Los paquetes "pesados" -los que tienen muchas dependencias, y los que tienen grandes cantidades de código compilado- aumentan este costo. - He aquí algunos enfoques para reducir las dependencias: +- He aquí algunos enfoques para reducir las dependencias: - Si sólo utilizas unas pocas funciones de una dependencia grande o pesada, puedes copiarlas en tu propio paquete. (Ver la sección [*Autoría*](#authorship-included-code) para saber cómo reconocer la autoría del código copiado). @@ -460,7 +466,7 @@ Para más detalles sobre las licencias, consulta el libro [R packages](https://r class(df) <- c("tbl_df", "tbl", "data.frame") ``` - (Ten en cuenta que este enfoque [no está universalmente aceptado](https://twitter.com/krlmlr/status/1067856118385381377).) + (Ten en cuenta que este enfoque debe utilizarse y probarse con mucho cuidado, sobre todo porque puede romper el comportamiento esperado de los objetos a los que se le cambia la clase.) - Asegúrate de que utilizas la función del paquete donde está definida originalmente y no de un paquete que la re-exporta. Por ejemplo, muchas funciones de **devtools** pueden encontrarse en paquetes especializados más pequeños, como **sessioninfo**. @@ -478,6 +484,9 @@ Para más detalles sobre las licencias, consulta el libro [R packages](https://r Utiliza sección `Suggests` para listar los paquetes que usas en los *tests* (`testthat`), y para generar la documentación (`knitr`, roxygen2) (si utilizas `usethis` para añadir la infraestructura de *tests* con [`usethis::use_testthat()`](https://usethis.r-lib.org/reference/use_testthat.html) o una viñeta mediante [usethis::use\_vignette()](https://usethis.r-lib.org/reference/use_vignette.html) los paquetes necesarios se añadirán a `DESCRIPTION`). Si utilizas algún paquete en los ejemplos o *tests* de tu paquete, asegúrate de listarlo en `Suggests` si no aparece ya en `Imports`. +- Comprueba el estado de desarrollo de cualquier dependencia que añadas. + Especialmente para los paquetes alojados en GitHub, es muy útil comprobar que se mantienen activamente, y que [no han sido archivados](https://ropensci.org/blog/2022/07/01/evaluating-github-activity-for-contributors/). + - Si tu paquete no está en Bioconductor pero depende de paquetes de Bioconductor, asegúrate de que las instrucciones de instalación en el *README* y la viñeta sean lo suficientemente claras incluso para una persona que no esté familiarizada con el ciclo de publicación de Bioconductor. - ¿Hay que usar [`BiocManager`](https://www.bioconductor.org/install/index.html#why-biocmanagerinstall) (recomendado)? @@ -528,6 +537,8 @@ Para más detalles sobre las licencias, consulta el libro [R packages](https://r - Los archivos fuente de tu paquete tienen que estar bajo control de versiones, más concretamente versionados con [Git](https://happygitwithr.com/). Puede que el paquete [gert](https://docs.ropensci.org/gert/) te resulte útil, así como algunas de las [funciones de usethis relacionadas con Git/GitHub](https://usethis.r-lib.org/reference/index.html#section-git-and-github); sin embargo, puedes utilizar git como quieras. + +- El nombre de rama por defecto no debe ser `master` ya que puede resultar ofensivo para algunas personas. Consulta la [declaración del proyecto Git y de la Software Freedom Conservancy](https://sfconservancy.org/news/2020/jun/23/gitbranchname/) para más contexto. Es práctica general nombrar a la rama por defecto `main` aunque también pueden utilizarse otros nombres. Consulta el artículo de tidyverse ["Cambiar el nombre de la rama por defecto"](https://www.tidyverse.org/blog/2021/10/renaming-default-branch/) para aprender a utilizar esta funcionalidad para renombrar las ramas por defecto. - Asegúrate de listar archivos innecesarios, como `.DS_Store`, en .gitignore. La función [`usethis::git_vaccinate()`](https://usethis.r-lib.org/reference/git_vaccinate.html), y el paquete [gitignore](https://docs.ropensci.org/gitignore/) pueden resultarte útil para esto. diff --git a/pkg_security.pt.Rmd b/pkg_security.pt.Rmd new file mode 100644 index 000000000..88ed02429 --- /dev/null +++ b/pkg_security.pt.Rmd @@ -0,0 +1,86 @@ + +# Práticas de segurança recomendadas no desenvolvimento de pacotes {#package-development-security-best-practices} + +```{block, type="summaryblock"} +Este capítulo em desenvolvimento inclui [orientações sobre o gerenciamento de credenciais em pacotes] (#pkgsecrets), além de [links para leituras complementares] (#furthersecreading). +``` + +## Diversos {#miscellaneous} + +Recomendamos a leitura do artigo [Dez dicas rápidas para você se manter seguro(a) on-line](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1008563), de Danielle Smalls e Greg Wilson. + +## Segurança no acesso ao GitHub {#git-hub-access-security} + +- Recomendamos que você [proteja a sua conta do GitHub com uma autenticação 2FA (autenticação de dois fatores)](https://help.github.com/articles/securing-your-account-with-two-factor-authentication-2fa/). Essa medida é *obrigatória* para todos os membros da organização ropensci e colaboradores externos que usam o GitHub, portanto, certifique-se de ativá-la antes que o seu pacote seja aprovado. + +- Também recomendamos que você verifique regularmente quem tem acesso ao repositório do seu pacote e remova qualquer acesso não utilizado (como os de ex-colaboradores e ex-colaboradoras). + +## https {#https} + +- Se o serviço Web que o seu pacote utiliza oferecer tanto https quanto http, opte por https. + +## Segredos em pacotes {#pkgsecrets} + +Esta seção oferece orientações para quando você desenvolve pacotes que interagem com recursos da Web que exigem credenciais (como chaves de API, tokens, etc.). Consulte também [a vinheta do pacote `httr` sobre o compartilhamento de credenciais](https://httr.r-lib.org/articles/secrets.html). + +### Credenciais em pacotes e proteção do(a) usuário(a) {#secrets-in-packages-and-user-protection} + +Digamos que o seu pacote precise de uma chave de API para fazer as solicitações em nome dos(as) usuários(as) do seu pacote. + +- Na documentação do seu pacote, oriente o(a) usuário(a) para que a chave de API não seja registrada no arquivo .Rhistory ou no arquivo de código dos(as) usuários(as) do seu pacote. + + - Incentive o uso de variáveis de ambiente para armazenar a chave de API (ou até mesmo remova a possibilidade de passá-la como um argumento para as funções). Você pode, na documentação, fazer referência a [introdução aos arquivos de inicialização](https://rstats.wtf/r-startup.html) e a função [`usethis::edit_r_environ()`](https://usethis.r-lib.org/reference/edit.html). + +- Ou o seu pacote pode depender ou incentivar o uso de [`keyring` para ajudar o(a) usuário(a) a armazenar variáveis](https://github.com/r-lib/keyring#readme) nos gerenciadores de credenciais específicos do sistema operacional (mais seguro do que .Renviron), ou seja, você criaria uma função para definir a chave e teria outra para recuperá-la; ou escreveria `Sys.setenv(SUPERSECRETKEY = keyring::key_get("myservice"))` no início do seu arquivo de código. + + - Não imprima a chave de API, nem mesmo no modo verboso, em qualquer mensagem, aviso ou erro. + +- No modelo de _issue_ do GitHub, deve ser declarado que nenhuma credencial deve ser compartilhada. Se um(a) usuário(a) do seu pacote compartilhar acidentalmente as credenciais em uma issue, certifique-se de que ele(a) esteja ciente disso para que possa revogar a chave (ou seja, pergunte explicitamente, em uma resposta, se a pessoa percebeu que compartilhou a chave). + +### Credenciais em pacotes e desenvolvimento {#secrets-in-packages-and-development} + +Você precisará proteger as suas credenciais da mesma forma que protege as credenciais dos(as) usuários(as), mas há mais aspectos a serem considerados e mantidos em mente. + +#### Credenciais e solicitações registradas em testes {#secrets-and-recorded-requests-in-tests} + +Se você utiliza [`vcr`](https://docs.ropensci.org/vcr/) ou [`httptest`](https://enpiar.com/r/httptest/) em testes para armazenar as respostas da API em cache, é importante garantir que as requisições ou configurações registradas não contenham credenciais. Consulte [o guia de segurança do pacote `vcr`](https://books.ropensci.org/http-testing/security-chapter.html) e [o guia do pacote `httptest` "Redigindo e modificando requisições registradas"](https://enpiar.com/r/httptest/articles/redacting.html). Além disso, inspecione as suas requisições ou configurações registradas antes de realizar o primeiro commit para garantir que você fez a configuração correta. + +Como o `vcr` é um pacote da rOpenSci, você pode postar qualquer dúvida que tiver no [Fórum da rOpenSci](https://discuss.ropensci.org/). + +#### Compartilhe credenciais com os serviços de CI {#share-secrets-with-ci-services} + +Agora, você pode precisar compartilhar credenciais com os [serviços de integração contínua](#ci). + +Você pode armazenar as chaves de API como variáveis de ambiente ou credenciais, consultando a documentação do serviço de CI. + +Para obter mais detalhes e orientações sobre o fluxo de trabalho, consulte [o artigo do pacote gargle - "Gerenciando tokens com segurança"](https://gargle.r-lib.org/articles/articles/managing-tokens-securely.html) e o [capítulo sobre segurança do livro HTTP testing in R](https://books.ropensci.org/http-testing/security-chapter.html). + +Documente as etapas em [CONTRIBUTING.md](#friendlyfiles) para que você, ou um(a) novo(a) mantenedor(a), possa se lembrar como proceder da próxima vez. + +#### Credenciais e colaborações {#secrets-and-collaborations} + +E quanto a pull requests de colaboradores(as) externos(as)? +No GitHub, por exemplo, as credenciais só estão disponíveis para GitHub Actions em pull requests iniciados a partir do próprio repositório, e não a partir de um fork. +Os testes que usam as suas credenciais falharão, ao menos que você use algum tipo de resposta simulada ou em cache, portanto, pode ser interessante ignorá-los dependendo do contexto. +Por exemplo, na sua conta de CI, você poderia criar uma variável de ambiente chamada `THIS_IS_ME` e, então, ignorar os testes com base na presença dessa variável. + Isso significa, portanto, que as verificações de PR feitas pela CI não serão exaustivas e, como consequência, você precisará verificar o PR localmente para executar todos os testes. + +Documente o comportamento do seu pacote em relação a PRs externos no arquivo [CONTRIBUTING.md](#friendlyfiles). Isso será útil tanto para quem faz PRs quanto para quem os revisa, seja você no futuro ou outras pessoas mantenedoras do pacote. + +### Credenciais e CRAN {#secrets-and-cran} + +No CRAN, ignore quaisquer testes (`skip_on_cran()`) e exemplos (`dontrun`) que exijam credenciais. + +[Gere previamente as vinhetas](https://ropensci.org/technotes/2019/12/08/precompute-vignettes/) que requerem credenciais. + +## Leitura adicional {#furthersecreading} + +Materiais úteis sobre segurança: + +- [a sessão da comunidade rOpenSci "Segurança para R"](https://ropensci.org/commcalls/2019-05-07/) (veja a gravação, os slides, etc. e, em particular, [a lista de recursos](https://ropensci.org/blog/2019/04/09/commcall-may2019/#resources)); + +- [os projetos relacionados à segurança do unconf18](https://ropensci.org/blog/2018/06/06/unconf18_recap_2/); + +- [o artigo do pacote `gargle` "Gerenciando tokens de forma segura"](gargle.r-lib.org/articles/articles/managing-tokens-securely.html) + + diff --git a/preface.Rmd b/preface.Rmd index 1e6a43fa1..8c57e57cf 100644 --- a/preface.Rmd +++ b/preface.Rmd @@ -20,13 +20,6 @@ This book is a living document. You can view updates to our best practices and policies via the [release notes](#booknews). You can cite this book using [its Zenodo metadata and DOI](https://doi.org/10.5281/zenodo.2553043). -```{r} -#| echo: false -#| results: 'asis' -#| warning: false -source(file.path("scripts", "airtable-get-reviewers.R"), local = knitr::knit_global()) -``` - _If you want to contribute to this book (suggestions, corrections) please refer to [the GitHub repository](https://github.com/ropensci/dev_guide) in particular [the contributing guidelines](https://github.com/ropensci/dev_guide#contributing). Thanks!_ _We are thankful for all authors, reviewers and guest editors for helping us improve the system and this guide over the years. Thanks also to the following persons who made contributions to this guide and its previous incarnations: `r readLines("thanks.md")` Please tell us if we forgot to acknowledge your contribution!_ diff --git a/preface.es.Rmd b/preface.es.Rmd index 3668e2e30..c57477de8 100644 --- a/preface.es.Rmd +++ b/preface.es.Rmd @@ -23,13 +23,6 @@ Este libro es un documento vivo. Puedes ver las actualizaciones de nuestras buenas prácticas y políticas a través de las [notas de cada versión](#booknews). Puedes citar este libro utilizando [sus metadatos de Zenodo y su DOI](https://doi.org/10.5281/zenodo.2553043). -```{r} -#| echo: false -#| results: 'asis' -#| warning: false -source(file.path("scripts", "airtable-get-reviewers.R"), local = knitr::knit_global()) -``` - *Si quieres contribuir sugerencias o correcciones a este libro, visita [el repositorio de GitHub](https://github.com/ropensci/dev_guide) y, en particular, [la guía de contribución](https://github.com/ropensci/dev_guide#contributing). ¡Gracias!* *Agradecemos a quienes crean, mantienen, revisan y editan paquetes por ayudarnos a mejorar el sistema y esta guía a lo largo de los años. Gracias también a las siguientes personas que han contribuido a esta guía y a sus versiones anteriores: `r readLines("thanks.md")`. Por favor, avísanos si nos olvidamos de reconocer tu contribución.* diff --git a/preface.pt.Rmd b/preface.pt.Rmd index e30d1424d..3e6e41e30 100644 --- a/preface.pt.Rmd +++ b/preface.pt.Rmd @@ -20,12 +20,6 @@ Este livro é um documento vivo. Você pode ver as atualizações das nossas práticas recomendadas e políticas nas [notas de versão](#booknews). Você pode citar este livro usando [os metadados Zenodo e DOI](https://doi.org/10.5281/zenodo.2553043). -````{r} -#| echo: false -#| results: 'asis' -source(file.path("scripts", "airtable-get-reviewers.R"), local = knitr::knit_global()) -```` - *Se você quiser contribuir com este livro (sugestões, correções), consulte [o repositório do GitHub](https://github.com/ropensci/dev_guide) em particular [as diretrizes de contribuição](https://github.com/ropensci/dev_guide#contributing). Obrigado!* *Agradecemos a todos os autores, revisores e editores convidados por nos ajudarem a aprimorar o sistema e este guia ao longo dos anos. Agradecemos também às seguintes pessoas que fizeram contribuições para este guia e suas versões anteriores: `r readLines("thanks.md")` Informe-nos se esquecemos de reconhecer a sua contribuição!* 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-data.R b/scripts/airtable-get-data.R new file mode 100644 index 000000000..cb005189b --- /dev/null +++ b/scripts/airtable-get-data.R @@ -0,0 +1,52 @@ +## all reviewers ---- +at_rev <- airtabler::airtable(base = Sys.getenv("AIRTABLE_ID"), + table = "reviewers-prod") +reviewers <- at_rev$`reviewers-prod`$select_all() + +## eic ---- + +at_eic <- airtabler::airtable(base = Sys.getenv("AIRTABLE_ID"), + table = "editor-in-chief-rotation") +eic <- at_eic$`editor-in-chief-rotation`$select_all() + +eic$period_start <- as.Date(eic$period_start) +eic$period_end <- as.Date(eic$period_end) +today <- Sys.Date () +eic_now <- eic [which (eic$period_start <= today & eic$period_end >= today), ] +eic_name <- eic_now$acting_eic_name [[1]] +eic_id <- eic_now$acting_eic +eic_in_rev_table <- which(reviewers$id == eic_id) +eic_github <- reviewers$github[eic_in_rev_table] + +## guest editors ---- + +at_guest <- airtabler::airtable(base = "app8dssb6a7PG6Vwj", + table = "guest-editors") + + +editor_index_all <- purrr::map_lgl(reviewers$editor, ~!is.null(.)) +editors_all <- reviewers[which(editor_index_all), c("name", "github", "Affiliation", "editor")] +editors_all <- editors_all [which(!editors_all$name == eic_name), ] +last_names <- humaniformat::last_name(trimws(editors_all$name)) +editors_all <- editors_all[order(last_names), ] + +editors_past <- editors_all[grep("Emeritus", editors_all$editor), ] +editors <- editors_all[which(!editors_all$name %in% editors_past$name), ] + +guest_editors <- at_guest$`guest-editors`$select_all() + +guest_editors <- airtabler::airtable(base = "app8dssb6a7PG6Vwj", + table = "guest-editors") +guest_editors <- guest_editors$`guest-editors`$select_all(fields = list("name", "github")) +guest_editors <- guest_editors[!(guest_editors$name %in% c(editors$name, "???")), ] +last_names <- humaniformat::last_name(trimws(guest_editors$name)) +guest_editors <- guest_editors[order(last_names), ] + +## reviewers that are not editors ---- + +reviewers <- reviewers[purrr::map_lgl(reviewers$reviews, + ~!is.null(.)) & + !(reviewers$name %in% c(editors_all$name, "???")), ] +last_names <- humaniformat::last_name(trimws(reviewers$name)) +reviewers <- reviewers[order(last_names), ] +reviewers$name[is.na(reviewers$name)] <- reviewers$github[is.na(reviewers$name)] diff --git a/scripts/airtable-get-editors.R b/scripts/airtable-get-editors.R index ea8726202..6ff44b3e5 100644 --- a/scripts/airtable-get-editors.R +++ b/scripts/airtable-get-editors.R @@ -1,8 +1,12 @@ -guest_editors <- airtabler::airtable(base = "app8dssb6a7PG6Vwj", - table = "guest-editors") -guest_editors <- guest_editors$`guest-editors`$select_all(fields = list("name", "github")) -guest_editors <- guest_editors[!(guest_editors$name %in% c(editors, "???")), ] -# get last names -last_names <- humaniformat::last_name(trimws(guest_editors$name)) -guest_editors <- guest_editors[order(last_names), ] -cat(paste0("[", guest_editors$name, "](https://github.com/", guest_editors$github, ")", collapse = " \U00B7 ")) +gen_ed_out <- function(ed_dat) { + if (!"Affiliation" %in% names(ed_dat)) { + ed_dat$Affiliation <- NA_character_ + } + out <- gsub("(,\\sNA|\\s);", ";", paste0( + "- [", ed_dat$name, "](https://github.com/", ed_dat$github, "), ", + ed_dat$Affiliation, ";\n")) + out[length(out)] <- gsub(";\\n$", ".\n", out[length(out)]) + return(out) +} + +cat(gen_ed_out(editors), sep = "") \ No newline at end of file diff --git a/scripts/airtable-get-eic.R b/scripts/airtable-get-eic.R new file mode 100644 index 000000000..1fb8f9cb1 --- /dev/null +++ b/scripts/airtable-get-eic.R @@ -0,0 +1,6 @@ +out <- paste0( + "We rotate our Editor-in-Chief, generally every three months. ", + "Our current Editor-in-Chief is [", eic_name, "](https://github.com/", + eic_github, ").\n" +) +cat(out, sep = "") \ No newline at end of file diff --git a/scripts/airtable-get-eic.es.R b/scripts/airtable-get-eic.es.R new file mode 100644 index 000000000..3ee924830 --- /dev/null +++ b/scripts/airtable-get-eic.es.R @@ -0,0 +1,6 @@ +out <- paste0( + "We rotate our Editor-in-Chief, generally every three months. ", + "Our current Editor-in-Chief is [", eic_name, "](https://github.com/", + eic_github, ").\n" +) +cat(out, sep = "") diff --git a/scripts/airtable-get-guest-editors.R b/scripts/airtable-get-guest-editors.R new file mode 100644 index 000000000..a86222390 --- /dev/null +++ b/scripts/airtable-get-guest-editors.R @@ -0,0 +1 @@ +cat(paste0("[", guest_editors$name, "](https://github.com/", guest_editors$github, ")", collapse = " \U00B7 ")) diff --git a/scripts/airtable-get-reviewers.R b/scripts/airtable-get-reviewers.R index 7b7f681cb..bd4841755 100644 --- a/scripts/airtable-get-reviewers.R +++ b/scripts/airtable-get-reviewers.R @@ -1,18 +1 @@ - -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[purrr::map_lgl(reviewers$reviews, - ~!is.null(.)) & - !(reviewers$name %in% c(editors, "???")), ] -# get last names -last_names <- humaniformat::last_name(trimws(reviewers$name)) -reviewers <- reviewers[order(last_names), ] -reviewers$name[is.na(reviewers$name)] <- reviewers$github[is.na(reviewers$name)] -cat(paste0("[", reviewers$name, "](https://github.com/", reviewers$github, ")", collapse = " \U00B7 ")) +cat(paste0("[", reviewers$name, "](https://github.com/", reviewers$github, ")", collapse = " \U00B7 ")) \ No newline at end of file diff --git a/softwarereview_author.Rmd b/softwarereview_author.Rmd index a5a52483a..8584c1885 100644 --- a/softwarereview_author.Rmd +++ b/softwarereview_author.Rmd @@ -11,15 +11,26 @@ This concise guide presents the software peer review process for you as a packag ## Planning a Submission (or a Pre-Submission Enquiry) {#planning-a-submission-or-a-pre-submission-enquiry} -- Do you expect to maintain your package for at least 2 years, or to be able to identify a new maintainer? + +### Scope + - Consult our [policies](#policies) see if your package meets our criteria for fitting into our suite and does not overlap with other packages. - If you are unsure whether a package meets our criteria, feel free to open an issue as a pre-submission inquiry to ask if the package is appropriate. - [Example response regarding overlap](https://github.com/ropensci/software-review/issues/199#issuecomment-375358362). Also consider adding some points about similar packages to your [package documentation](#docs-general). + +### Lifecycle + +- Please do not submit several packages at a time: we request you wait until a package has been approved before you submit another one. +- Do you expect to maintain your package for at least 2 years, or to be able to identify a new maintainer? - Please consider the best time in your package's development to submit. Your package should be sufficiently mature so that reviewers are able to review all essential aspects, but keep in mind that review may result in major changes. - We strongly suggest submitting your package for review *before* publishing on CRAN or submitting a software paper describing the package to a journal. Review feedback may result in major improvements and updates to your package, including renaming and breaking changes to functions. - Do not submit your package for review while it or an associated manuscript is also under review at another venue, as this may result in conflicting requests for changes. - Please also consider the time and effort needed to respond to reviews: think about your availability or that of your collaborators in the next weeks and months following a submission. Note that reviewers are volunteers, and we ask that you respect their time and effort by responding in a timely and respectful manner. - If you use [repostatus.org badges](https://www.repostatus.org/) (which we recommend), submit when you're ready to get an *Active* instead of *WIP* badge. Similarly, if you use [lifecycle badges](https://www.tidyverse.org/lifecycle/), submission should happen when the package is *Stable*. +- Your package will continue to evolve after review, the chapter on *Package evolution* [provides guidance about the topic](#evolution). + +### Documentation + - For any submission or pre-submission inquiry the README of your package should provide enough information about your package (goals, usage, similar packages) for the editors to assess its scope without having to install the package. Even better, set up a pkgdown website for allowing more detailed assessment of functionality online. - At the submission stage, all major functions should be stable enough to be fully documented and tested; the README should make a strong case for the package. - Your README file should strive to explain your package's functionality and aims, assuming readers have little to no domain knowledge. All technical tems, including references to other software, should be clarified. @@ -27,13 +38,28 @@ This concise guide presents the software peer review process for you as a packag ## Preparing for Submission {#preparing-for-submission} -- Read and follow [our packaging style guide](#building), [reviewer's guide](#preparereview) to ensure your package meets our style and quality criteria. +### Asking for help + - Feel free to ask any questions about the process, or your specific package, in our [Discussion Forum](https://discuss.ropensci.org). + +### Guidelines + +- Read and follow [our packaging style guide](#building), [reviewer's guide](#preparereview) to ensure your package meets our style and quality criteria. + +### Automatic checks + - All submissions are automatically checked by our [pkgcheck](https://docs.ropensci.org/pkgcheck/) system to ensure packages follow our guidelines. All authors are expected to have run [the main `pkgcheck` function](https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html) locally to confirm that the package is ready to be submitted. Alternatively, an even easier way to ensure a package is ready for submission is to use [the `pkgcheck` GitHub Action](https://github.com/ropensci-review-tools/pkgcheck-action) to run `pkgcheck` as a GitHub Action, as described in [our blog post](https://ropensci.org/blog/2022/02/01/pkgcheck-action/). -- If your package requires unusual system dependencies (see [*Packaging Guide*](#pkgdependencies)) for our GitHub Action to pass, please submit a pull request adding them to [our base Dockerfile](https://github.com/ropensci-review-tools/pkgcheck/blob/main/Dockerfile). +- If your package requires unusual system dependencies (see [*Packaging Guide*](#pkgdependencies)) for our GitHub Action to pass, please submit a pull request adding them to [our base Dockerfile](https://github.com/ropensci-review-tools/pkgcheck/blob/main/Dockerfile). + See [this `pkgcheck` vignette](https://docs.ropensci.org/pkgcheck/articles/environment.html) for details of our checking environment, and how to modify it to help your package pass checks. - If there are any aspects of `pkgcheck` which your package is unable to pass, please explain reasons in your submission template. -- If you feel your package is in scope for the - [Journal of Open-Source Software](https://joss.theoj.org/) (JOSS), do not submit it to JOSS consideration until after the rOpenSci review process is over: if your package is deemed in scope by JOSS editors, only the accompanying short paper would be reviewed, (not the software that will have been extended reviewed by rOpenSci by that time). Not all rOpenSci packages will meet the criteria for JOSS. + +### Accompanying manuscript (optional) + +If you intend to submit an accompanying manuscript for your package, rOpenSci has a collaborative partnership with the [Journal of Open-Source Software](https://joss.theoj.org/) and [Methods in Ecology and Evolution](https://besjournals.onlinelibrary.wiley.com/journal/2041210X): + +- For a submission to Journal of Open-Source Software (JOSS), do not submit it to JOSS consideration until after the rOpenSci review process is over: if your package is deemed in scope by JOSS editors, only the accompanying short paper would be reviewed, (not the software that will have been extended reviewed by rOpenSci by that time). Not all rOpenSci packages will meet the criteria for JOSS. + +- For a submission to Methods in Ecology and Evolution (MEE), submit it to MEE only after the rOpenSci reviewers have submitted their reviews, either before or after the package has been accepted. The review collaboration with MEE was introduced in a [blog post](https://ropensci.org/blog/2017/11/29/review-collaboration-mee/). The relevant article type for MEE is [Application](https://besjournals.onlinelibrary.wiley.com/hub/journal/2041210X/features/applicationpapers) for more details. ## The Submission Process {#the-submission-process} @@ -48,12 +74,13 @@ This concise guide presents the software peer review process for you as a packag - *When submitting a package please make sure your GitHub notification settings make it unlikely you will miss a comment.* - Packages are automatically checked on submission by [our `pkgcheck` system](https://docs.ropensci.org/pkgcheck), which will confirm whether or not a package is ready to be reviewed. - Submitted packages can be hosted in the main/default branch, or any other non-default branch. In the latter case, it is encouraged, but not required, to submit the package via a dedicated `ropensci-software-review` branch. +- For submissions in non-default branches, the "Repository" URL in the submission template should be the full URL to the review branch, like `https://github.com/my/repo/tree/ropensci-software-review`. ## The Review Process {#the-review-process} - 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..0eb8811b2 100644 --- a/softwarereview_author.es.Rmd +++ b/softwarereview_author.es.Rmd @@ -6,15 +6,25 @@ Esta guía condensa el proceso de revisión por pares desde el punto de vista de ## Planificar un envío (o una consulta previa al envío) {#planning-a-submission-or-a-pre-submission-enquiry} -- ¿Esperas mantener tu paquete durante al menos 2 años, o poder encontrar a otra persona para mantenerlo? +### Alcance + - Consulta nuestras [políticas](#policies) para evaluar si tu paquete cumple los criterios para ser incluido en nuestro conjunto de paquetes y no se superpone con otros. - - Si no sabes si un paquete cumple con nuestros criterios, no dudes en abrir un issue para consultarlo. +- Si no sabes si un paquete cumple con nuestros criterios, no dudes en abrir un _issue_ para consultarlo. - [Ejemplo de respuesta sobre solapamiento](https://github.com/ropensci/software-review/issues/199#issuecomment-375358362). Considera también añadir información sobre paquetes similares a tu [documentación de paquetes](#docs-general). + +### Ciclo de desarrollo + +- Por favor, no envies varios paquetes a la vez: te rogamos que espere hasta que un paquete haya sido aprobado antes de enviar otro. +- ¿Esperas mantener tu paquete durante al menos 2 años, o poder encontrar a otra persona para mantenerlo? - Por favor, considera cuál es el mejor momento en el desarrollo de tu paquete para presentarlo. Tu paquete debe estar lo suficientemente maduro como para que quienes lo revisen puedan evaluar todos los aspectos esenciales, pero ten en cuenta que la revisión puede resultar en cambios importantes. - Te recomendamos fuertemente que envíes tu paquete para su revisión *antes de* publicarlo en CRAN o enviar un artículo de software que describa el paquete a una revista. Las devoluciones de las revisiones pueden dar pie a importantes mejoras y actualizaciones de tu paquete, incluso cambiar el nombre o modificaciones incompatibles con versiones previas. - No envíes tu paquete para su revisión mientras éste o un artículo científico asociado también esté siendo revisado en otro lugar, ya que esto puede dar lugar a recomendaciones incompatibles. - Ten en cuenta también el tiempo y el esfuerzo necesarios para responder a las revisiones: piensa en tu disponibilidad o en la de quienes colaboran con tu paquete en las semanas y meses siguientes al envío. Ten en cuenta que las revisiones son realizadas por personas voluntarias, y te pedimos que respetes su tiempo y esfuerzo respondiendo puntual y respetuosamente. - Si utilizas [etiquetas de repostatus.org](https://www.repostatus.org/) (que recomendamos), envía tu paquete cuando esté listo para obtener la etiqueta *Active* en vez de *WIP*. Si utilizas [etiquetas de ciclo de vida](https://www.tidyverse.org/lifecycle/), el envío debe producirse cuando el paquete esté al menos en el estado *Maturing*. +- Tu paquete seguirá evolucionando después de la revisión, el capítulo sobre *Evolución de paquetes* [proporciona orientación sobre el tema](#evolution). + +### Documentación + - Para cualquier envío o consulta previa al envío, el *README* de tu paquete debería proporcionar suficiente información sobre el mismo (objetivos, uso, paquetes similares) para que quienes revisan el paquete puedan evaluar su alcance sin tener que instalarlo. Mejor aún, crea un sitio web de pkgdown para que puedan evaluar las funcionalidads detalladamente en línea. - En la fase de envío, todas las funciones principales deben ser lo suficientemente estables como para estar completamente documentadas y testeadas. El *README* tiene que dar una buena impresión de tu paquete. - El archivo *README* debe esforzarse por explicar las funcionalidades y los objetivos de tu paquete asumiendo poco o ningún conocimiento del dominio. Además, debe aclarar todos los temas técnicos, incluidas las referencias a otros software. @@ -22,12 +32,28 @@ Esta guía condensa el proceso de revisión por pares desde el punto de vista de ## Preparación para el envío {#preparing-for-submission} -- Lee y sigue nuestra [guía de estilo para paquetes](#building) y nuestra [guía para la revisión](#preparereview) para asegurarte de que tu paquete cumple nuestros criterios de estilo y calidad. +### Pedir ayuda + - No dudes en hacer cualquier pregunta sobre el proceso en general, o sobre tu paquete en particular en nuestro [foro de discusión](https://discuss.ropensci.org). + +### Directrices + +- Lee y sigue nuestra [guía de estilo para paquetes](#building) y nuestra [guía para la revisión](#preparereview) para asegurarte de que tu paquete cumple nuestros criterios de estilo y calidad. + +### Controles automáticos + - Todos los envíos son revisados automáticamente por nuestro [propio sistema](https://docs.ropensci.org/pkgcheck/) para garantizar que los paquetes sigan nuestras directrices. Se espera que hayas corrido [la función `pkgcheck`](https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html) localmente para confirmar que el paquete está listo para ser enviado. Otra forma aún más fácil de asegurarse de que un paquete está listo para su envío es utilizar [la acción de GitHub `pkgcheck`](https://github.com/ropensci-review-tools/pkgcheck-action) para ejecutar `pkgcheck` como una Acción de GitHub, como se describe en [esta publicación en nuestro blog](https://ropensci.org/blog/2022/02/01/pkgcheck-action/). -- Si tu paquete requiere dependencias inusuales del sistema (ver [*Guía de Empaquetado*](#pkgdependencies) para que nuestra Acción de GitHub pase, por favor envíe un _pull request_ añadiéndolas a [nuestro _Dockerfile_ base](https://github.com/ropensci-review-tools/pkgcheck/blob/main/Dockerfile). +- Si tu paquete requiere dependencias inusuales del sistema (ver [*Guía de Empaquetado*](#pkgdependencies) para que nuestra Acción de GitHub pase, por favor envía un _pull request_ añadiéndolas a [nuestro _Dockerfile_ base](https://github.com/ropensci-review-tools/pkgcheck/blob/main/Dockerfile). + Consulta [esta viñeta `pkgcheck`](https://docs.ropensci.org/pkgcheck/articles/environment.html) para obtener más información sobre nuestro entorno de comprobación y cómo modificarlo para que tu paquete pase las verificaciones. - Si hay algún test de `pkgcheck` que tu paquete no pueda aprobar, explica los motivos en la plantilla de envío. -- Si crees que tu paquete es relevante para el [Journal of Open Source Software](https://joss.theoj.org/) (JOSS), no lo sometas a consideración de JOSS hasta que haya finalizado el proceso de revisión de rOpenSci: si el equipo de edición de JOSS considera que tu paquete está dentro de su ámbito de aplicación, sólo se revisará el breve artículo que lo acompaña (pero no el software que habrá sido revisado por rOpenSci en ese momento). No todos los paquetes de rOpenSci pueden aplicar a JOSS. + +### Artículo complementario (opcional) + +Si tiene intención de enviar un artículo científico sobre tu paquete, rOpenSci colabora con el [Journal of Open-Source Software](https://joss.theoj.org/) y [Methods in Ecology and Evolution](https://besjournals.onlinelibrary.wiley.com/journal/2041210X): + +- Envía el artículo al [Journal of Open Source Software](https://joss.theoj.org/) (JOSS),una vez que has recibido las revistas: si el equipo de edición de JOSS considera que tu paquete está dentro de su ámbito de aplicación, sólo se revisará el artículo que lo acompaña (pero no el software que ya habrá sido revisado por rOpenSci en ese momento). No todos los paquetes de rOpenSci pueden aplicar a JOSS. + +- Para un envío a Methods in Ecology and Evolution (MEE), envíelo a MEE sólo después de que el proceso de revisión de rOpenSci haya terminado, ya sea antes o después de que el paquete haya sido aceptado. La colaboración de revisión con MEE se introdujo en un [blog post](https://ropensci.org/blog/2017/11/29/review-collaboration-mee/). El tipo de artículo relevante para MEE es [Solicitud](https://besjournals.onlinelibrary.wiley.com/hub/journal/2041210X/features/applicationpapers) para más detalles. ## El proceso de envío {#the-submission-process} @@ -42,12 +68,13 @@ Esta guía condensa el proceso de revisión por pares desde el punto de vista de - *Cuando envíes un paquete, por favor asegúrate de tener configuradas las notificaciones de GitHub para que no te pierdas ningún comentario.* - Los paquetes se checkean automáticamente al ser enviados con [nuestro sistema `pkgcheck`](https://docs.ropensci.org/pkgcheck), el cual confirmará si está listo para ser revisado o no. - Los paquetes enviados pueden estar en la rama *main/default*, o en cualquier otra rama no predeterminada. En este último caso, es recomendable, aunque no obligatorio, enviar el paquete a través de una rama dedicada llamada `ropensci-software-review`. +- Para paquetes que están en ramas diferentes a la rama por defecto, la URL del «Repository» en la plantilla de envío debe ser la URL completa de la rama de revisión, como por ejemplo: `https://github.com/my/repo/tree/ropensci-software-review`. ## El proceso de revisión {#the-review-process} - 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_author.pt.Rmd b/softwarereview_author.pt.Rmd new file mode 100644 index 000000000..87256ccd4 --- /dev/null +++ b/softwarereview_author.pt.Rmd @@ -0,0 +1,89 @@ +--- +aliases: + - authors-guide.html +--- + +# Guia para Autores {#authors-guide} + +```{block, type="summaryblock"} +Este guia conciso apresenta o processo de revisão de software por pares, para você como autor de um pacote. +``` + +## Planejando uma Submissão (ou uma Consulta de Pré-Submissão) {#planning-a-submission-or-a-pre-submission-enquiry} + +### Escopo + +- Consulte nossas [políticas de uso](#policies) para ver se o seu pacote atende aos nossos critérios e se encaixa em nossa coleção, não se sobrepondo a outros pacotes já existentes. + - Se você não tiver certeza de que um pacote atende aos nossos critérios, sinta-se à vontade para abrir um _issue_ no GitHub como uma consulta de pré-submissão para perguntar se o pacote é apropriado. + - [Exemplo de resposta a sobreposição](https://github.com/ropensci/software-review/issues/199#issuecomment-375358362). Também considere adicionar alguns pontos sobre pacotes semelhantes ao seu na sua [documentação do pacote](#docs-general). + +### Ciclo de vida + +- Não envie vários pacotes ao mesmo tempo: solicitamos que você espere até que um pacote seja aprovado antes de enviar outro. +- Você pretende manter o seu pacote por pelo menos 2 anos ou ser capaz de identificar uma nova pessoa para mantê-lo? +- Considere o melhor momento de desenvolvimento do seu pacote para enviar sua submissão. Seu pacote deve estar suficientemente maduro para que os revisores possam analisar todos os aspectos essenciais, mas tenha em mente que revisões podem resultar em grandes alterações. + - Sugerimos enfaticamente que você envie seu pacote para análise *antes de* publicá-lo no CRAN ou antes de enviá-lo para publicação como artigo em um periódico. O _feedback_ da revisão pode resultar em grandes aprimoramentos e atualizações do seu pacote, incluindo renomeações e alterações de funções. + - Não envie seu pacote para revisão enquanto este ou o manuscrito associado também estiver sendo revisado em outro local, pois isso pode resultar em solicitações conflitantes de alterações. +- Considere também o tempo e o esforço necessários para responder às revisões: pense na sua disponibilidade ou na de seus colaboradores nas próximas semanas e meses após o envio da submissão. Observe que os revisores são voluntários e pedimos que você respeite o tempo e o esforço deles, respondendo de maneira oportuna e respeitosa. +- Se você usa [distintivos do repostatus.org](https://www.repostatus.org/) (o que recomendamos), envie uma submissão quando você estiver pronto para receber um distintivo tipo _Active_ em vez de _WIP_. Da mesma forma, se você usa [distintivos tipo _lifecycle_](https://www.tidyverse.org/lifecycle/) o envio da submissão deverá ocorrer quando o pacote for _Stable_. +- Seu pacote continuará a evoluir após a revisão. O capítulo sobre *Evolução do pacote* [fornece mais orientações sobre este tópico](#evolution). + +### Documentação + +- Para qualquer envio ou consulta de pré-submissão, o README do seu pacote deve fornecer informações suficientes sobre o pacote (objetivos, uso, pacotes semelhantes) para que os editores avaliem seu escopo sem precisar instalar o pacote. Melhor ainda, crie um website pkgdown para permitir uma avaliação mais detalhada da funcionalidade online. + - No estágio de envio da submissão, todas as principais funções devem ser estáveis o suficiente para serem totalmente documentadas e testadas; o README deve apresentar uma base segura para o pacote. + - Seu arquivo README deve assegurar-se em explicar a funcionalidade e os objetivos do seu pacote, presumindo que os leitores tenham pouco ou nenhum conhecimento do domínio. Todos os termos técnicos, inclusive as referências a outros softwares, devem ser esclarecidos. +- Seu pacote continuará a evoluir após a revisão. O capítulo sobre *Evolução do pacote* [fornece mais orientações sobre este tópico](#evolution). + +## Preparando para Submissão {#preparing-for-submission} + +### Solicitação de ajuda + +- Fique à vontade para fazer perguntas sobre o processo ou sobre seu pacote em específico no nosso [Fórum de discussão](https://discuss.ropensci.org). + +### Diretrizes + +- Leia e siga [nosso guia de estilo de pacotes](#building) e nosso [guia de revisão](#preparereview), para garantir que seu pacote atenda aos nossos critérios de estilo e qualidade. + +### Verificações automáticas + +- Todas as submissões são verificadas automaticamente pelo nosso [`pkgcheck`](https://docs.ropensci.org/pkgcheck/) para garantir que os pacotes sigam as nossas diretrizes. Espera-se que todas as pessoas autoras tenham executado a [principal função do `pkgcheck`](https://docs.ropensci.org/pkgcheck/reference/pkgcheck.html) localmente para confirmar que o pacote está pronto para ser submetido. Como alternativa, uma maneira ainda mais fácil de garantir que um pacote está pronto para ser submetido é usando [a função `pkgcheck` do GitHub Action](https://github.com/ropensci-review-tools/pkgcheck-action), conforme descrito em [nossa postagem no blog](https://ropensci.org/blog/2022/02/01/pkgcheck-action/). +- Se o seu pacote exigir dependências incomuns de sistema (consulte [*Guia de pacotes*](#pkgdependencies)) para que a _GitHub Action_ seja aprovada, envie um _pull request_ adicionando-as ao [nosso arquivo Dockerfile](https://github.com/ropensci-review-tools/pkgcheck/blob/main/Dockerfile). + Consulte [esta vinheta `pkgcheck`](https://docs.ropensci.org/pkgcheck/articles/environment.html) para obter detalhes sobre o nosso ambiente de verificação e como modificá-lo para ajudar o seu pacote a passar nas verificações. +- Se houver algum aspecto do `pkgcheck` no qual seu o pacote não possa ser aprovado, explique os motivos no seu modelo de submissão. + + +### Manuscrito de acompanhamento (opcional) + +Se você pretende enviar um manuscrito de acompanhamento para seu o pacote, a rOpenSci tem uma parceria de colaboração com os periódicos [Journal of Open-Source Software] (https://joss.theoj.org/) e [Methods in Ecology and Evolution] (https://besjournals.onlinelibrary.wiley.com/journal/2041210X): + +- Para enviar um pacote ao Journal of Open-Source Software (JOSS), não o envie para consideração do JOSS até que o processo de revisão do rOpenSci tenha terminado: se o seu pacote for considerado dentro do escopo pelos editores do JOSS, apenas o artigo curto que o acompanha será revisado (não o software que terá sido revisado extensivamente pelo rOpenSci até aquele momento). Nem todos os pacotes da rOpenSci atenderão aos critérios do JOSS. +- Para uma submissão ao Methods in Ecology and Evolution (MEE), envie-a ao MEE somente depois que as revisoras e revisores da rOpenSci tiverem enviado suas revisões, antes ou depois de o pacote ter sido aceito. A colaboração de revisão com a MEE foi apresentada em uma [postagem de blog](https://ropensci.org/blog/2017/11/29/review-collaboration-mee/). O tipo de artigo relevante para a MEE é [*Applications*](https://besjournals.onlinelibrary.wiley.com/hub/journal/2041210X/features/applicationpapers) para obter mais detalhes. + +## O Processo de Submissão {#the-submission-process} + +- Um software é enviado/submetido para revisão através da [abertura de uma nova _issue_](https://github.com/ropensci/software-review/issues/new/choose) no repositório de revisão do software, sendo preenchido o modelo sugerido. +- O modelo sugerido começa com uma seção que inclui diversas variáveis no estilo HTML (``). Elas são usadas pelo nosso `ropensci-review-bot` e devem ser deixadas nos seus respectivos lugares, com valores preenchidos entre os pontos de início e fim indicados, assim: + +```{bash, eval=F} +insira valor aqui