Check whether a package is ready for submission to
rOpenSci’s peer review system. The primary
function collates the output of
goodpractice,
including R CMD check results, a number of statistics via the
pkgstats package,
and checks for package structure expected for rOpenSci submissions. The
output of this function immediately indicates whether or not a package
is “Ready to Submit”.
The easiest way to install this package is via the associated
r-universe.
As shown there, simply enable the universe with
options (repos = c (
ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev",
CRAN = "https://cloud.r-project.org"
))And then install the usual way with,
install.packages ("pkgcheck")Alternatively, the package can be installed by first installing either the remotes or pak packages and running one of the following lines:
remotes::install_github ("ropensci-review-tools/pkgcheck")
pak::pkg_install ("ropensci-review-tools/pkgcheck")The package can then loaded for use with
library (pkgcheck)The pkgstats
package also
requires the system libraries ctags and GNU
global to be installed.
Procedures to install these libraries on various operating systems are
described in a pkgstats
vignette.
This package also uses the GitHub GraphQL
API which requires a local GitHub
token to be stored with an unambiguous name including GITHUB, such as
GITHUB_TOKEN (recommended), or GITHUB_PAT (for Personal
Authorization Token). This can be obtained from GitHub (via your user
settings), and stored using
Sys.setenv ("GITHUB_TOKEN" = "<my_token>")This can also be set permanently by putting this line in your
~/.Renviron file (or creating this if it does not yet exist). Once
pkgstats has been successfully installed, the pkgcheck package can
then be loaded via a library call:
library (pkgcheck)The package primarily has one function, pkgcheck, which accepts the
single argument, path, specifying the local location of a git
repository to be analysed. The following code generates a reproducible
report by first downloading a local clone of a repository called
srr-demo, which contains the
skeleton of an srr (Software Review Roclets)
package, generated with
the srr_stats_pkg_skeleton()
function:
mydir <- file.path (tempdir (), "srr-demo")
gert::git_clone ("https://github.com/mpadge/srr-demo", path = mydir)
devtools::document (mydir, quiet = TRUE) # Generate documentation entries in "/man" directory
x <- pkgcheck (mydir)That object has default print and summary methods. The latter can be
used to simply check whether a package is ready for submission:
summary (x)
##
## ── demo 0.0.0.9000 ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
##
## ✔ Package name is available
## ✖ does not have a 'codemeta.json' file.
## ✖ does not have a 'contributing' file.
## ✖ The following function has no documented return value: [test_fn]
## ✔ uses 'roxygen2'.
## ✔ 'DESCRIPTION' has a URL field.
## ✖ 'DESCRIPTION' does not have a BugReports field.
## ✖ Package has no HTML vignettes
## ✖ These functions do not have examples: [test_fn].
## ✖ Package has no continuous integration checks.
## ✖ Package coverage failed
## ✖ Statistical standards should be documented in most package files, yet are mostly only documented in one file.
## ✔ R CMD check found no errors.
## ✔ R CMD check found no warnings.
##
## ℹ Current status:
## ✖ This package is not ready to be submitted.
## A package may only be submitted when the summary contains all ticks and
no cross symbols. (These symbols are colour-coded with green ticks and
red crosses when generated in a terminal; GitHub markdown only renders
them in black-and-white.) The object returned from the pkgcheck
function is a complex nested list with around a dozen primary
components. Full information can be obtained by simply calling the
default print method by typing the object name (x).
The pkgcheck package also has an associated GitHub action in the
pkgcheck-action
repository.
You can use this action to run pkgcheck every time you push commits to
GitHub, just like the rcmdcheck() checks which can be installed and
run via the usethis::use_github_action_check_standard()
function.
pkgcheck includes an analogous function,
use_github_action_pkgcheck(),
which will download the workflow file defining the action into your
local .github/workflows folder. See the pkgcheck-action
repository
for more details.
You can also add a pkgcheck badge, just like that rcmdcheck badge,
that will always reflect the current state of your repository’s
pkgcheck results. To add a badge, copy the following line to your
README file, filling in details of the GitHub organization and
repository name (<org> and <repo>, respectively):
[](https://github.com/<org>/<repo>/actions?query=workflow%3Apkgcheck)All current checks are listed in a separate vignette.
Calling summary() on the object returned by the pkgcheck()
function
will generate a checklist like that shown above. This checklist will
also be automatically generated when a package is first submitted to
rOpenSci, and is used by the editors to assess whether to process a
submission. Authors must ensure prior to submission that there are no
red crosses in the resultant list. (In the unlikely circumstances that a
package is unable to pass particular checks, explanations should be
given upon submission about why those checks fail, and why review may
proceed in spite of such failures.)
Full details of check results can be seen by print-ing the object
returned by the pkgcheck()
function
(or just by typing the name of this object in the console.)
The package includes an additional function,
checks_to_markdown(),
with a parameter, render, which can be set to TRUE to automatically
render a HTML-formatted representation of the check results, and open it
in a browser. The formatting differs only slightly from the terminal
output, mostly through the components of
goodpractice being divided
into distinct headings, with explicit statements in cases where
components pass all checks (the default screen output inherits directly
from that package, and only reports components which do not pass all
checks).
This
checks_to_markdown()
function returns the report in markdown format, suitable for pasting
directly into a GitHub issue, or other markdown-compatible place. (The
clipr package can be used to
copy this directly to your local clipboard with write_clip(md), where
md is the output of checks_to_markdown().)
Running the pgkcheck
function
can be time-consuming, primarily because the
goodpractice component runs
both a full R CMD check, and calculates code coverage of all tests. To
avoid re-generating these results each time, the package saves previous
reports to a local cache directory defined in
Sys.getenv("PKGCHECK_CACHE_DIR").
You may manually erase the contents of this pkgcheck subdirectory at
any time at no risk beyond additional time required to re-generate
contents. By default checks presume packages use git for version
control, with checks updated only when code is updated via git commit.
Checks for packages that do not use git are updated when any files are
modified.
The first time
pkgcheck()
is applied to a package, the checks will be stored in the cache
directory. Calling that function a second time will then load the cached
results, and so enable checks to be returned much faster. For code which
is frequently updated, such as for packages working on the final stages
prior to submission, it may still be necessary to repeatedly call
pkgcheck()
after each modification, a step which may still be inconveniently
time-consuming. To facilitate frequent re-checking, the package also has
a pkgcheck_bg()
function
which is effectively identical to the main pkgcheck()
function,
except it runs in the background, enabling you to continue coding while
checks are running.
The pkgcheck_bg()
function
returns a handle to the callr::r_bg()
process in which the
checks are running. Typing the name of the returned object will
immediately indicate whether the checks are still running, or whether
they have finished. That handle is itself an R6
object with a number of methods, notably
including
get_result()
which can be used to access the checks once the process has finished.
Alternatively, as soon as the background process, the normal
(foreground) pkgcheck()
function
may be called to quickly re-load the cached results.
The checklist package for
“checking packages and R code”.
Please note that this package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.
All contributions to this project are gratefully acknowledged using the
allcontributors
package following the
all-contributors specification.
Contributions of any kind are welcome!
mpadge |
maelle |
assignUser |
annakrystalli |
karthik |
piyalkarum |
noamross |
christophsax |
steffilazerte |
phuongquan |
s3alfisc |
Bisaloo |
Robinlovelace |
schneiderpy |
eliocamp |
osorensen |
KlausVigo |
sjentsch |
willgearty |
ddbortoli |
dgkf |
cboettig |
jhollist |
ropensci-review-bot |
santikka |
bnicenboim |
b-rodrigues |
philipp-baumann |