|
| 1 | +--- |
| 2 | +aliases: |
| 3 | + - ci.html |
| 4 | +--- |
| 5 | + |
| 6 | +# Práticas Recomendadas de Integração Contínua {#ci} |
| 7 | + |
| 8 | +```{block, type="summaryblock"} |
| 9 | +Este capítulo resume as nossas diretrizes sobre a integração contínua, depois de explicar o que o termo integração contínua significa. |
| 10 | +
|
| 11 | +Juntamente com o [capítulo anterior] (#construção), ele forma as nossas diretrizes para a revisão de software por pares. |
| 12 | +``` |
| 13 | + |
| 14 | +## O que é a integração contínua? {#what-is-continuous-integration-ci} |
| 15 | + |
| 16 | +A integração contínua (do inglês, CI) se refere a execução de testes automáticos em software. No caso da rOpenSci, a CI significa praticamente que um conjunto de testes será executado automaticamente por meio do GitHub, sempre que você fizer um _commit_ ou um _pull request_ ao GitHub. |
| 17 | + |
| 18 | +A CI automatiza a execução de verificações gerais de pacotes, como `R CMD check`; Veja [testando](/building.html#testing). É possível configurar a CI antes que os testes sejam escritos, assim a CI executará os testes quando você os enviar para o repositório por meio de _commits_. |
| 19 | + |
| 20 | +## Por que usar a integração contínua (CI)? {#why-use-continuous-integration-ci} |
| 21 | + |
| 22 | +Todos os pacotes da rOpenSci devem usar uma forma de integração contínua. Isso garante que todos os commits, pull requests e novas ramificações sejam executados pelo `R CMD check`. Os resultados de todos os testes são exibidos na página de _pull requests_ no GitHub, fornecendo outra camada de informações sobre os problemas e a proteção contra a quebra do seu pacote antes de fazer a fusão das alterações. A integração contínua dos pacotes da rOpenSci também deve ser vinculada a um serviço de cobertura de código, indicando quantas linhas são cobertas por testes de unidade. |
| 23 | + |
| 24 | +Tanto o status do teste quanto a cobertura do código devem ser relatados por meio de distintivos no README do seu pacote. |
| 25 | + |
| 26 | +Os pacotes R devem ter CI para todos os sistemas operacionais (Linux, Mac OSX, Windows) quando contiverem: |
| 27 | + |
| 28 | +- Código compilado |
| 29 | +- Dependências em Java |
| 30 | +- Dependências em outras linguagens |
| 31 | +- Pacotes com chamadas de sistema |
| 32 | +- Processamento de texto, como obter os nomes das pessoas (para encontrar problemas de codificação) |
| 33 | +- Qualquer coisa com sistema de arquivos/chamadas de diretório |
| 34 | + |
| 35 | +Em caso de dúvida sobre a aplicabilidade desses critérios ao seu pacote, é melhor adicionar CI para todos os sistemas operacionais. A maioria das configurações de padrões de serviços de CI para pacotes R permite que isso seja feito sem muito trabalho. |
| 36 | + |
| 37 | +## Qual(is) serviço(s) de integração contínua? {#whichci} |
| 38 | + |
| 39 | +Há vários serviços de integração contínua, incluindo serviços autônomos (CircleCI, AppVeyor) e outros integrados à hospedagem de código ou a serviços relacionados (GitHub Actions, GitLab, AWS Code Pipeline). Diferentes serviços oferecem suporte a diferentes configurações de sistema operacional. |
| 40 | + |
| 41 | +[Ações do GitHub](https://github.com/features/actions) é uma opção conveniente para muitas pessoas desenvolvedoras de R que já usam o GitHub, pois está integrada à plataforma e oferece suporte a todos os sistemas operacionais necessários. Existem [ações compatíveis com o ecossistema R](https://github.com/r-lib/actions/) bem como suporte de primeira classe no pacote [{usethis}](https://usethis.r-lib.org/reference/github_actions.html). Todos os pacotes enviados à rOpenSci para revisão por pares são verificados por nosso [sistema `pkgcheck`](https://docs.ropensci.org/pkgcheck), descrito mais detalhadamente na seção [Guia para Autores](#authors-guide). Essas verificações também são fornecidas como uma ação do GitHub no repositório [`ropensci-review-tools/pkgcheck-action`](https://github.com/ropensci-review-tools/pkgcheck-action). Os autores e as autoras de pacotes são incentivados a usar essa ação para confirmar, antes do envio, que um pacote passa em todas as nossas verificações. Consulte [nossa publicação no blog](https://ropensci.org/blog/2022/02/01/pkgcheck-action/) para obter mais informações. |
| 42 | + |
| 43 | +[usethis oferece suporte a configuração de CI para outros sistemas](https://usethis.r-lib.org/reference/ci.html) embora essas funções estejam levemente obsoletas. A rOpenSci também oferece suporte ao pacote [círculo](https://docs.ropensci.org/circle/), que auxilia na configuração de pipelines CircleCI, e ao pacote [tic](https://docs.ropensci.org/tic/) para criar pipelines de CI mais complicadas. |
| 44 | + |
| 45 | +#### Testes usando diferentes versões do R {#testing-using-different-versions-of-r} |
| 46 | + |
| 47 | +Exigimos que os pacotes da rOpenSci sejam testados nas versões mais recentes, porém também nas versões anteriores e de desenvolvimento do R, para garantir a compatibilidade retroativa e progressiva com o R básico. |
| 48 | + |
| 49 | +Detalhes sobre como executar testes/verificações usando diferentes versões do R localmente podem ser encontrados na vinheta do R-hub ao executar [Verificações locais do Linux com Docker](https://r-hub.github.io/rhub/articles/local-debugging.html). |
| 50 | + |
| 51 | +Você pode ajustar a implementação de testes com cada versão usando uma matriz de testes. |
| 52 | + |
| 53 | +Se você desenvolver um pacote que dependa ou seja destinado ao Bioconductor, esta informação [biocthis](https://lcolladotor.github.io/biocthis/index.html) pode ser relevante. |
| 54 | + |
| 55 | +#### Minimizando o tempo de compilação na CI {#minimizing-build-times-on-ci} |
| 56 | + |
| 57 | +Você pode usar estas dicas para minimizar o tempo de compilação na CI: |
| 58 | + |
| 59 | +- Instalar os pacotes em um cache que possa ser reutilizado no processo de CI quando necessário (_cache installation of packages_). O padrão faz isso [r-lib/actions workflows](https://github.com/r-lib/actions). |
| 60 | + |
| 61 | +#### Dependências do sistema {#sysdeps-ci} |
| 62 | + |
| 63 | +Você pode achar a postagem de Hugo Gruson útil [Dependências do sistema em pacotes R e testes automáticos](https://blog.r-hub.io/2023/09/26/system-dependency/). |
| 64 | + |
| 65 | +### Travis CI (Linux e Mac OSX) {#travis-ci-linux-and-mac-osx} |
| 66 | + |
| 67 | +Recomendamos que você [afaste-se de Travis](https://ropensci.org/technotes/2020/11/19/moving-away-travis/). |
| 68 | + |
| 69 | +### AppVeyor CI (Windows) {#app-veyor-ci-windows} |
| 70 | + |
| 71 | +Para a integração contínua no Windows, consulte [R + AppVeyor](https://github.com/krlmlr/r-appveyor). Configure-o usando `usethis::use_appveyor()`. |
| 72 | + |
| 73 | +Aqui estão algumas dicas para você minimizar o tempo de compilação do AppVeyor: |
| 74 | + |
| 75 | +- Instale os seus pacotes em algum tipo de cache. [Exemplo de um arquivo de configuração](https://github.com/r-lib/usethis/blob/2c52c06373849d52f78a26c5a0e080f518a2f825/inst/templates/appveyor.yml#L13). Ele já estará no arquivo de configuração se você configurar o AppVeyor CI usando `usethis::use_appveyor()`. |
| 76 | + |
| 77 | +- Ativar [compilações contínuas](https://www.appveyor.com/docs/build-configuration/#rolling-builds). |
| 78 | + |
| 79 | +Não transferimos mais projetos AppVeyor para a conta "ropensci" no AppVeyor, portanto, após a transferência do seu repositório para a conta "ropensci" no GitHub, o distintivo será `[](https://ci.appveyor.com/project/individualaccount/pkgname)`. |
| 80 | + |
| 81 | +### Circle CI (Linux e Mac OSX) {#circle-ci-linux-and-mac-osx} |
| 82 | + |
| 83 | +[Circle CI](https://circleci.com/) é usado, por exemplo, pelo pacote [`bomrang`](https://github.com/ropensci/bomrang) da rOpenSci como serviço de integração contínua. |
| 84 | + |
| 85 | +## Cobertura de testes {#coverage} |
| 86 | + |
| 87 | +A integração contínua também deve incluir relatórios de cobertura de teste por meio de um serviço de teste, como o [Codecov](https://codecov.io/) ou [Coveralls](https://coveralls.io/). |
| 88 | + |
| 89 | +Recomendamos que você use Codecov. Para ativar Codecov em seu repositório, execute `usethis::use_github_action("test-coverage")` para criar um arquivo `.github/workflows/test-coverage.yaml`. Você também precisa dar ao Codecov acesso ao seu repositório do GitHub, consulte [Guia de início rápido do Codecov](https://docs.codecov.com/docs/quick-start) para saber como configurar o acesso. Em seguida, adicione um distintivo de status do Codecov à parte superior do seu README.md, consulte [Distintivos de status do Codecov](https://docs.codecov.com/docs/status-badges). |
| 90 | + |
| 91 | +Se o seu repositório for transferido para a organização GitHub ropensci, o acesso ao Codecov deverá ser transferido automaticamente. Você precisará atualizar o URL do distintivo para apontar ao repositório hospedado na rOpenSci. |
| 92 | + |
| 93 | +Para mais detalhes e instruções, consulte a seção [README do pacote **covr**](https://github.com/r-lib/covr), bem como [`usethis::use_coverage()`](https://usethis.r-lib.org/reference/use_coverage.html) e [`usethis::use_github_action()`](https://usethis.r-lib.org/reference/github_actions.html). |
| 94 | + |
| 95 | +Se você executar a cobertura em vários serviços de CI [os resultados serão fundidos](https://docs.codecov.io/docs/merging-reports). |
| 96 | + |
| 97 | +## Ainda mais CI: OpenCPU {#even-more-ci-open-cpu} |
| 98 | + |
| 99 | +Após a transferência para a organização "ropensci" no GitHub pertencente a rOpenSci, cada envio para o repositório será contruido no OpenCPU e a pessoa que fizer o _commit_ receberá um e-mail de notificação. Esse é um serviço de CI adicional para autores e autoras de pacotes que permite que as funções do R em pacotes sejam chamadas remotamente via [https://ropensci.ocpu.io/](https://ropensci.ocpu.io/), usando o [API opencpu](https://www.opencpu.org/api.html#api-json). Para obter mais detalhes sobre esse serviço, consulte a [página de ajuda do OpenCPU](https://www.opencpu.org/help.html) que também indica onde você pode fazer perguntas. |
| 100 | + |
| 101 | +## Ainda mais CI: documentos da rOpenSci {#rodocsci} |
| 102 | + |
| 103 | +Após a transferência para a organização "ropensci" no GitHub pertencente a rOpenSci, um site pkgdown será criado para o seu pacote após cada envio para o repositório no GitHub. Você pode encontrar o status dessas compilações em `https://ropensci.r-universe.dev/ui#packages` e na seção [status do commit](https://ropensci.org/blog/2021/09/03/runiverse-docs/#how-it-works). A compilação do site usará seu arquivo config do pkgdown, se você tiver um, exceto para o estilo que usará o pacote [ `rotemplate`](https://github.com/ropensci-org/rotemplate/). |
| 104 | + |
| 105 | +Por favor, informe bugs, perguntas e solicitações de recursos sobre as compilações centrais e sobre o modelo em [https://github.com/ropensci-org/rotemplate/](https://github.com/ropensci-org/rotemplate/). |
| 106 | + |
| 107 | + |
0 commit comments