pkgcheck now available as a GitHub action!

What is pkgcheck?

The pkgcheck package has been developed by rOpenSci to automate the process of checking all packages on submission. The ropensci-review-bot automatically runs pkgcheck on all submissions, and checks can also be called at any time by editors using the command:

@ropensci-review-bot check package

The bot will return a list of checks which should ideally look like this:

To be ready for peer review, pkgcheck should return a series of ✔, indicating successful checks, and there shouldn’t be any ✘ symbols, which indicate failed checks. Anybody preparing a package to submit is recommended to “use pkgcheck” to confirm that a package is indeed ready to submit. Until now, this has only been possible through locally installing the package and running the pkgcheck() command. Local checks suffer two important disadvantages:

1. Results may only be reproducible on a local system, rather than be generally reproducible; and
2. The checks run by pkgcheck include all checks run by the rcmdcheck package which may take quite some time to run.

Just like the GitHub rcmdcheck action which can be easily installed with one of the use_github_action_check_... functions from the usethis package, pkgcheck now also has a GitHub action which overcomes both of these disadvantages through running remotely (on GitHub), and generating reproducible results.

The GitHub pkgcheck-action

This post is the “official” release announcement of pkgcheck-action, a GitHub action which enables checks to be run every time code is pushed to GitHub. The action was developed by one of us (Jacob), and can be found on GitHub at ropensci-review-tools/pkgcheck-action. The easiest way to use this action in your own repository is to install the pkgcheck package, and run the use_github_action_pkgcheck() function. That will place a new file in the .github/workflows directory of your package called “pkgcheck.yaml”, an example of which is shown on the main README of the pkgcheck-action repository. The action consists of the single job expressed in the final lines:

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

There are several parameters also described in that main README, which can either be passed as parameters to the use_github_action_pkgcheck() function, or added to the YAML workflow file as also described in the README. Once the action has been created in your repository, it can be activated by adding it in a git commit and pushing to GitHub.

Posting pkgcheck results to a GitHub issue

In addition to the workflow printing the full details returned by the main pkgcheck function, the output of pkgcheck can also be posted to a GitHub issue, where it will appear precisely like the example shown above. Once the workflow has finished, you’ll receive a notification, and be able to view the check results (with a summary-only parameter determining whether only a summary of results like shown above will be posted to the issue, or whether full results will be posted which include the summary followed by quite a bit more detail). The workflow will only succeed when all pkgcheck checks have been passed.

Using pkgcheck-action to prepare for submission

This action makes preparing packages for submission to peer review with rOpenSci much easier, by automatically confirming whether a package the general requirements for rOpenSci submissions. You can use pkgcheck-action to confirm that a package is ready for submission by following these three easy steps:

1. Insert the action into your repository with pkgcheck::use_github_action_pkgcheck().
2. Add and commit the action script to your git index, and push to GitHub to activate it.
3. Examine results in the automatically-created issue of your GitHub repository, modify the repository to address any failing checks, and iterate.
4. Once the action passes, you’ll see “✔ This package may be submitted.”

You can also put a pkgcheck} badge in your README by inserting a modified version of these lines:

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

Once your package passes all tests, the badge will turn green and look like this: