diff --git a/pkg_building.pt.Rmd b/pkg_building.pt.Rmd index af01dab8d..b3891a52e 100644 --- a/pkg_building.pt.Rmd +++ b/pkg_building.pt.Rmd @@ -1,120 +1,120 @@ --- aliases: - - building.html +- building.html --- -# Packaging Guide {#building} +# Guia de desenvolvimento de pacotes {#building} ```{block, type="summaryblock"} -rOpenSci accepts packages that meet our guidelines via a streamlined [Software Peer Review process](#whatissoftwarereview). To ensure a consistent style across all of our tools we have written this chapter highlighting our guidelines for package development. Please also read and apply our [chapter about continuous integration (CI)](#ci). Further guidance for after the review process is provided in the third section of this book starting with [a chapter about collaboration](#collaboration). +A rOpenSci aceita pacotes que atendam às nossas diretrizes por meio de um processo simplificado de [Revisão por Pares de Software](#whatissoftwarereview). Para garantir um estilo consistente em todas as nossas ferramentas, escrevemos este capítulo destacando nossas diretrizes para o desenvolvimento de pacotes. Leia e aplique também nosso [capítulo sobre integração contínua (CI)](#ci). Outras orientações para depois do processo de revisão são fornecidas na terceira seção deste livro, começando com [um capítulo sobre colaboração](#collaboration). -We recommend that package developers read Hadley Wickham and Jenny Bryan's thorough book on package development which is available for [free online](https://r-pkgs.org/). Our guide is partially redundant with other resources but highlights rOpenSci's guidelines. +Recomendamos que as pessoas desenvolvedoras de pacotes leiam o livro completo de Hadley Wickham e Jenny Bryan sobre desenvolvimento de pacotes, que está disponível [gratuitamente on-line](https://r-pkgs.org/) (em inglês). Nosso guia é parcialmente redundante em relação a outros recursos, mas destaca as diretrizes da rOpenSci. - To read why submitting a package to rOpenSci is worth the effort to meet guidelines, have a look at [reasons to submit](#whysubmit). + Para saber por que vale a pena enviar um pacote para a rOpenSci para atender às diretrizes, dê uma olhada em [motivos para submeter](#whysubmit). ``` -## Package name and metadata {#package-name-and-metadata} +## Nome do pacote e metadados {#package-name-and-metadata} -### Naming your package {#naming-your-package} +### Como nomear seu pacote {#naming-your-package} -- We strongly recommend short, descriptive names in lower case. If your package deals with one or more commercial services, please make sure the name does not violate branding guidelines. You can check if your package name is available, informative and not offensive by using the [`pak::pkg_name_check()` function](https://pak.r-lib.org/reference/pkg_name_check.html); also use a search engine as you'd thus see if it's offensive in a language other than English. In particular, do *not* choose a package name that's already used on CRAN or Bioconductor. +- Recomendamos fortemente nomes curtos e descritivos em letras minúsculas. Se o seu pacote tratar de um ou mais serviços comerciais, verifique se o nome não viola as diretrizes de marca. Você pode verificar se o nome do seu pacote está disponível, é informativo e não é ofensivo usando a função [`pak::pkg_name_check()`](https://pak.r-lib.org/reference/pkg_name_check.html); use também um mecanismo de pesquisa para ver se é ofensivo em um idioma diferente do inglês. Em particular, *não* escolha um nome de pacote que já esteja sendo usado no CRAN ou no Bioconductor. -- There is a trade-off between the advantages of a unique package name and a less original package name. +- Existe um equilíbrio entre as vantagens de um nome de pacote exclusivo e um nome de pacote menos original. - - A more unique package name might be easier to track (for you and us to assess package use for instance, fewer false positives when typing its name in GitHub code search) and search (for users to ask "how to use package blah" in a search engine). - - On the other hand a *too* unique package name might make the package less discoverable (that is to say, to find it by searching "how to do this-thing in R"). It might be an argument for naming your package something very close to its topic such as [geojson](https://github.com/ropensci/geojson)). + - Um nome de pacote mais exclusivo pode ser mais fácil de rastrear (para você e nós avaliarmos o uso do pacote, por exemplo, menos falsos positivos ao digitar seu nome na pesquisa de código do GitHub) e pesquisar (para quando as pessoas usuárias perguntarem "como usar o pacote blah" em um mecanismo de pesquisa). + - Por outro lado, um nome único *demais* pode fazer com que o pacote seja menos detectável (ou seja, não seja possível encontrá-lo ao pesquisar "como fazer isso em R"). Isso pode ser um argumento para nomear seu pacote com algo muito próximo ao tópico, como [geojson](https://github.com/ropensci/geojson)). -- Find other interesting aspects of naming your package [in this blog post by Nick Tierney](https://www.njtierney.com/post/2018/06/20/naming-things/), and in case you change your mind, find out [how to rename your package in this other blog post of Nick's](https://www.njtierney.com/post/2017/10/27/change-pkg-name/). +- Encontre outros aspectos interessantes sobre como nomear seu pacote [neste texto do blog do Nick Tierney (em inglês)](https://www.njtierney.com/post/2018/06/20/naming-things/) e, caso você mude de ideia, descubra [como renomear seu pacote nesta outra postagem do blog do Nick](https://www.njtierney.com/post/2017/10/27/change-pkg-name/). -### Creating metadata for your package {#creating-metadata-for-your-package} +### Criando metadados para seu pacote {#creating-metadata-for-your-package} -We recommend you to use the [`codemetar` package](https://github.com/ropensci/codemetar) for creating and updating a JSON [CodeMeta](https://codemeta.github.io/) metadata file for your package via `codemetar::write_codemeta()`. It will automatically include all useful information, including [GitHub topics](#grooming). CodeMeta uses [Schema.org terms](https://schema.org/) so as it gains popularity the JSON metadata of your package might be used by third-party services, maybe even search engines. +Recomendamos que você use o [pacote `codemetar`](https://github.com/ropensci/codemetar) para criar e atualizar um arquivo JSON [CodeMeta](https://codemeta.github.io/) para seu pacote por meio de `codemetar::write_codemeta()`. Ele incluirá automaticamente todas as informações úteis, incluindo [tópicos do GitHub](#grooming). O CodeMeta usa [termos do Schema.org](https://schema.org/), portanto, à medida que ganha popularidade, os metadados JSON do seu pacote podem ser usados por serviços de terceiros, talvez até por mecanismos de pesquisa. -## Platforms {#platforms} +## Plataformas {#platforms} -- Packages should run on all major platforms (Windows, macOS, Linux). Exceptions may be granted packages that interact with system-specific functions, or wrappers for utilities that only operate on limited platforms, but authors should make every effort for cross-platform compatibility, including system-specific compilation, or containerization of external utilities. +- Os pacotes devem funcionar em todas as principais plataformas (Windows, macOS, Linux). Pode haver exceções para pacotes que interajam com funções específicas do sistema ou que adaptem utilitários que só funcionam em plataformas limitadas, mas deve-se fazer todo o possível para garantir a compatibilidade entre plataformas, incluindo a compilação específica em cada sistema ou a containerização de utilitários externos. -## Package API {#package-api} +## API do pacote {#package-api} -### Function and argument naming {#function-and-argument-naming} +### Nomeando funções e argumentos {#function-and-argument-naming} -- Functions and arguments naming should be chosen to work together to form a common, logical programming API that is easy to read, and auto-complete. +- A nomenclatura das funções e dos argumentos deve ser escolhida de modo a trabalhar em conjunto para formar uma API de programação comum e lógica que seja fácil de ler e de autocompletar. - - Consider an `object_verb()` naming scheme for functions in your package that take a common data type or interact with a common API. `object` refers to the data/API and `verb` the primary action. This scheme helps avoid namespace conflicts with packages that may have similar verbs, and makes code readable and easy to auto-complete. For instance, in **stringi**, functions starting with `stri_` manipulate strings (`stri_join()`, `stri_sort()`, and in **googlesheets** functions starting with `gs_` are calls to the Google Sheets API (`gs_auth()`, `gs_user()`, `gs_download()`). + - Considere um esquema de nomenclatura `objeto_verbo()` para as funções do seu pacote que usam um tipo de dados comum ou interagem com uma API comum. `objeto` refere-se aos dados/API e `verbo` a ação principal. Esse esquema ajuda a evitar conflitos de nome com pacotes que podem ter verbos semelhantes e torna o código legível e fácil de preencher automaticamente. Por exemplo, em **stringi** as funções que começam com `stri_` manipulam strings (`stri_join()`, `stri_sort()`, e em **googlesheets** funções que começam com `gs_` são chamadas para a API do Google Sheets (`gs_auth()`, `gs_user()`, `gs_download()`). -- For functions that manipulate an object/data and return an object/data of the same type, make the object/data the first argument of the function so as to enhance compatibility with the pipe operators (base R's `|>`, magrittr's `%>%`). +- Para funções que manipulam um objeto/dado e retornam um objeto/dado do mesmo tipo, faça com que o objeto/dado seja o primeiro argumento da função para aumentar a compatibilidade com o operador pipe (`|>` do R base, `%>%` do pacote magrittr). -- We strongly recommend `snake_case` over all other styles unless you are porting over a package that is already in wide use. +- Recomendamos fortemente usar `snake_case` em vez de todos os outros estilos, a menos que esteja fazendo a portabilidade de um pacote que já esteja sendo amplamente utilizado. -- Avoid function name conflicts with base packages or other popular ones (e.g. `ggplot2`, `dplyr`, `magrittr`, `data.table`) +- Evite conflitos de nomes de funções com pacotes básicos ou outros pacotes populares (por exemplo `ggplot2`, `dplyr`, `magrittr`, `data.table`) -- Argument naming and order should be consistent across functions that use similar inputs. +- A nomenclatura e a ordem dos argumentos devem ser consistentes entre as funções que usam entradas semelhantes. -- Package functions importing data should not import data to the global environment, but instead must return objects. Assignments to the global environment are to be avoided in general. +- As funções do pacote que importam dados não devem importar dados para o ambiente global, mas, em vez disso, devem retornar objetos. As atribuições ao ambiente global devem ser evitadas em geral. -### Console messages {#console-messages} +### Mensagens do console {#console-messages} -- Use either the [cli package](https://cli.r-lib.org/), or base R's tools (`message()` and `warning()`) to communicate with the user in your functions. +- Use o [pacote cli](https://cli.r-lib.org/) ou as ferramentas do R básico (`message()` e `warning()`) para se comunicar com as pessoas que usam suas funções. -- Highlights of the cli package include: automatic wrapping, respect of the [NO\_COLOR convention](https://cli.r-lib.org/articles/cli-config-user.html?q=no#no_color), many [semantic elements](https://cli.r-lib.org/articles/semantic-cli.html), and extensive documentation. Read more in a [blog post](https://blog.r-hub.io/2023/11/30/cliff-notes-about-cli/). +- Os destaques do pacote cli incluem: empacotamento automático, respeito a [convenção NO\_COLOR](https://cli.r-lib.org/articles/cli-config-user.html?q=no#no_color), muitos [elementos semânticos](https://cli.r-lib.org/articles/semantic-cli.html) e ampla documentação. Mais informações [neste texto em inglês](https://blog.r-hub.io/2023/11/30/cliff-notes-about-cli/). -- Please do not use `print()` or `cat()` unless it's for a `print.*()` or `str.*()` methods, as these methods of printing messages are harder for users to suppress. +- Por favor, não use `print()` ou `cat()` a menos que seja para um `print.*()` ou `str.*()`, pois esses métodos de impressão de mensagens são mais difíceis de serem silenciados. -- Provide a way for users to opt out of verbosity, preferably at the package level: make message creation dependent on an environment variable or option (like ["usethis.quiet"](https://usethis.r-lib.org/reference/ui.html?q=usethis.quiet#silencing-output) in the usethis package), rather than on a function parameter. The control of messages could be on several levels ("none", "inform", "debug") rather than logical (no messages at all / all messages). Control of verbosity is useful for end users but also in tests. More interesting comments can be found in an [issue of the tidyverse design guide](https://github.com/tidyverse/design/issues/42). +- Forneça uma maneira de suprimir a verbosidade, de preferência em nível de pacote: torne a criação de mensagens dependente de uma variável ou opção de ambiente (como ["usethis.quiet"](https://usethis.r-lib.org/reference/ui.html?q=usethis.quiet#silencing-output) no pacote usethis), em vez de um parâmetro da função. O controle das mensagens poderia ser feito em vários níveis ("nenhum", "informar", "debugar") em vez de ser lógico (nenhuma mensagem / todas as mensagens). O controle da verbosidade é útil para quem utiliza a função, mas também em testes. Você pode encontrar mais comentários interessantes [nesta issue do guia de design do tidyverse](https://github.com/tidyverse/design/issues/42) -- You can provide translations for your package's messages. The [potools](https://michaelchirico.github.io/potools/) R package can help you with that task. +- Você pode fornecer traduções para as mensagens do seu pacote. O pacote [potools](https://michaelchirico.github.io/potools/) pode te ajudar com essa tarefa. -### Interactive/Graphical Interfaces {#interactive-graphical-interfaces} +### Interfaces interativas/gráficas {#interactive-graphical-interfaces} -If providing a graphical user interface (GUI) (such as a Shiny app), to facilitate workflow, include a mechanism to automatically reproduce steps taken in the GUI. This could include auto-generation of code to reproduce the same outcomes, the output of intermediate values produced in the interactive tool, or simply clear and well-documented mapping between GUI actions and scripted functions. (See also ["Testing"](#testing) below.) +Se estiver fornecendo uma interface gráfica de usuário (GUI) (como um aplicativo Shiny), para facilitar o fluxo de trabalho, inclua um mecanismo para reproduzir automaticamente as etapas realizadas na GUI. Isso pode incluir a geração automática de código para reproduzir os mesmos resultados, a saída de valores intermediários produzidos na ferramenta interativa ou simplesmente um mapeamento claro e bem documentado entre as ações da GUI e as funções usadas. (Consulte também a seção ["Testes"](#testing) abaixo). -The [`tabulizer` package](https://github.com/ropensci/tabulizer) e.g. has an interactive workflow to extract tables, but can also only extract coordinates so one can re-run things as a script. Besides, two examples of shiny apps that do code generation are , and . +O [pacote `tabulizer`](https://github.com/ropensci/tabulizer) por exemplo, tem um fluxo de trabalho interativo para extrair tabelas, mas também pode extrair apenas coordenadas para que seja possível executar novamente como um script. Além disso, dois exemplos de aplicativos brilhantes que geram código são e . -### Input checking +### Verificação de entrada -We recommend your package use a consistent method of your choice for [checking inputs](https://blog.r-hub.io/2022/03/10/input-checking/) -- either base R, an R package, or custom helpers. +Recomendamos que seu pacote use um método consistente de sua escolha para [verificação de entradas (*inputs*)](https://blog.r-hub.io/2022/03/10/input-checking/) -- seja o R básico, um pacote em R ou ajudantes personalizados. -### Packages wrapping web resources (API clients) +### Pacotes que envolvem recursos da Web (clientes de API) -If your package accesses a web API or another web resource, +Se o seu pacote acessar uma API da Web ou outro recurso da Web, -- Make sure requests send an [user agent](https://httr2.r-lib.org/articles/wrapping-apis.html#user-agent), that is, a way to identify what (your package) or who sent the request. The users should be able to override the package's default user agent. Ideally, the user agent should be different on continuous integration services, and in development (based on, for instance, the GitHub usernames of the developers). -- You might choose different (better) defaults than the API, in which case you should document them. -- Your package should help with pagination, by allowing the users to not worry about it at all since your package does all necessary requests. -- Your package should help with rate limiting according to the API rules. -- Your package should reproduce API errors, and possibly explain them in informative error messages. -- Your package could export high-level functions and low-level functions, the latter allowing users to call API endpoints directly with more control (like `gh::gh()`). +- Certifique-se de que as solicitações enviem um [agente de usuário](https://httr2.r-lib.org/articles/wrapping-apis.html#user-agent), ou seja, uma maneira de identificar o que (seu pacote) ou quem enviou a solicitação. Deve ser possível substituir o agente de usuário padrão do pacote. Idealmente, o agente de usuário deve ser diferente nos serviços de integração contínua e no desenvolvimento (com base, por exemplo, nos nomes de usuário do GitHub das pessoas desenvolvedoras). +- Você pode escolher padrões diferentes (melhores) do que os da API e, nesse caso, deve documentá-los. +- Seu pacote deve ajudar com a paginação, permitindo que os usuários não se preocupem com isso, pois o pacote faz todas as solicitações necessárias. +- Seu pacote deve ajudar a limitar a taxa de acordo com as regras da API. +- Seu pacote deve reproduzir erros de API e possivelmente explicá-los em mensagens de erro informativas. +- Seu pacote pode exportar funções de alto nível e funções de baixo nível, sendo que estas últimas permitem que os usuários chamem os pontos de acesso (*endpoints*) da API diretamente com mais controle (como `gh::gh()`). -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). +Para obter mais informações, consulte a postagem do blog: [Por que você deve (ou não deve) criar um cliente de API](https://ropensci.org/blog/2022/06/16/publicize-api-client-yes-no) (em inglês). -### Packages wrapping external software {#external-software} +### Pacotes que envolvem software externo {#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). +- Documente claramente como instalar o pacote, incluindo todos os pacotes ou bibliotecas externas necessários, incluindo, quando aplicável, etapas explícitas em sistemas operacionais comuns. +- Forneça uma função de relatório de situação (sitrep) para verificar se o software foi instalado, com dicas caso algo esteja faltando. [Exemplo do pacote greta](https://github.com/greta-dev/greta/blob/50ef770a79f8c6d8b9090e94f15953f2ba155a18/R/greta-sitrep.R). +- Se possível, forneça uma função que ajude na instalação. [Exemplo no pacote hugodown](https://github.com/r-lib/hugodown/blob/main/R/hugo-install.R). -## Code Style and best practices {#code-style} +## Estilo de código e práticas recomendadas {#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/). +- Para obter mais informações sobre como estilizar seu código, nomear funções e scripts R dentro da seção `R/` recomendamos a leitura do [capítulo *R Code* do livro *R Packages*](https://r-pkgs.org/Code.html) (em inglês). Recomendamos o uso do [Air](https://posit-dev.github.io/air/) ou do [pacote styler](https://github.com/r-lib/styler) para automatizar parte do estilo do código. Também sugerimos a leitura do [Guia de estilo do Tidyverse (em inglês)](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. +- Você pode optar por usar `=` ao invés de `<-` desde que seja consistente com uma escolha em seu pacote. Recomendamos evitar o uso de `->` para atribuição em um pacote. Se você usar `<-` em seu pacote e também usar `R6` nesse pacote, você será forçado a usar `=` para atribuição em seu `R6Class` - isso não é considerado uma inconsistência porque você não pode usar `<-` nesse caso. -- 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/). +- Você pode usar o [pacote lintr](https://lintr.r-lib.org/index.html) para identificar algumas possíveis áreas de melhoria. [Exemplo de fluxo de trabalho](https://masalmon.eu/2024/08/28/lintr-3-steps/). -## CITATION file {#citation-file} +## Arquivo CITATION {#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. +- Se o seu pacote ainda não tiver um arquivo CITATION, você poderá criar um com `usethis::use_citation()` e preenchê-lo com os valores gerados pela função `citation()`. -- CRAN requires CITATION files to be declared as [`bibentry` items](https://stat.ethz.ch/R-manual/R-devel/library/utils/html/bibentry.html), and not in the previously-accepted form of [`citEntry()`](https://stat.ethz.ch/R-manual/R-devel/library/utils/html/citEntry.html). +- O CRAN exige que os arquivos CITATION sejam declarados como [itens `bibentry`](https://stat.ethz.ch/R-manual/R-devel/library/utils/html/bibentry.html) e não na forma previamente aceita de [`citEntry()`](https://stat.ethz.ch/R-manual/R-devel/library/utils/html/citEntry.html). -- If you archive each release of your GitHub repo on Zenodo, add the [Zenodo top-level DOI](https://help.zenodo.org/#versioning) to the CITATION file. +- Se você arquivar cada versão de seu repositório do GitHub no Zenodo, adicione a tag [DOI principal do Zenodo](https://help.zenodo.org/#versioning) ao arquivo CITATION. -- If one day [**after** review at rOpenSci](#authors-guide) you publish a software publication about your package, add it to the CITATION file. +- Se um dia [**depois de** revisão na rOpenSci](#authors-guide) você publicar um artigo sobre seu pacote, adicione-o ao arquivo CITATION. -- Less related to your package itself but to what supports it: if your package wraps a particular resource such as data source or, say, statistical algorithm, remind users of how to cite that resource via e.g. `citHeader()`. [Maybe even add the reference for the resource](https://discuss.ropensci.org/t/citation-of-original-article-when-implementing-specific-methods/2312). +- Menos relacionado ao seu pacote em si, mas ao que o apoia: se o seu pacote envolve um recurso específico, como uma fonte de dados ou, digamos, um algoritmo estatístico, lembre as pessoas que utilizam o software sobre como citar esse recurso por meio de, por exemplo, `citHeader()`. [Talvez até mesmo adicione a referência do recurso](https://discuss.ropensci.org/t/citation-of-original-article-when-implementing-specific-methods/2312). -As an example see [the dynamite CITATION file](https://github.com/ropensci/dynamite/blob/main/inst/CITATION) which refers to the R manual as well as other associated publications. +Como exemplo, veja [o arquivo CITATION do dynamite](https://github.com/ropensci/dynamite/blob/main/inst/CITATION) que faz referência ao manual do R, bem como a outras publicações associadas. ```r citHeader("To cite dynamite in publications use:") @@ -153,419 +153,417 @@ bibentry( ) ``` -- You could also create and store a `CITATION.cff` thanks to the [cffr package](https://docs.ropensci.org/cffr/). It also provides a [GitHub Action workflow](https://docs.ropensci.org/cffr/reference/cff_gha_update.html) to keep the `CITATION.cff` file up-to-date. +- Você também pode criar e armazenar um `CITATION.cff` graças ao [pacote cffr](https://docs.ropensci.org/cffr/). Ele também fornece um [fluxo de trabalho do GitHub Action](https://docs.ropensci.org/cffr/reference/cff_gha_update.html) para manter o `CITATION.cff` atualizado. ## README {#readme} -- All packages should have a README file, named `README.md`, in the root of the repository. The README should include, from top to bottom: +- Todos os pacotes devem ter um arquivo README, denominado `README.md` na raiz do repositório. O README deve incluir, de cima para baixo: - - The package name. - - Badges for continuous integration and test coverage, the badge for rOpenSci peer-review once it has started (see below), a repostatus.org badge, and any other badges (e.g. [R-universe](https://docs.r-universe.dev/publish/set-up.html#document-install)). - - Short description of goals of package (what does it do? why should a potential user care?), with descriptive links to all vignettes unless the package is small and there's only one vignette repeating the README. Please also ensure the vignettes are rendered and readable, see [the "documentation website" section](#website)). - - Installation instructions using e.g. the [remotes package](https://remotes.r-lib.org/), [pak package](https://pak.r-lib.org/), or [R-universe](https://docs.r-universe.dev/publish/set-up.html). - - Any additional setup required (authentication tokens, etc). - - Brief demonstration usage. - - If applicable, how the package compares to other similar packages and/or how it relates to other packages. - - Citation information i.e. Direct users to the preferred citation in the README by adding boilerplate text "here's how to cite my package". See e.g. [ecmwfr README](https://github.com/bluegreen-labs/ecmwfr#how-to-cite-this-package-in-your-article). + - O nome do pacote. + - Selos (*badges*) para integração contínua e cobertura de testes, o selo para revisão por pares da rOpenSci assim que ele for iniciado (veja abaixo), um selo do repostatus.org e quaisquer outros selos (por exemplo do [R-universe](https://docs.r-universe.dev/publish/set-up.html#document-install)). + - Uma breve descrição dos objetivos do pacote (o que ele faz? por que seria interessante usá-lo?), com links descritivos para todas as vinhetas (*vignettes*), a menos que o pacote seja pequeno e haja apenas uma vinheta repetindo o README. Certifique-se também de que as vinhetas sejam renderizadas e legíveis, consulte [a seção "site de documentação"](#website)). + - Instruções de instalação usando, por exemplo, o [pacote remotes](https://remotes.r-lib.org/), [pacote pak](https://pak.r-lib.org/) ou [R-universe](https://docs.r-universe.dev/publish/set-up.html). + - Qualquer configuração adicional necessária (tokens de autenticação, etc.). + - Breve demonstração de uso. + - Se aplicável, como o pacote se compara a outros pacotes semelhantes e/ou como ele se relaciona com outros pacotes. + - Informações de citação, ou seja, direcione a forma de citação preferida no README adicionando o texto padrão "aqui está como citar meu pacote". Veja, por exemplo [o README do pacote ecmwfr](https://github.com/bluegreen-labs/ecmwfr#how-to-cite-this-package-in-your-article). -If you use another repo status badge such as a [lifecycle](https://www.tidyverse.org/lifecycle/) badge, please also add a [repostatus.org](https://www.repostatus.org/) badge. [Example of a repo README with two repo status badges](https://github.com/ropensci/ijtiff#ijtiff-). +Se você usar outro selo de status de repositório, como o [ciclo de vida](https://www.tidyverse.org/lifecycle/), adicione também um selo do [repostatus.org](https://www.repostatus.org/). [Exemplo de um README de repositório com dois selos de status de repositório](https://github.com/ropensci/ijtiff#ijtiff-). -- Once you have submitted a package and it has passed editor checks, add a peer-review badge via +- Depois de enviar um pacote e ele ter sido aprovado na verificação editorial, adicione um selo de revisão por pares por meio do ``` [![rOpenSci software peer-review](https://badges.ropensci.org/_status.svg)](https://github.com/ropensci/software-review/issues/) ``` -where issue\_id is the number of the issue in the software-review repository. For instance, the badge for [`rtimicropem`](https://github.com/ropensci/rtimicropem) review uses the number 126 since it's the [review issue number](https://github.com/ropensci/software-review/issues/126). The badge will first indicated "under review" and then "peer-reviewed" once your package has been onboarded (issue labelled "approved" and closed), and will link to the review issue. +onde issue\_id é o número da *Issue* no repositório `software-review`. Por exemplo, o selo para [`rtimicropem`](https://github.com/ropensci/rtimicropem) usa o número 126, pois é o [número da Issue de revisão](https://github.com/ropensci/software-review/issues/126). O selo indicará primeiro "under review" (em revisão) e depois "peer-reviewed" (revisado por pares) assim que o seu pacote tiver sido integrado (Issue marcada como "approved" (aprovada) e fechada), e será vinculado à Issue de revisão. -- If your README has many badges consider ordering them in an HTML table to make it easier for newcomers to gather information at a glance. See examples in [`drake` repo](https://github.com/ropensci/drake) and in [`qualtRics` repo](https://github.com/ropensci/qualtRics/). Possible sections are +- Se o seu README tiver muitos selos, considere ordená-los em uma tabela HTML para facilitar a obtenção de informações. Veja exemplos no [repositórion`drake`](https://github.com/ropensci/drake) e no [repositório `qualtRics`](https://github.com/ropensci/qualtRics/). As seções possíveis são: - - Development (CI statuses cf [CI chapter](#ci), Slack channel for discussion, repostatus) - - Release/Published ([CRAN version and release date badges from METACRAN](https://www.r-pkg.org/services#badges), [CRAN checks API badge](https://github.com/r-hub/cchecksbadges), Zenodo badge) - - Stats/Usage (downloads e.g. [download badges from r-hub/cranlogs](https://github.com/r-hub/cranlogs.app#badges)) - The table should be more wide than it is long in order to mask the rest of the README. + - Desenvolvimento (status de integração contínua (CI), ver o [Capítulo sobre CI](#ci), canal do Slack para discussão, repostatus) + - Edição ou Publicação ([selos de versão do CRAN e data de lançamento do METACRAN](https://www.r-pkg.org/services#badges), [selo de checagem da API do CRAN](https://github.com/r-hub/cchecksbadges), selo do Zenodo) + - Estatísticas/Uso (downloads, por exemplo: [selos de quantidade de downloads do r-hub/cranlogs](https://github.com/r-hub/cranlogs.app#badges)) + A tabela deve ser mais larga do que longa para não mascarar o restante do README. -- If your package connects to a data source or online service, or wraps other software, consider that your package README may be the first point of entry for users. It should provide enough information for users to understand the nature of the data, service, or software, and provide links to other relevant data and documentation. For instance, - a README should not merely read, "Provides access to GooberDB," but also include, - "..., an online repository of Goober sightings in South America. More - information about GooberDB, and documentation of database structure and metadata - can be found at *link*". +- Se o seu pacote se conectar a uma fonte de dados ou serviço on-line, ou envolver outro software, considere que o README do seu pacote pode ser o ponto de partida de quem usa o utiliza pela primeira vez. Ele deve fornecer informações suficientes para entender a natureza dos dados, do serviço ou do software e fornecer links para outros dados e documentação relevantes. Por exemplo, + um README não deve se limitar a dizer: "Fornece acesso ao GooberDB", mas também incluir, + "..., um repositório on-line de avistamentos de Goober na América do Sul. Mais + informações sobre o GooberDB e a documentação da estrutura e dos metadados do banco de dados + podem ser encontradas em *link*". -- We recommend not creating `README.md` directly, but from a `README.Rmd` file (an R Markdown file) if you have any demonstration code. The advantage of the `.Rmd` file is you can combine text with code that can be easily updated whenever your package is updated. +- Recomendamos não criar o `README.md` diretamente, mas a partir de um `README.Rmd` (um arquivo R Markdown) se você tiver algum código de demonstração. A vantagem do `.Rmd` é que você pode combinar texto com código que pode ser facilmente atualizado sempre que seu pacote for atualizado. -- Consider using `usethis::use_readme_rmd()` to get a template for a `README.Rmd` file and to automatically set up a pre-commit hook to ensure that `README.md` is always newer than `README.Rmd`. +- Considere o uso da função `usethis::use_readme_rmd()` para obter um modelo para o arquivo `README.Rmd` e para configurar automaticamente uma verificação para garantir que o arquivo `README.md` seja sempre mais recente que o `README.Rmd` antes de fazer um commit. -- Extensive examples should be kept for a vignette. If you want to make the vignettes more accessible before installing the package, we suggest [creating a website for your package](#website). +- Exemplos extensos devem ser mantidos em uma vinheta. Se você quiser tornar as vinhetas mais acessíveis antes de instalar o pacote, sugerimos [criar um site para seu pacote](#website). -- Add a [code of conduct and contribution guidelines](#friendlyfiles). +- Adicionar um [código de conduta e as diretrizes de contribuição](#friendlyfiles). -- See the [`gistr` README](https://github.com/ropensci/gistr#gistr) for a good example README to follow for a small package, and [`bowerbird` README](https://github.com/ropensci/bowerbird) for a good example README for a larger package. +- Veja o [README do pacote `gistr`](https://github.com/ropensci/gistr#gistr) para um bom exemplo de README a ser seguido em um pacote pequeno, e [o README do pacote `bowerbird`](https://github.com/ropensci/bowerbird) para um bom exemplo de README para um pacote maior. -## Documentation {#documentation} +## Documentação {#documentation} -### General {#docs-general} +### Geral {#docs-general} -- All exported package functions should be fully documented with examples. +- Todas as funções exportadas de pacote devem ser totalmente documentadas com exemplos. -- If there is potential overlap or confusion with other packages providing similar functionality or having a similar name, add a note in the README, main vignette and potentially the Description field of DESCRIPTION. Examples in [rtweet README](https://docs.ropensci.org/rtweet/), [rebird README](https://docs.ropensci.org/rebird/#auk-vs-rebird), and the non-rOpensci package [slurmR](https://uscbiostats.github.io/slurmR/index.html#vs). +- Se houver possível sobreposição ou confusão com outros pacotes que forneçam funcionalidade semelhante ou que tenham um nome semelhante, adicione uma nota no README, na vinheta principal e, potencialmente, no campo Descrição do DESCRIPTION. Exemplos em [README do rtweet](https://docs.ropensci.org/rtweet/), [README do rebird](https://docs.ropensci.org/rebird/#auk-vs-rebird) e o pacote [slurmR](https://uscbiostats.github.io/slurmR/index.html#vs) (que não é parte da rOpenSci). -- The package should contain top-level documentation for `?foobar`, (or ``?`foobar-package` `` if there is a naming conflict). Optionally, you can use both `?foobar` and ``?`foobar-package` `` for the package level manual file, using `@aliases` roxygen tag. [`usethis::use_package_doc()`](https://usethis.r-lib.org/reference/use_package_doc.html) adds the template for the top-level documentation. +- O pacote deve conter documentação geral para `?pacote`(ou ``?`pacote-package` `` se houver um conflito de nomes). Opcionalmente, você pode usar ambos `?pacote e ``?`pacote-package` `` para o arquivo de manual do pacote, usando a etiqueta`@aliases` do roxygen. [`usethis::use_package_doc()`](https://usethis.r-lib.org/reference/use_package_doc.html) adiciona o modelo para a documentação geral. -- The package should contain at least one **HTML** vignette providing a substantial coverage of package functions, illustrating realistic use cases and how functions are intended to interact. If the package is small, the vignette and the README may have very similar content. +- O pacote deve conter pelo menos um **HTML** que ofereça uma cobertura substancial das funções do pacote, ilustrando casos de uso realistas e como as funções devem interagir. Se o pacote for pequeno, a vinheta e o README poderão ter conteúdo muito semelhante. -- As is the case for a README, top-level documentation or vignettes may be the first point of entry for users. If your package connects to a data source or online service, or wraps other software, it should provide enough information for users to understand the nature of the data, service, or software, and provide links to other relevant data and documentation. For instance, a vignette intro or documentation should not merely read, "Provides access to GooberDB," but also include, "..., an online repository of Goober sightings in South America. More information about GooberDB, and documentation of database structure and metadata can be found at *link*". Any vignette should outline prerequisite knowledge to be able to understand the vignette upfront. +- Como no caso de um README, a documentação geral ou as vinhetas podem ser o primeiro ponto de entrada para quem usa o pacote. Se o seu pacote se conectar a uma fonte de dados ou a um serviço on-line, ou envolver outro software, ele deverá fornecer informações suficientes para entender a natureza dos dados, do serviço ou do software e fornecer links para outros dados e documentação relevantes. Por exemplo, a introdução ou a documentação de uma vinheta não deve se limitar a dizer: "Fornece acesso ao GooberDB", mas também incluir: "..., um repositório on-line de avistamentos de Goober na América do Sul. Mais informações sobre o GooberDB e a documentação da estrutura e dos metadados do banco de dados podem ser encontradas no *link*". Qualquer vinheta deve descrever o conhecimento necessário para que seja possível entender a vinheta antecipadamente. -The general vignette should present a series of examples progressing in complexity from basic to advanced usage. +A vinheta geral deve apresentar uma série de exemplos que progridam em complexidade, do uso básico ao avançado. -- Functionality likely to be used by only more advanced users or developers might be better put in a separate vignette (e.g. programming/NSE with dplyr). +- A funcionalidade que provavelmente será usada apenas para desenvolvimento mais avançado pode ser melhor colocada em uma vinheta separada (por exemplo, a programação usando NSE (*non-standard evaluation*) com dplyr). -- The README, the top-level package docs, vignettes, websites, etc., should all have enough information at the beginning to get a high-level overview of the package and the services/data it connects to, and provide navigation to other relevant pieces of documentation. This is to follow the principle of *multiple points of entry* i.e. to take into account the fact that any piece of documentation may be the first encounter the user has with the package and/or the tool/data it wraps. +- O README, a documentação geral do pacote, as vinhetas, os sites etc. devem ter informações suficientes no início para obter uma visão geral de alto nível do pacote e dos serviços/dados aos quais ele se conecta e fornecer navegação para outras partes relevantes da documentação. Isso é para seguir o princípio de *vários pontos de entrada* ou seja, levar em conta o fato de que qualquer parte da documentação pode ser o primeiro encontro que alguém tem com o pacote e/ou com a ferramenta/dados que ele envolve. -- The vignette(s) should include citations to software and papers where appropriate. +- A(s) vinheta(s) deve(m) incluir citações de software e documentos, quando apropriado. -- If your package provides access to a data source, we require that DESCRIPTION contains both (1) A brief identification and/or description of the organisation responsible for issuing data; and (2) The URL linking to a public-facing page providing, describing, or enabling data access (which may often differ from URL leading directly to data source). +- Se o seu pacote fornecer acesso a uma fonte de dados, exigimos que o arquivo DESCRIPTION contenha (1) uma breve identificação e/ou descrição da organização responsável pela emissão dos dados; e (2) o URL com link para uma página pública que forneça, descreva ou permita o acesso aos dados (que muitas vezes pode ser diferente do URL que leva diretamente à fonte de dados). -- Only use package startup messages when necessary (function masking for instance). Avoid package startup messages like "This is foobar 2.4-0" or citation guidance because they can be annoying to the user. Rely on documentation for such guidance. +- Use mensagens de inicialização de pacote somente quando necessário (mascaramento de função, por exemplo). Evite mensagens de inicialização de pacotes como "Esse é o pacote 2.4-0" ou orientação de citação, pois elas podem ser irritantes para quem o utiliza. Confie na documentação para obter essa orientação. -- You can choose to have a README section about use cases of your package (other packages, blog posts, etc.), [example](https://github.com/ropensci/vcr#example-packages-using-vcr). +- Você pode optar por ter uma seção README sobre casos de uso do seu pacote (outros pacotes, publicações em blogs etc.), [exemplo](https://github.com/ropensci/vcr#example-packages-using-vcr). ### roxygen2 use {#roxygen-2-use} -- We request all submissions to use [roxygen2](https://roxygen2.r-lib.org/) for documentation. roxygen2 is an R package that compiles `.Rd` files to your `man` folder in your package from tags written above each function. roxygen2 has [support for Markdown syntax](https://roxygen2.r-lib.org/articles/rd-formatting.html). One key advantage of using roxygen2 is that your `NAMESPACE` will always be automatically generated and up to date. +- Solicitamos que todos os envios usem o [roxygen2](https://roxygen2.r-lib.org/) para a documentação. O roxygen2 é um pacote R que compila automaticamente os arquivos `.Rd` para a pasta `man` em seu pacote a partir de etiquetas escritas acima de cada função. O roxygen2 tem [suporte à sintaxe Markdown](https://roxygen2.r-lib.org/articles/rd-formatting.html). Uma das principais vantagens de usar o roxygen2 é que seu `NAMESPACE` sempre será gerado automaticamente e estará atualizado. -- More information on using roxygen2 documentation is available in the [R packages book](https://r-pkgs.org/man.html) and in [roxygen2 website itself](https://roxygen2.r-lib.org/). +- Mais informações sobre o uso da documentação do roxygen2 estão disponíveis no [capítulo sobre documentação de funções do livro *R Packages* (em inglês)](https://r-pkgs.org/man.html) e no [próprio site do roxygen2](https://roxygen2.r-lib.org/). -- If you were writing Rd directly without roxygen2, the [Rd2roxygen](https://cran.r-project.org/web/packages/Rd2roxygen/index.html) package contains functions to convert Rd to roxygen documentation. +- Se você estivesse escrevendo o `.Rd` diretamente sem o roxygen2, o [Rd2roxygen](https://cran.r-project.org/web/packages/Rd2roxygen/index.html) contém funções para converter o `.Rd` em documentação do roxygen. -- All functions should document the type of object returned under the `@return` heading. +- Todas as funções devem documentar o tipo de objeto retornado com a etiqueta `@return`. -- The default value for each parameter should be clearly documented. For example, instead of writing `A logical value determining if ...`, you should write ``A logical value (default `TRUE`) determining if ...``. It is also good practice to indicate the default values directly in your function definition: +- O valor padrão de cada parâmetro deve ser claramente documentado. Por exemplo, em vez de escrever "Um valor lógico que determina se ...", você deve escrever "Um valor lógico (por padrão `TRUE`) que determina se ...". Também é uma boa prática indicar os valores padrão diretamente na definição da função: ```{r, eval=FALSE} f <- function(a = TRUE) { - # function code + # código da função } ``` -- Documentation should support user navigation by including useful [cross-links](https://roxygen2.r-lib.org/reference/tags-index-crossref.html) between related functions and documenting related functions together in groups or in common help pages. In particular, the `@family` tags, that automatically creates "See also" links and [can help group](https://pkgdown.r-lib.org/reference/build_reference.html) functions together on pkgdown sites, is recommended for this purpose. See [the "manual" section of The R Packages book](https://r-pkgs.org/man.html) and [the "function grouping" section of the present chapter](#function-grouping) for more details. +- A documentação deve dar suporte à navegação, incluindo [links cruzados](https://roxygen2.r-lib.org/reference/tags-index-crossref.html) úteis entre funções relacionadas e documentando funções relacionadas em grupos ou em páginas de ajuda comuns. Recomendamos o uso da etiqueta `@family` que cria automaticamente links do tipo *"See also"* e [podem ajudar a agrupar](https://pkgdown.r-lib.org/reference/build_reference.html) funções em sites com pkgdown. Veja [o capítulo sobre documentação de funções do livro *R Packages* (em inglês)](https://r-pkgs.org/man.html) e [a seção "agrupamento de funções" do presente capítulo](#function-grouping) para obter mais detalhes. -- You can re-use documentation pieces (e.g. details about authentication, related packages) across the vignettes/README/man pages. Refer to [roxygen2 vignette on documentation reuse](https://roxygen2.r-lib.org/articles/reuse.html). +- Você pode reutilizar partes da documentação (por exemplo, detalhes sobre autenticação, pacotes relacionados) nas páginas de vinhetas, README e de documentação. Consulte a [vinheta do roxygen2 sobre reutilização de documentação](https://roxygen2.r-lib.org/articles/reuse.html). -- For including examples, you can use the classic `@examples` tag (plural "examples") but also the `@example ` tag (singular "example") for storing the example code in a separate R script (ideally under `man/`), and the `@exampleIf` tag for running examples conditionally and avoiding R CMD check failures. Refer to [roxygen2 documentation about examples](https://roxygen2.r-lib.org/articles/rd.html#examples). +- Para incluir exemplos, você pode usar o clássico `@examples` (no plural *"examples"*), mas também a tag `@example ` (no singular *"example"*) para armazenar o código de exemplo em um script R separado (de preferência na pasta `man/`), e a tag `@exampleIf` para executar exemplos condicionalmente e evitar falhas na verificação do R CMD. Consulte a [documentação do roxygen2 sobre exemplos](https://roxygen2.r-lib.org/articles/rd.html#examples). -- Add `#' @noRd` to internal functions. You might be interested in the [devtag experimental package](https://github.com/moodymudskipper/devtag) for getting local manual pages when using `#' @noRd`. +- Adicionar `#' @noRd` às funções internas. Talvez você se interesse no [pacote experimental devtag](https://github.com/moodymudskipper/devtag) para obter páginas de manual locais ao usar `#' @noRd`. -- Starting from roxygen2 version 7.0.0, `R6` classes are officially supported. See the [roxygen2 docs](https://roxygen2.r-lib.org/articles/rd-other.html#r6) for details on how to document `R6` classes. +- A partir da versão 7.0.0 do roxygen2, as classes `R6` são oficialmente suportadas. Consulte a [documentação do roxygen2](https://roxygen2.r-lib.org/articles/rd-other.html#r6) para obter detalhes sobre como documentar classes `R6`. -- There is no support for providing manual pages in different languages yet, but some interesting progress in the [rhelpi18n R package](https://github.com/eliocamp/rhelpi18n). +- Ainda não há suporte para o fornecimento de páginas de manual em diferentes idiomas, mas há um progresso interessante no projeto de [pacote em R rhelpi18n](https://github.com/eliocamp/rhelpi18n). -### Example datasets {#example-datasets} +### Exemplos de conjuntos de dados {#example-datasets} -To document your package's interface, you might need to use example datasets. -You can either use base R datasets (in the datasets package) such as penguins, or [re-distribute and document data](https://r-pkgs.org/data.html), with proper attributions. -Be careful to choose data that comply with the [rOpenSci's code of conduct](https://ropensci.org/code-of-conduct/) and generally is not hurtful or alienating to anyone. +Para documentar a interface do seu pacote, talvez seja necessário usar conjuntos de dados de exemplo. +Você pode usar conjuntos de dados básicos do R (no pacote datasets), como `penguins`, ou [redistribuir e documentar os dados](https://r-pkgs.org/data.html) com as devidas atribuições. +Tenha o cuidado de escolher dados que estejam em conformidade com o [código de conduta da rOpenSci](https://ropensci.org/code-of-conduct/) e que, em geral, não sejam prejudiciais ou alienantes para ninguém. -### URLs in documentation {#ur-ls-in-documentation} +### URLs na documentação {#ur-ls-in-documentation} -This subsection is particularly relevant to authors wishing to submit their package to CRAN. -CRAN will check URLs in your documentation and does not allow redirect status codes such as 301. -You can use the [urlchecker](https://github.com/r-lib/urlchecker) package to reproduce these checks and, in particular, replace URLs with the URLs they redirect to. -Others have used the option to escape some URLs (change `` to `https://ropensci.org/`, or `\url{https://ropensci.org/}` to `https://ropensci.org/`.), but if you do so, you will need to implement some sort of URL checking yourself to prevent them from getting broken without your noticing. Furthermore, links would not be clickable from local docs. +Esta subseção é particularmente relevante para quem deseja enviar seu pacote para o CRAN. +O CRAN verificará os URLs em sua documentação e não permite códigos de status de redirecionamento, como 301. +Você pode usar o pacote [urlchecker](https://github.com/r-lib/urlchecker) para reproduzir essas verificações e, em particular, substituir os URLs pelos URLs para os quais eles redirecionam. +Outras pessoas já usaram a opção para escapar de alguns URLs (alterar `` para `https://ropensci.org/`, ou `\url{https://ropensci.org/}` para `https://ropensci.org/`.), mas se você fizer isso, precisará implementar algum tipo de verificação de URL para evitar que eles sejam quebrados sem que você perceba. Além disso, os links não poderão ser clicados nos documentos locais. -## Documentation website {#website} +## Site de documentação {#website} -We recommend creating a documentation website for your package using [`pkgdown`](https://github.com/r-lib/pkgdown). The R packages book features a [chapter on pkgdown](https://r-pkgs.org/website.html), and of course `pkgdown` has [its own documentation website](https://pkgdown.r-lib.org/). +Recomendamos a criação de um site de documentação para seu pacote usando o pacote [`pkgdown`](https://github.com/r-lib/pkgdown). O livro *R packages* (em inglês) apresenta um [capítulo sobre pkgdown](https://r-pkgs.org/website.html) e também o `pkgdown` tem [seu próprio site de documentação](https://pkgdown.r-lib.org/). -There are a few elements we'd like to underline here. +Há alguns elementos que gostaríamos de destacar aqui. -### Automatic deployment of the documentation website {#docsropensci} +### Implementação automática do site de documentação {#docsropensci} -You only need to worry about automatic deployment of your website until approval and transfer of your package repo to the ropensci organization; indeed, after that a pkgdown website will be built for your package after each push to the GitHub repo. You can find the status of these builds at `https://dev.ropensci.org/job/package_name`, e.g. [for `magick`](https://dev.ropensci.org/job/magick); and the website at `https://docs.ropensci.org/package_name`, e.g. [for `magick`](https://docs.ropensci.org/magick). The website build will use your pkgdown config file if you have one, except for the styling that will use the [`rotemplate` package](https://github.com/ropensci-org/rotemplate/). The resulting website will have a local search bar. Please report bugs, questions and feature requests about the central builds at and about the template at . +Você só precisa se preocupar com a implementação automática (*automatic deployment*) do seu site até a aprovação e a transferência do repositório do seu pacote para a organização ropensci; de fato, depois disso, um site pkgdown será criado para o seu pacote após cada *push* para o repositório do GitHub. Você pode encontrar o status dessas compilações em `https://dev.ropensci.org/job/package_name` por exemplo [para `magick`](https://dev.ropensci.org/job/magick); e o site em `https://docs.ropensci.org/package_name` por exemplo [para `magick`](https://docs.ropensci.org/magick). A construção do site usará seu arquivo de configuração pkgdown, se você tiver um, exceto para o estilo que usará o arquivo [de modelo do pacote`rotemplate`](https://github.com/ropensci-org/rotemplate/). O site resultante terá uma barra de pesquisa local. Pedimos que informe erros, perguntas e solicitações de recursos sobre a implementação automática em e sobre o modelo em . -*If your package vignettes need credentials (API keys, tokens, etc.) to knit, you might want to [precompute them](https://ropensci.org/technotes/2019/12/08/precompute-vignettes/) since credentials cannot be used on the docs server.* +*Se as vinhetas do seu pacote precisarem de credenciais (chaves de API, tokens, etc.) para serem ativadas, talvez você queira [renderizar as vinhetas previamente](https://ropensci.org/technotes/2019/12/08/precompute-vignettes/), já que as credenciais não podem ser usadas no servidor de documentos.* -Before submission and before transfer, you could use the [approach documented by `pkgdown`](https://pkgdown.r-lib.org/reference/deploy_site_github.html) or the [`tic` package](https://docs.ropensci.org/tic/) for automatic deployment of the package's website. This would save you the hassle of running (and remembering to run) `pkgdown::build_site()` yourself every time the site needs to be updated. First refer to our [chapter on continuous integration](#ci) if you're not familiar with continuous integration. In any case, do not forget to update all occurrences of the website URL after transfer to the ropensci organization. +Antes do envio e da transferência do pacote, você pode usar a [abordagem documentada por `pkgdown`](https://pkgdown.r-lib.org/reference/deploy_site_github.html) ou o [pacote `tic`](https://docs.ropensci.org/tic/) para a implantação automática do site do pacote. Isso evitaria o incômodo de executar (e lembrar de executar) `pkgdown::build_site()` toda vez que o site precisar ser atualizado. Primeiro, consulte nosso [capítulo sobre integração contínua](#ci) se você não estiver familiarizado com a integração contínua. De qualquer forma, não se esqueça de atualizar todas as ocorrências do URL do site após a transferência para a organização ropensci. -### Language +### Idioma -If your package's documentation is written in a language other than English (but supported by the rOpenSci software peer-review system), you can declare that language for your pkgdown website to be [localized](https://pkgdown.r-lib.org/articles/translations.html). +Se a documentação do seu pacote estiver escrita em um idioma diferente do inglês (mas suportado pelo sistema de revisão por pares do software rOpenSci), você poderá declarar esse idioma para que o site do pkgdown [seja localizado](https://pkgdown.r-lib.org/articles/translations.html). -It is [not yet possible to get a multilingual pkgdown website](https://github.com/r-lib/pkgdown/issues/2258) out of the box. +Porém, [ainda não é possível obter um site pkgdown multilíngue](https://github.com/r-lib/pkgdown/issues/2258) diretamente. -### Grouping functions in the reference {#function-grouping} +### Agrupamento de funções no índice {#function-grouping} -When your package has many functions, use grouping in the reference, which you can do more or less automatically. +Quando seu pacote tiver muitas funções, é conveniente que apareçam agrupadas no índice da documentação, o que pode ser feito de forma mais ou menos automática. -If you use roxygen2 above version 6.1.1, you should use the `@family` tag in your functions documentation to indicate grouping. This will give you links between functions in the local documentation of the installed package ("See also" section) *and* allow you to use the `pkgdown` `has_concept` function in the config file of your website. Non-rOpenSci example courtesy of [`optiRum`](https://github.com/lockedata/optiRum): [family tag](https://github.com/lockedata/optiRum/blob/master/R/APR.R#L17), [`pkgdown` config file](https://github.com/lockedata/optiRum/blob/master/_pkgdown.yml) and [resulting reference section](https://itsalocke.com/optirum/reference/). -To customize the text of the cross-reference title created by roxygen2 (`Other {family}:`), refer to [roxygen2 docs regarding how to provide a `rd_family_title` list in `man/roxygen/meta.R`](https://roxygen2.r-lib.org/articles/rd.html#cross-references). +Se você usa o roxygen2 acima da versão 6.1.1, deve usar a tag `@family` na documentação de suas funções para indicar o agrupamento. Isso lhe dará links entre as funções na documentação local do pacote instalado (seção *"See also"*) *e* permitirá que você use a função `has_concept` do pacote `pkgdown` no arquivo de configuração do seu site. Exemplo não relacionado a rOpenSci, cortesia de [`optiRum`](https://github.com/lockedata/optiRum): [tag family](https://github.com/lockedata/optiRum/blob/master/R/APR.R#L17), [arquivo de configuração do `pkgdown`](https://github.com/lockedata/optiRum/blob/master/_pkgdown.yml) e [seção no índice resultante](https://itsalocke.com/optirum/reference/). +Para personalizar o texto do título da referência cruzada criada pelo roxygen2 (`Other {family}:`), consulte [a documentação do roxygen2 sobre como fornecer uma lista `rd_family_title` no arquivo `man/roxygen/meta.R`](https://roxygen2.r-lib.org/articles/rd.html#cross-references). -Less automatically, see the example of [`drake` website](https://docs.ropensci.org/drake/) and [associated config file +De forma menos automática, veja o exemplo do [website do pacote `drake`](https://docs.ropensci.org/drake/) e [arquivo de configuração associado ](https://github.com/ropensci/drake/blob/master/_pkgdown.yml). -### Branding of authors {#branding-of-authors} +### Marca de autoria {#branding-of-authors} -You can make the names of (some) authors clickable by adding their URL, and you can even replace their names with a logo (think rOpenSci... or your organisation/company!). See [`pkgdown` documentation](https://pkgdown.r-lib.org/reference/build_home.html?q=authors#yaml-config-authors). +Você pode tornar os nomes de (algumas) das pessoas autoras clicáveis, adicionando um URL, e pode até mesmo substituir os nomes por um logotipo (pense na rOpenSci... ou na sua organização/empresa!). Veja [a documentação do `pkgdown`](https://pkgdown.r-lib.org/reference/build_home.html?q=authors#yaml-config-authors). -### Tweaking the navbar {#tweaking-the-navbar} +### Ajustando a barra de navegação {#tweaking-the-navbar} -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`. +Você pode tornar o conteúdo do seu site mais fácil de navegar ajustando a barra de navegação, consulte [a documentação do `pkgdown`](https://pkgdown.r-lib.org/articles/pkgdown.html#navigation-bar). Em particular, observe que, se você nomear a vinheta principal de seu pacote como "pkg-name.Rmd", ela poderá ser acessada na barra de navegação como `Para começar` (*Get started*) em vez de via `Artigos > Título da vinheta` (*Articles > Vignette Title*). -### Math rendering {#mathjax} +### Renderização matemática {#mathjax} -Please refer to [pkgdown documentation](https://pkgdown.r-lib.org/dev/articles/customise.html#math-rendering). -Our template is compatible with this configuration. +Consulte a [documentação do pkgdown](https://pkgdown.r-lib.org/dev/articles/customise.html#math-rendering). +Nosso modelo é compatível com essa configuração. -### Package logo {#package-logo} +### Logotipo do pacote {#package-logo} -To use your package logo on the pkgdown homepage, refer to [`usethis::use_logo()`](https://usethis.r-lib.org/reference/use_logo.html). -If your package doesn't have any logo, the [rOpenSci docs builder](#docsropensci) will use the rOpenSci logo instead. +Para usar o logotipo de seu pacote na página inicial do pkgdown, consulte [`usethis::use_logo()`](https://usethis.r-lib.org/reference/use_logo.html). +Se o seu pacote não tiver um logotipo, o [construtor de documentos da rOpenSci](#docsropensci) usará o logotipo da rOpenSci em seu lugar. -## Authorship {#authorship} +## Autoria {#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.), and using the comment field to indicate the [ORCID ID](https://ropensci.org/technotes/2018/10/08/orcid/) of each author who is a person and the [ROR ID](https://ropensci.org/blog/2025/05/09/ror/) of each author that is an organization, if they have one. -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: +O arquivo DESCRIPTION de um pacote deve listar as pessoas que participaram da autoria e que colaboraram com o pacote, usando o parâmetro `Authors@R` para indicar suas funções (*author*/*creator*/*contributor*, etc.) e usando o campo de comentário para indicar o [ID do ORCID](https://ropensci.org/technotes/2018/10/08/orcid/) de cada pessoa e o [ID ROR](https://ropensci.org/blog/2025/05/09/ror/) de cada organização, se houver. +Veja [esta seção de "Escrevendo extensões R"](https://cran.rstudio.com/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file) para obter detalhes. +Se você achar que as pessoas que revisaram fizeram uma contribuição substancial para o desenvolvimento do seu pacote, poderá listá-los na seção `Authors@R` com o tipo de contribuição `"rev"`, da seguinte forma: ``` person("Bea", "Hernández", role = "rev", - comment = "Bea reviewed the package (v. X.X.XX) for rOpenSci, see "), + comment = "Bea revisou o pacote (v. X.X.XX) para rOpenSci, veja "), ``` -Only include reviewers after asking for their consent. -Read more in this blog post ["Thanking Your Reviewers: Gratitude through Semantic Metadata"](https://ropensci.org/blog/2018/03/16/thanking-reviewers-in-metadata/). -Please do not list editors as contributors. -Your participation in and contribution to rOpenSci is thanks enough! +Somente inclua revisores(as) depois de pedir seu consentimento. +Leia mais nesta postagem do blog [*Thanking Your Reviewers: Gratitude through Semantic Metadata* ("Agradecendo as revisões: Gratidão por meio de metadados semânticos")](https://ropensci.org/blog/2018/03/16/thanking-reviewers-in-metadata/). +Por favor, não liste pessoas editoras como colaboradoras. +Sua participação e contribuição para a rOpenSci já são agradecimentos suficientes! -### Authorship of included code {#authorship-included-code} +### Autoria do código incluído no pacote {#authorship-included-code} -Many packages include code from other software. Whether entire files or single functions are included from other packages, rOpenSci packages should follow [the CRAN *Repository Policy*](https://cran.r-project.org/web/packages/policies.html): +Muitos pacotes incluem códigos de outros softwares. Se arquivos inteiros ou funções individuais forem incluídos de outros pacotes, os pacotes rOpenSci devem seguir [a *Política de Repositório* do CRAN](https://cran.r-project.org/web/packages/policies.html): -> The ownership of copyright and intellectual property rights of all components of the package must be clear and unambiguous (including from the authors specification in the DESCRIPTION file). Where code is copied (or derived) from the work of others (including from R itself), care must be taken that any copyright/license statements are preserved and authorship is not misrepresented. +> A propriedade dos direitos autorais e de propriedade intelectual de todos os componentes do pacote deve ser clara e inequívoca (inclusive a partir da especificação de autoria no arquivo DESCRIPTION). Quando o código for copiado (ou derivado) do trabalho de outros (inclusive do próprio R), deve-se tomar cuidado para que quaisquer declarações de direitos autorais/licenças sejam preservadas e a autoria não seja deturpada. > -> Preferably, an 'Authors@R' field would be used with 'ctb' roles for the authors of such code. Alternatively, the 'Author' field should list these authors as contributors. +> De preferência, um campo 'Authors@R' seria usado com funções 'ctb' para quem tem a autoria deste código. Como alternativa, o campo "Autor" deve listar essas pessoas como colaboradoras. > -> Where copyrights are held by an entity other than the package authors, this should preferably be indicated via 'cph' roles in the 'Authors@R' field, or using a 'Copyright' field (if necessary referring to an inst/COPYRIGHTS file). +> Quando os direitos autorais forem detidos por uma entidade que não seja as pessoas autoras do pacote, isso deve ser indicado preferencialmente por meio das funções 'cph' no campo 'Authors@R' ou usando um campo 'Copyright' (se necessário, referindo-se a um arquivo inst/COPYRIGHTS). > -> Trademarks must be respected. +> As marcas registradas devem ser respeitadas. -## Licence {#licence} +## Licença {#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. -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). +O pacote precisa ter uma licença aceita pelo [CRAN](https://svn.r-project.org/R/trunk/share/licenses/license.db) ou [OSI](https://opensource.org/licenses). +O [livro *R packages* (em inglês)](https://r-pkgs.org/description.html#sec-description-authors-at-r) inclui uma seção útil [sobre licenças](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). +Se o seu pacote agrupar código de outras fontes, você também precisará reconhecer a autoria do código original no seu arquivo DESCIPTION, geralmente com uma função de detentor de direitos autorais: `role = "cph"`. +Para saber como atualizar seu arquivo DESCRIPTION, consulte [o livro *R packages* (em inglês)](https://r-pkgs.org/description.html#sec-description-authors-at-r). -## Testing {#testing} +## Testes {#testing} -- All packages should pass `R CMD check`/`devtools::check()` on all major platforms. +- Todos os pacotes devem passar nas verificações do `R CMD check`/`devtools::check()` em todas as principais plataformas. -- All packages should have a test suite that covers major functionality of the package. The tests should also cover the behavior of the package in case of errors. +- Todos os pacotes devem ter um conjunto de testes que abranja a funcionalidade principal do pacote. Os testes também devem abranger o comportamento do pacote em caso de erros. -- It is good practice to write unit tests for all functions, and all package code in general, ensuring key functionality is covered. Test coverage below 75% will likely require additional tests or explanation before being sent for review. +- É uma boa prática escrever testes unitários para todas as funções e para todo o código do pacote em geral, garantindo que a funcionalidade principal seja coberta. Se a cobertura de testes em seu pacote está abaixo de 75%, provavelmente exigirá testes adicionais ou explicações antes de ser enviado para revisão. -- We recommend using [testthat](https://testthat.r-lib.org/) for writing tests. An alternative is [tinytest](https://journal.r-project.org/archive/2021/RJ-2021-056/index.html). +- Recomendamos o uso do [pacote testthat](https://testthat.r-lib.org/) para escrever testes. Uma alternativa é o [tinytest](https://journal.r-project.org/archive/2021/RJ-2021-056/index.html). -- 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). +- Se esforce para escrever testes ao escrever cada nova função. Isso atende à necessidade óbvia de ter um teste adequado para o pacote, mas permite que você pense sobre as várias maneiras pelas quais uma função pode falhar e programe *defensivamente* contra essas falhas. [Mais informações sobre testes](https://r-pkgs.org/tests.html). -- 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. +- Os testes devem ser fáceis de entender e ser tão autocontidos quanto possível. Ao usar o testthat, evite usar código fora do `test_that()` (como etapas de pré-processamento). Recomendamos a leitura da seção [*"high-level principles for testing"* (princípios de alto nível para testes)](https://r-pkgs.org/testing-design.html#sec-testing-design-principles) no *livro R Packages*. -- 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. +- Os pacotes com aplicativos Shiny devem usar uma estrutura de testes unitários, como [`shinytest2`](https://rstudio.github.io/shinytest2/) ou [`shinytest`](https://rstudio.github.io/shinytest/articles/shinytest.html) para testar se as interfaces interativas se comportam conforme o esperado. -- For testing your functions creating plots, we suggest using [vdiffr](https://vdiffr.r-lib.org/), an extension of the testthat package that relies on [testthat snapshot tests](https://testthat.r-lib.org/articles/snapshotting.html). +- Para testar as funções que criam gráficos, sugerimos usar o [vdiffr](https://vdiffr.r-lib.org/), uma extensão do pacote testthat que se baseia em [testes com snapshots do testthat](https://testthat.r-lib.org/articles/snapshotting.html). -- If your package interacts with web resources (web APIs and other sources of data on the web) you might find the [HTTP testing in R book by Scott Chamberlain and Maëlle Salmon](https://books.ropensci.org/http-testing/) relevant. Packages helping with HTTP testing (corresponding HTTP clients): +- Se o seu pacote interagir com recursos da Web (APIs da Web e outras fontes de dados na Web), você poderá achar o livro [*HTTP testing in R*, de Scott Chamberlain e Maëlle Salmon](https://books.ropensci.org/http-testing/) relevante. Alguns pacotes que ajudam nos testes de HTTP (e seus clientes HTTP correspondentes) são: - [httptest2](https://enpiar.com/httptest2/) ([httr2](https://httr2.r-lib.org/)); - [httptest](https://enpiar.com/r/httptest/) ([httr](https://httr.r-lib.org/)); - [vcr](https://docs.ropensci.org/vcr/) ([httr](https://httr.r-lib.org/), [crul](https://docs.ropensci.org/crul)); - [webfakes](https://webfakes.r-lib.org/) ([httr](https://httr.r-lib.org/), [httr2](https://httr2.r-lib.org/), [crul](https://docs.ropensci.org/crul), [curl](https://jeroen.r-universe.dev/curl#)). -- testthat has a function `skip_on_cran()` that you can use to not run tests on CRAN. We recommend using this on all functions that are API calls since they are quite likely to fail on CRAN. These tests should still run on continuous integration. Note that from testthat 3.1.2 `skip_if_offline()` automatically calls `skip_on_cran()`. More info on [CRAN preparedness for API wrappers](https://books.ropensci.org/http-testing/cran-preparedness.html). +- O pacote testthat tem uma função `skip_on_cran()` que você pode usar para não executar testes no CRAN. Recomendamos usar isso em todas as funções que são chamadas de API, pois é muito provável que elas falhem no CRAN. Esses testes ainda devem ser executados na integração contínua. Observe que a partir do testthat 3.1.2 `skip_if_offline()` chama automaticamente `skip_on_cran()`. Mais informações sobre em [*CRAN preparedness for API wrappers* (Preparação do CRAN para utilização de APIs)](https://books.ropensci.org/http-testing/cran-preparedness.html). -- If your package interacts with a database you might find [dittodb](https://docs.ropensci.org/dittodb) useful. +- Se o seu pacote interagir com um banco de dados, você poderá achar o pacote [dittodb](https://docs.ropensci.org/dittodb) útil. -- Once you've set up [continuous integration (CI)](#ci), use your package's code coverage report (cf [this section of our book](#coverage)) to identify untested lines, and to add further tests. +- Depois de configurar a [integração contínua (CI)](#ci) use o relatório de cobertura de código do seu pacote (veja [esta seção do nosso livro](#coverage)) para identificar linhas não testadas e adicionar mais testes. -- Even if you use [continuous integration](#ci), we recommend that you run tests locally prior to submitting your package (you might need to set `Sys.setenv(NOT_CRAN="true")`). +- Mesmo que você use a [integração contínua](#ci), recomendamos que você execute testes localmente antes de enviar seu pacote (talvez seja necessário definir `Sys.setenv(NOT_CRAN="true")`). -## Examples {#examples} +## Exemplos {#examples} -- Include extensive examples in the documentation. In addition to demonstrating how to use the package, these can act as an easy way to test package functionality before there are proper tests. However, keep in mind we require tests in contributed packages. +- Inclua exemplos abrangentes na documentação. Além de demonstrar como usar o pacote, eles podem funcionar como uma maneira fácil de testar a funcionalidade do pacote antes de haver testes adequados. No entanto, lembre-se de que exigimos testes em pacotes contribuídos. -- 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. +- Você pode executar exemplos com `devtools::run_examples()`. Observe que quando você executa o R CMD CHECK ou equivalente (por exemplo, `devtools::check()`), seus exemplos que não estão incluídos no `\dontrun{}` ou `\donttest{}` são executados. Consulte a seção [tabela de resumo](https://roxygen2.r-lib.org/articles/rd.html#functions) na documentação do roxygen2. -- To safeguard 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. In this case, you might add some small toy examples, or wrap the example code in `try()`. Also refer to the `@exampleIf` tag present, at the time of writing, in the roxygen2 development version. +- Para evitar que os exemplos sejam executados no CRAN (por exemplo, se requerem autenticação), você precisa usar `\dontrun{}`. No entanto, para uma primeira submissão, o CRAN não permitirá que você pule todos os exemplos. Nesse caso, você pode adicionar alguns pequenos exemplos de brinquedo, ou envolver o código de exemplo com `try()`. Consulte também a etiqueta `@exampleIf` do roxygen2. -- 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`. +- Além de executar exemplos localmente em seu próprio computador, é altamente recomendável que você execute exemplos em um dos [sistemas de integração contínua](#ci). Mais uma vez, os exemplos que não estão incluídos em `\dontrun{}` ou `\donttest{}` serão executados, mas para aqueles que estão, você pode configurar suas compilações de integração contínua para executá-los por meio dos argumentos de verificação do R CMD `--run-dontrun` e/ou `--run-donttest`. -## Package dependencies {#pkgdependencies} +## Dependências de pacotes {#pkgdependencies} -- It is very generally better to have fewer dependencies. +- Em geral, é melhor ter menos dependências. -- 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. +- Considere as vantagens e desvantagens envolvidas no fato de depender de um pacote. Por um lado, + o uso de dependências reduz o esforço de codificação e pode se basear em funcionalidades úteis desenvolvidas por + outras pessoas, especialmente se a dependência executar tarefas complexas e tiver alto desempenho, + e/ou for bem avaliada e testada. Por outro lado, ter muitas dependências + sobrecarrega a pessoa mantenedora ao ter que acompanhar as alterações nesses pacotes, arriscando +a sustentabilidade de longo prazo do seu pacote. Isso também + aumenta o tempo e o tamanho da instalação, o que leva em consideração principalmente o seu ciclo de desenvolvimento e o de outras pessoas, bem como os sistemas de compilação automatizados. Pacotes "pesados" - aqueles com muitas dependências e aqueles com grandes quantidades de código compilado - aumentam esse custo. -- Approaches to reducing dependencies include: +- As abordagens para reduzir as dependências incluem: - - Small, simple functions from a dependency package may be better copied into - your own package if the dependency is used only for a few functions - in an otherwise large or heavy dependency. (See [*Authorship* section - above](#authorship-included-code) for how to acknowledge original authors - of copied code.) On the other hand, complex functions with many edge - cases (e.g. parsers) require considerable testing and vetting. + - Se você usar apenas algumas funções de uma dependência grande ou pesada, poderá copiá-las para seu próprio pacote. (Consulte [a seção *Autoria* + acima](#authorship-included-code) para saber como reconhecer a autoria original + do código copiado). Por outro lado, funções complexas com muitos + casos especiais (por exemplo, analisadores sintáticos) exigem testes e verificações consideráveis. - - A common example of this is in returning tidyverse-style "tibbles" from package - functions that provide data. - One can avoid the modestly heavy **tibble** package dependency by returning - a tibble created by modifying a data frame like so: + - Um exemplo comum disso é o retorno de "tibbles" no estilo tidyverse + em funções do pacote que fornecem dados. + É possível evitar o uso do pacote **tibble** retornando + um tibble criado pela modificação de um *data.frame* da seguinte forma: ``` class(df) <- c("tbl_df", "tbl", "data.frame") ``` - (Note that this approach should be very carefully used and tested, especially as it may break expected behaviour of re-classed objects.) + (Observe que essa abordagem deve ser usada e testada com muito cuidado, especialmente porque pode quebrar o comportamento esperado de objetos reclassificados). - - 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 - should be imported from **magrittr**, where it is defined, rather than the heavier - **dplyr**, which re-exports it. + - Certifique-se de que esteja usando o pacote em que a função está definida, + e não aquele em que ela é reexportada. Por exemplo, muitas funções do **devtools** podem ser encontradas em pacotes especializados menores, como **sessioninfo**. A função `%>%` + deve ser importada do pacote **magrittr** onde ela é definida, em vez do mais pesado + **dplyr** , que a reexporta. - - Some dependencies are preferred because they provide easier to interpret - function names and syntax than base R solutions. If this is the primary - reason for using a function in a heavy dependency, consider wrapping - the base R approach in a nicely-named internal function in your package. See e.g. the [rlang R script providing functions with a syntax similar to purrr functions](https://github.com/r-lib/rlang/blob/9b50b7a86698332820155c268ad15bc1ed71cc03/R/standalone-purrr.R). + - Algumas dependências são preferidas porque fornecem uma interpretação mais fácil de + nomes de funções e sintaxe mais fáceis do que as soluções básicas do R. Se esse for o principal + motivo para usar uma função em uma dependência pesada, considere a possibilidade de envolver + a abordagem do R básico em uma função interna bem nomeada em seu pacote. Veja, por exemplo, o [script em R do rlang que fornece funções com uma sintaxe semelhante às funções purrr](https://github.com/r-lib/rlang/blob/9b50b7a86698332820155c268ad15bc1ed71cc03/R/standalone-purrr.R). - - If dependencies have overlapping functionality, see if you can rely on only one. + - Se as dependências tiverem funcionalidades sobrepostas, verifique se você pode confiar em apenas uma delas. - - 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 + - Mais dicas de gerenciamento de dependências podem ser encontradas no capítulo [*"Dependencies: Mindset and Background"* do livro *R packages* (em inglês)](https://r-pkgs.org/dependencies-mindset-background.html) e em um [post do 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`. +- Usar `Imports` em vez de `Depends` para pacotes que fornecem funções de outros pacotes. Certifique-se de listar os pacotes usados para o teste (`testthat`) e a documentação (`knitr`, roxygen2) em seu `Suggests` das dependências do pacote (se você usar `usethis` para adicionar a infraestrutura de teste via [`usethis::use_testthat()`](https://usethis.r-lib.org/reference/use_testthat.html) ou uma vinheta via [usethis::use\_vignette()](https://usethis.r-lib.org/reference/use_vignette.html), os pacotes necessários serão adicionados ao DESCRIPTION). Se você usar algum pacote nos exemplos ou testes do seu pacote, certifique-se de listá-lo em `Suggests` se ainda não estiver listado em `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/). +- Verifique o status de desenvolvimento de todas as dependências que você adicionar. + Especialmente para pacotes hospedados no GitHub, é muito útil verificar se eles são mantidos ativamente e se [não foram arquivados](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. +- Se o seu pacote (não do Bioconductor) depender de pacotes do Bioconductor, certifique-se de que as instruções de instalação no README e na vinheta sejam claras o suficiente, mesmo para uma pessoa não esteja familiarizada com o ciclo de publicação do Bioconductor. - - Should the user use [`BiocManager`](https://www.bioconductor.org/install/index.html#why-biocmanagerinstall) (recommended)? Document this. + - É necessário usar o [`BiocManager`](https://www.bioconductor.org/install/index.html#why-biocmanagerinstall) (recomendado)? Documente isso. - - Is the automatic installation of Bioconductor packages by `install.packages()` enough? In that case, mention that the user needs to run `setRepositories()` if they haven't set the necessary Bioconductor repositories yet. + - A instalação automática de pacotes do Bioconductor usando `install.packages()` é suficiente? Nesse caso, mencione que é necessário executar `setRepositories()` se ainda não tiver definido os repositórios necessários do Bioconductor. - - If your package depends on Bioconductor after a certain version, mention it in DESCRIPTION and the installation instructions. + - Se o seu pacote depender do Bioconductor após uma determinada versão, mencione isso na DESCRIPTION e nas instruções de instalação. -- Specifying minimum dependencies (e.g. `glue (>= 1.3.0)` instead of just `glue`) should be a conscious choice. If you know for a fact that your package will break below a certain dependency version, specify it explicitly. - But if you don't, then no need to specify a minimum dependency. In that case when a user reports a bug which is explicitly related to an older version of a dependency then address it then. - An example of bad practice would be for a developer to consider the versions of their current state of dependencies to be the minimal version. That would needlessly force everyone to upgrade (causing issues with other packages) when there is no good reason behind that version choice. +- Especificar dependências mínimas (por exemplo `glue (>= 1.3.0)` em vez de apenas `glue`) deve ser uma escolha consciente. Se tiver certeza de que seu pacote quebrará abaixo de uma determinada versão de dependência, especifique-a explicitamente. + Mas se não souber, então não há necessidade de especificar uma dependência mínima. Nesse caso, quando um usuário relatar um bug que esteja explicitamente relacionado a uma versão mais antiga de uma dependência, resolva-o. + Um exemplo de prática ruim seria, ao desenvolver o pacote, considerar as versões atuais de suas dependências como sendo a versão mínima. Isso forçaria desnecessariamente todos a atualizar (causando problemas com outros pacotes) quando não há um bom motivo por trás dessa escolha de versão. -- For most cases where you must expose functions from dependencies to the user, you should import and re-export those individual functions rather than listing them in the `Depends` fields. For instance, if functions in your package produce `raster` objects, you might re-export only printing and plotting functions from the **raster** package. +- Na maioria dos casos em que é necessário expor as funções das dependências, você deve importar e reexportar essas funções individuais em vez de listá-las no campo `Depends`. Por exemplo, se as funções do seu pacote produzem objetos do tipo `raster`, você pode reexportar do pacote **raster** apenas as funções de impressão e plotagem. -- If your package uses a *system* dependency, you should +- Se seu pacote usar uma dependência de *sistema*, você deve - - Indicate it in DESCRIPTION; + - Indicá-la no DESCRIPTION; - - Check that it is listed by [`sysreqsdb`](https://github.com/r-hub/sysreqsdb#sysreqs) to allow automatic tools to install it, and [submit a contribution](https://github.com/r-hub/sysreqsdb#contributing) if not; + - Verifique se ele está listado por [`sysreqsdb`](https://github.com/r-hub/sysreqsdb#sysreqs) para permitir que ferramentas automáticas o instalem, ou [envie uma contribuição](https://github.com/r-hub/sysreqsdb#contributing) caso contrário; - - Check for it in a `configure` script ([example](https://github.com/ropensci/magick/blob/c116b2b8505f491db72a139b61cd543b7a2ce873/DESCRIPTION#L19)) and give a helpful error message if it cannot be found ([example](https://github.com/cran/webp/blob/master/configure)). - `configure` scripts can be challenging as they often require hacky solutions - to make diverse system dependencies work across systems. Use examples ([more here](https://github.com/search?q=org%3Acran+anticonf&type=Code)) as a starting point but note that it is common to encounter bugs and edge cases and often violate CRAN policies. Do not hesitate to [ask for help on our forum](https://discuss.ropensci.org/). + - Verificar se está listado em um script `configure` ([exemplo](https://github.com/ropensci/magick/blob/c116b2b8505f491db72a139b61cd543b7a2ce873/DESCRIPTION#L19)) e que fornecerá uma mensagem de erro útil caso não seja encontrado ([exemplo](https://github.com/cran/webp/blob/master/configure)). + Os scripts `configure` podem ser desafiadores, pois geralmente exigem soluções improvisadas + para fazer com que as diversas dependências do sistema funcionem em todos os sistemas. Use exemplos ([mais aqui](https://github.com/search?q=org%3Acran+anticonf&type=Code)) como ponto de partida, mas observe que é comum encontrar bugs e casos extremos e, muitas vezes, violar as políticas do CRAN. Não hesite em [pedir ajuda em nosso fórum](https://discuss.ropensci.org/). -## Recommended scaffolding {#recommended-scaffolding} +## Estruturas recomendadas {#recommended-scaffolding} -- For HTTP requests we recommend using [httr2](https://httr2.r-lib.org), [httr](https://httr.r-lib.org), [curl](https://jeroen.r-universe.dev/curl#), or [crul](http://docs.ropensci.org/crul/) over [RCurl](https://cran.rstudio.com/web/packages/RCurl/). If you like low-level clients for HTTP, curl is best, whereas httr2, httr and crul are better for higher-level access. +- Para solicitações HTTP, recomendamos o uso dos pacotes [httr2](https://httr2.r-lib.org), [httr](https://httr.r-lib.org), [curl](https://jeroen.r-universe.dev/curl#) ou [crul](http://docs.ropensci.org/crul/) ao invés do [RCurl](https://cran.rstudio.com/web/packages/RCurl/). Se você gosta de clientes de baixo nível para HTTP, o curl é melhor, enquanto o httr2, o httr e o crul são melhores para acesso de alto nível. -- For parsing JSON, use [jsonlite](https://github.com/jeroen/jsonlite) instead of [rjson](https://cran.rstudio.com/web/packages/rjson/) or [RJSONIO](https://cran.rstudio.com/web/packages/RJSONIO/). +- Para converter JSON (*parsing*) , use [jsonlite](https://github.com/jeroen/jsonlite) em vez de [rjson](https://cran.rstudio.com/web/packages/rjson/) ou [RJSONIO](https://cran.rstudio.com/web/packages/RJSONIO/). -- For parsing, creating, and manipulating XML, we strongly recommend [xml2](https://cran.rstudio.com/web/packages/xml2/) for most cases. [You can refer to Daniel Nüst's notes about migration from XML to xml2](https://gist.github.com/nuest/3ed3b0057713eb4f4d75d11bb62f2d66). +- Para converter, criar e manipular XML, recomendamos enfaticamente o pacote [xml2](https://cran.rstudio.com/web/packages/xml2/) para a maioria dos casos. [Você pode consultar as observações de Daniel Nüst sobre a migração de XML para xml2 (em inglês)](https://gist.github.com/nuest/3ed3b0057713eb4f4d75d11bb62f2d66). -- For spatial data, the [sp](https://github.com/edzer/sp/) package should be considered deprecated in favor of [sf](https://r-spatial.github.io/sf/), and the packages [rgdal](https://cran.r-project.org/web/packages/rgdal/index.html), [maptools](https://cran.r-project.org/web/packages/maptools/index.html) and [rgeos](https://cran.r-project.org/web/packages/rgeos/index.html) were retired in 2023. We recommend use of the spatial suites developed by the [r-spatial](https://github.com/r-spatial) and [rspatial](https://github.com/rspatial) communities. See [this GitHub issue](https://github.com/ropensci/software-review-meta/issues/47) for relevant discussions. +- Para dados espaciais, o pacote [sp](https://github.com/edzer/sp/) deve ser considerado obsoleto em favor do pacote [sf](https://r-spatial.github.io/sf/) e os pacotes [rgdal](https://cran.r-project.org/web/packages/rgdal/index.html), [maptools](https://cran.r-project.org/web/packages/maptools/index.html) e [rgeos](https://cran.r-project.org/web/packages/rgeos/index.html) foram aposentados em 2023. Recomendamos o uso do conjunto de ferramentas espaciais desenvolvidas pelas comunidades [r-spatial](https://github.com/r-spatial) e [rspatial](https://github.com/rspatial). Veja [esta edição do GitHub](https://github.com/ropensci/software-review-meta/issues/47) para discussões relevantes. -## Version Control {#version-control} +## Controle de versão {#version-control} -- 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. +- Os arquivos de origem do seu pacote devem estar sob controle de versão, mais especificamente rastreados com [Git](https://happygitwithr.com/). Você pode achar o [pacote gert](https://docs.ropensci.org/gert/) relevante, bem como algumas das funções do [pacote usethis relacionadas ao Git/GitHub](https://usethis.r-lib.org/reference/index.html#section-git-and-github); no entanto, você pode usar o git como quiser. -- 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. +- O nome da ramificação (*branch*) padrão não deve ser `master`, pois isso pode ser ofensivo para algumas pessoas. Consulte a seção [do projeto Git e da Software Freedom Conservancy](https://sfconservancy.org/news/2020/jun/23/gitbranchname/) para obter mais contexto. É uma prática geral nomear uma ramificação padrão `main`, embora outros nomes também possam ser usados. Consulte a postagem do blog do tidyverse ["Renomeando a ramificação padrão"](https://www.tidyverse.org/blog/2021/10/renaming-default-branch/) para saber mais sobre como usar essa funcionalidade para ajudar a renomear as ramificações padrão. -- 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. +- Certifique-se de listar arquivos desnecessários, como `.DS_Store`, no arquivo .gitignore. Você pode achar a função [`usethis::git_vaccinate()`](https://usethis.r-lib.org/reference/git_vaccinate.html) e o [pacote gitignore](https://docs.ropensci.org/gitignore/) relevantes. -- A later section of this book contains some [git workflow tips](#gitflow). +- Uma seção posterior deste livro contém algumas [dicas de fluxo de trabalho com git](#gitflow). -## Miscellaneous CRAN gotchas {#crangotchas} +## Problemas diversos do CRAN {#crangotchas} -This is a collection of CRAN gotchas that are worth avoiding at the outset. +Esta é uma coleção de problemas do CRAN que vale a pena evitar desde o início. -- Make sure your package title is in Title Case. -- 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. ``. -- 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. +- Certifique-se de que as palavras do título do seu pacote comecem com letra maiúscula (o que em inglês é chamado de *[Title Case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case)*. +- Não coloque um ponto final no final do título. +- Não coloque "no R" ou "com R" em seu título, pois isso é óbvio nos pacotes hospedados no CRAN. Se, mesmo assim, quiser que essas informações sejam exibidas em seu site, verifique a [documentação do `pkgdown`](https://pkgdown.r-lib.org/reference/build_home.html#yaml-config-home) para saber como substituir isso. +- Evite iniciar a descrição com o nome do pacote ou "Este pacote ...". +- Certifique-se de incluir links para sites se você envolver uma API da Web, extrair dados de um site etc. na seção `Description` do seu arquivo DESCRIPTION. Os URLs devem ser colocados entre colchetes angulares (`<>`), por exemplo ``. +- Em ambos os `Title` e `Description`, os nomes de pacotes ou outros softwares externos devem ser colocados entre aspas simples (por exemplo, *Integração do 'Rcpp' para a biblioteca de álgebra linear com modelo 'Armadillo'*). +- Evite testes e exemplos que sejam demorados. Considere usar `testthat::skip_on_cran` nos testes para pular coisas que demoram muito, mas ainda assim testá-las localmente e em [integração contínua](#ci). +- Inclua arquivos de nível superior, como `paper.md` e arquivos de configuração de integração contínua, no arquivo `.Rbuildignore`. -For further gotchas, refer to the collaborative list maintained by ThinkR, ["Prepare for CRAN"](https://github.com/ThinkR-open/prepare-for-cran). +Para obter mais dicas, consulte a lista colaborativa mantida pelo ThinkR, ["Prepare-se para o CRAN"](https://github.com/ThinkR-open/prepare-for-cran). -### CRAN checks {#cranchecks} +### Verificações do CRAN {#cranchecks} -Once your package is on CRAN, it will be [regularly checked on different platforms](https://blog.r-hub.io/2019/04/25/r-devel-linux-x86-64-debian-clang/#cran-checks-101). Failures of such checks, when not false positives, can lead to the CRAN team's reaching out. You can monitor the state of the CRAN checks via +Quando seu pacote estiver no CRAN, ele será [checado regularmente em diferentes plataformas](https://blog.r-hub.io/2019/04/25/r-devel-linux-x86-64-debian-clang/#cran-checks-101). As falhas nessas verificações, quando não são falsos positivos, podem levar a equipe do CRAN a entrar em contato com você. Você pode monitorar o estado das verificações do CRAN por meio -- the [`foghorn` package](https://fmichonneau.github.io/foghorn/). +- do [`foghorn` pacote](https://fmichonneau.github.io/foghorn/). -- the [CRAN checks badges](https://github.com/r-hub/cchecksbadges). +- das [etiquetas de checagem do CRAN (*"CRAN checks Badges"*)](https://github.com/r-hub/cchecksbadges). -## Bioconductor gotchas {#bioconductor-gotchas} +## Problemas do Bioconductor {#bioconductor-gotchas} -If you intend your package to be submitted to, or if your package is on, Bioconductor, refer to [Bioconductor packaging guidelines](https://www.bioconductor.org/developers/package-guidelines/) and the [updated developer book](https://contributions.bioconductor.org/). +Se você pretende que seu pacote seja enviado para o Bioconductor ou se o pacote estiver no Bioconductor, consulte as [Diretrizes de empacotamento do Bioconductor](https://www.bioconductor.org/developers/package-guidelines/) e o [livro de desenvolvimento atualizado](https://contributions.bioconductor.org/). -## Further guidance {#further-guidance} +## Orientações adicionais {#further-guidance} -- If you are submitting a package to rOpenSci via the [software-review repo](https://github.com/ropensci/software-review), you can direct further questions to the rOpenSci team in the issue tracker, or in our [discussion forum](https://discuss.ropensci.org/). +- Se você estiver enviando um pacote para a rOpenSci por meio do [repositório de revisão de software](https://github.com/ropensci/software-review), poderá encaminhar outras perguntas à equipe da rOpenSci usando as *issues* ou em nosso [fórum de discussão](https://discuss.ropensci.org/). -- Read the [authors guide](#authors-guide). +- Leia o [guia de autoria](#authors-guide). -- Read, incorporate, and act on advice from the [*Collaboration Guide* chapter](#collaboration). +- Leia, incorpore e aja de acordo com os conselhos do [capítulo *Guia de Colaboração*](#collaboration). -### Learning about package development {#learning-about-package-development} +### Aprendendo sobre o desenvolvimento de pacotes {#learning-about-package-development} -#### Books {#books} +#### Livros {#books} -- [Hadley Wickham and Jenny Bryan's *R packages* book](https://r-pkgs.org/) is an excellent, readable resource on package development which is available for [free online](https://r-pkgs.org/) (and can be bought in [print](https://www.oreilly.com/library/view/r-packages/9781491910580/)). +- O livro [*R packages* (Pacotes em R) escrito por Hadley Wickham e Jenny Bryan](https://r-pkgs.org/) é um recurso excelente e de fácil leitura sobre o desenvolvimento de pacotes, está disponível [gratuitamente on-line](https://r-pkgs.org/) (e pode ser comprado [impresso](https://www.oreilly.com/library/view/r-packages/9781491910580/)). -- [Writing R Extensions](https://cran.r-project.org/doc/manuals/r-release/R-exts.html) is the canonical, usually most up-to-date, reference for creating R packages. +- [*Writing R Extensions* (Escrevendo extensões do R)](https://cran.r-project.org/doc/manuals/r-release/R-exts.html) (em inglês) é a referência canônica, geralmente a mais atualizada, para a criação de pacotes em R. -- [*Mastering Software Development in R* by Roger D. Peng, Sean Kross, and Brooke Anderson](https://bookdown.org/rdpeng/RProgDA/). +- O livro [*Mastering Software Development in R* (Dominando o desenvolvimento de software em R) por Roger D. Peng, Sean Kross e Brooke Anderson](https://bookdown.org/rdpeng/RProgDA/). -- [*Advanced R* by Hadley Wickham](https://adv-r.hadley.nz/) +- [*Advanced R* (R avançado) por Hadley Wickham](https://adv-r.hadley.nz/). -- [*Tidyverse style guide*](https://style.tidyverse.org/) +- [*Tidyverse style guide* (Guia de estilo do Tidyverse)](https://style.tidyverse.org/). -- [*Tidyverse design guide*](https://design.tidyverse.org/) (WIP) and the accompanying [newsletter](http://tidydesign.substack.com/). +- [*Tidyverse design guide* (Guia de design do Tidyverse)](https://design.tidyverse.org/) (em elaboração) e o [boletim de notícias (*newsletter*)](http://tidydesign.substack.com/) que o acompanha. -#### Tutorials {#tutorials} +#### Tutoriais {#tutorials} -- [Your first R package in 1 hour](https://www.pipinghotdata.com/posts/2020-10-25-your-first-r-package-in-1-hour/) by Shannon Pileggi. +- [*Your first R package in 1 hour* (Seu primeiro pacote R em 1 hora)](https://www.pipinghotdata.com/posts/2020-10-25-your-first-r-package-in-1-hour/) por Shannon Pileggi. -- [this workflow description by Emil Hvitfeldt](https://www.emilhvitfeldt.com/post/2018-09-02-usethis-workflow-for-package-development/). +- [essa descrição de fluxo de trabalho por Emil Hvitfeldt](https://www.emilhvitfeldt.com/post/2018-09-02-usethis-workflow-for-package-development/). -- [This pictorial by Matthew J Denny](https://www.mjdenny.com/R_Package_Pictorial.html). +- [Esta ilustração de Matthew J Denny](https://www.mjdenny.com/R_Package_Pictorial.html). #### Blogs {#blogs} -- [R-hub blog](https://blog.r-hub.io/post). +- [Blog do R-hub](https://blog.r-hub.io/post). -- Some posts of the [rOpenSci blog](https://ropensci.org/archive/) e.g. ["How to precompute package vignettes or pkgdown articles"](https://ropensci.org/blog/2019/12/08/precompute-vignettes/). +- Algumas postagens do [blog da rOpenSci](https://ropensci.org/archive/), por exemplo [*How to precompute package vignettes or pkgdown articles* ("Como pré-computar vinhetas de pacotes ou artigos pkgdown")](https://ropensci.org/blog/2019/12/08/precompute-vignettes/). -- Package Development Corner section of [rOpenSci newsletter](https://ropensci.org/news/). +- Seção *Package Development Corner* ("Espaço de desenvolvimento de pacotes") do [boletim informativo da rOpenSci](https://ropensci.org/news/). -- Some posts of the [tidyverse blog](https://www.tidyverse.org) e.g. ["Upgrading to testthat edition 3"](https://www.tidyverse.org/blog/2022/02/upkeep-testthat-3/). +- Algumas postagens do [blog do tidyverse](https://www.tidyverse.org), por exemplo [*Upgrading to testthat edition 3* ("Atualizando para o testthat edition 3")](https://www.tidyverse.org/blog/2022/02/upkeep-testthat-3/). #### MOOCs {#moo-cs} -There is a [Coursera specialization corresponding to the book by Roger Peng, Sean Kross and Brooke Anderson](https://fr.coursera.org/specializations/r), with a course specifically about R packages. +Existe um [especialização do Coursera correspondente ao livro escrito por Roger Peng, Sean Kross e Brooke Anderson](https://fr.coursera.org/specializations/r), com um curso específico sobre pacotes R.