rOpenSci | O pkgcheck agora está disponível como uma ação do GitHub (GitHub Action)!

O pkgcheck agora está disponível como uma ação do GitHub (GitHub Action)!

🔗 O que é o pkgcheck?

O pacote pkgcheck foi desenvolvido pela rOpenSci para automatizar o processo de checagem de todos os pacotes submetidos. O ropensci-review-bot executa automaticamente o pkgcheck em todas as submissões, e a checagem também podem ser chamadas a qualquer momento pelos editores usando o comando:

@ropensci-review-bot check package

O bot retornará uma lista de verificações que, idealmente, deve ser semelhante a esta:

Resultados do pkgcheck para envio recente

Para estar pronto para a revisão por pares, o pkgcheck deve retornar uma série de ✔, indicando verificações bem-sucedidas, e não deve haver nenhum símbolo ✘, que indica verificações com falha. Recomenda-se que qualquer pessoa que esteja preparando um pacote para enviar “use o pkgcheck” para confirmar que um pacote está de fato pronto para ser enviado. Até agora, isso só era possível instalando o pacote localmente e executando o comando pkgcheck(). As verificações locais têm duas desvantagens importantes:

  1. Os resultados podem ser reprodutíveis apenas em um sistema local, em vez de serem reprodutíveis em geral; e
  2. As verificações executadas pelo pkgcheck incluem todas as verificações executadas pelo pacote rcmdcheck, que pode levar algum tempo para ser executado.

Assim como a ação do GitHub rcmdcheck, que pode ser facilmente instalada com uma das use_github_action_check_... funções do pacote usethis, o pkgcheck agora também tem uma ação do GitHub que supera essas duas desvantagens ao ser executado remotamente (no GitHub) e gerar resultados reprodutíveis.

🔗 A ação do GitHub pkgcheck-action

Esta postagem é o anúncio de lançamento “oficial” do pkgcheck-action, uma ação do GitHub que permite que as verificações sejam executadas toda vez que o código é enviado para o GitHub. A ação foi desenvolvida por um de nós (Jacob) e pode ser encontrada no GitHub em ropensci-review-tools/pkgcheck-action. A maneira mais fácil de usar essa ação em seu próprio repositório é instalar o pacote pkgcheck e executar a função use_github_action_pkgcheck(). Isso colocará um novo arquivo no diretório .github/workflows do seu pacote chamado “pkgcheck.yaml”, um exemplo do qual é mostrado no README principal do repositório pkgcheck-action. A ação consiste em um único trabalho expresso nas linhas finais:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: ropensci-review-tools/pkgcheck-action@main

Há vários parâmetros também descritos no arquivo README principal, que podem ser passados como parâmetros para a função use_github_action_pkgcheck() ou adicionada ao arquivo de fluxo de trabalho YAML, conforme também descrito no README. Depois que a ação tiver sido criada em seu repositório, ela poderá ser ativada adicionando o arquivo em um commit do git e subindo para o GitHub.

🔗 Publicando resultados do pkgcheck em uma Issue do GitHub

Além de o fluxo de trabalho imprimir os detalhes completos retornados pela função principal do pkgcheck, a saída do pkgcheck também pode ser postada em uma Issue do GitHub, onde aparecerá exatamente como o exemplo mostrado acima. Assim que o fluxo de trabalho for concluído, você receberá uma notificação e poderá visualizar os resultados da verificação (com um summary-only que determina se apenas um resumo dos resultados, como o mostrado acima, será publicado na Issue ou se serão publicados os resultados completos, que incluem o resumo seguido de muito mais detalhes). O fluxo de trabalho só será bem-sucedido quando todas as verificações do pkgcheck forem aprovadas.

🔗 Usando o pkgcheck-action para preparar o envio

Essa ação facilita muito a preparação de pacotes para envio à revisão por pares com o rOpenSci, confirmando automaticamente se um pacote atende aos requisitos gerais para envios à rOpenSci. Você pode usar o pkgcheck-action para confirmar que um pacote está pronto para ser enviado, seguindo estas três etapas simples:

  1. Insira a ação em seu repositório com pkgcheck::use_github_action_pkgcheck().
  2. Adicione o arquivo criado em um commit do git, e faça push para o GitHub para ativá-lo.
  3. Examine os resultados na Issue criada automaticamente no seu repositório do GitHub, modifique o código no repositório para resolver qualquer falha nas verificações, e repita esse processo.
  4. Quando a ação for aprovada, você verá “✔ Este pacote pode ser enviado”.

Você também pode colocar um selo pkgcheck em seu README inserindo uma versão modificada dessas linhas:

[![pkgcheck](https://github.com/<org>/<repo>/workflows/pkgcheck/badge.svg)](https://github.com/<org>/<repo>/actions?query=workflow%3Apkgcheck)

Quando seu pacote passar em todos os testes, o selo ficará verde e terá a seguinte aparência:

pkgcheckpkgcheckpassingpassing

Assim, você saberá que seu pacote está pronto para ser enviado!

E, por fim, sinta-se à vontade para fazer perguntas sobre o uso do pkgcheck-action ou relatar quaisquer erros em https://github.com/ropensci-review-tools/pkgcheck-action/issues.