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.
Juntamente com o [capítulo anterior] (#construção), ele forma as nossas diretrizes para a revisão de software por pares.
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.
A CI automatiza a execução de verificações gerais de pacotes, como R CMD check; Veja testando. É 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.
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.
Tanto o status do teste quanto a cobertura do código devem ser relatados por meio de distintivos no README do seu pacote.
Os pacotes R devem ter CI para todos os sistemas operacionais (Linux, Mac OSX, Windows) quando contiverem:
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.
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.
Ações do GitHub é 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 bem como suporte de primeira classe no pacote {usethis}. Todos os pacotes enviados à rOpenSci para revisão por pares são verificados por nosso sistema pkgcheck, descrito mais detalhadamente na seção Guia para Autores. Essas verificações também são fornecidas como uma ação do GitHub no repositório 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 para obter mais informações.
usethis oferece suporte a configuração de CI para outros sistemas embora essas funções estejam levemente obsoletas. A rOpenSci também oferece suporte ao pacote círculo, que auxilia na configuração de pipelines CircleCI, e ao pacote tic para criar pipelines de CI mais complicadas.
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.
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.
Você pode ajustar a implementação de testes com cada versão usando uma matriz de testes.
Se você desenvolver um pacote que dependa ou seja destinado ao Bioconductor, esta informação biocthis pode ser relevante.
Você pode usar estas dicas para minimizar o tempo de compilação na CI:
Você pode achar a postagem de Hugo Gruson útil Dependências do sistema em pacotes R e testes automáticos.
Recomendamos que você afaste-se de Travis.
Para a integração contínua no Windows, consulte R + AppVeyor. Configure-o usando usethis::use_appveyor().
Aqui estão algumas dicas para você minimizar o tempo de compilação do AppVeyor:
Instale os seus pacotes em algum tipo de cache. Exemplo de um arquivo de configuração. Ele já estará no arquivo de configuração se você configurar o AppVeyor CI usando usethis::use_appveyor().
Ativar compilações contínuas.
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).
Circle CI é usado, por exemplo, pelo pacote bomrang da rOpenSci como serviço de integração contínua.
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 ou Coveralls.
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 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.
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.
Para mais detalhes e instruções, consulte a seção README do pacote covr, bem como usethis::use_coverage() e usethis::use_github_action().
Se você executar a cobertura em vários serviços de CI os resultados serão fundidos.
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/, usando o API opencpu. Para obter mais detalhes sobre esse serviço, consulte a página de ajuda do OpenCPU que também indica onde você pode fazer perguntas.
Após a transferência para a organização “ropensci” no GitHub pertencente a rOpenSci, um site pkgdown será criado para o seu pacote:
Para cada novo commit no ramo padrão (verificado aproximadamente uma vez por hora).
Quando qualquer uma das dependências fortes no mesmo universo atualiza o número da versão.
Uma vez por mês.
Você pode encontrar o status dessas compilações em https://ropensci.r-universe.dev/ui#packages e na seção status do commit. A compilação do site usará o seu arquivo config do pkgdown, se você tiver um, exceto para o estilo que usará o pacote rotemplate. Se sua documentação incluir código que dependa, por exemplo, de credenciais, veja aqui como garantir que os documentos pkgdown sejam renderizados da melhor maneira possível.
examplesIf com a variável IN_PKGDOWN, por exemplo, #' @examplesIf identical(Sys.getenv(“IN_PKGDOWN”), “true”)
IN_PKGDOWN com a opção knitr eval, por exemploknitr::opts_chunk$set(
collapse = TRUE,
comment = “#>”,
eval = Sys.getenv(“IN_PKGDOWN”) == “true”
)Exemplos:
examplesIf:https://github.com/ropensci/gtexr/blob/592ac781672f07eb67e935d4155570c5960d1fdb/R/get_service_info.R#L14 (veja também a documentação da tag roxygen2: https://roxygen2.r-lib.org/articles/rd.html?q=examplesIf#examples)Por favor, informe bugs, faça perguntas e solicitações de recursos sobre as compilações centrais e sobre o modelo em https://github.com/ropensci-org/rotemplate/.