Check whether a package is ready for submission to rOpenSci’s peer review system. The
primary function, pkgcheck(),
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 may also be installed from locations other than GitHub, with any of the following options:
remotes::install_git ("https://codeberg.org/ropensci-review-tools/pkgcheck")
remotes::install_git ("https://codefloe.com/ropensci-review-tools/pkgcheck")The package can then be 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 '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].
## ✖ Repository has no website
## ✖ 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.
## ℹ Some goodpractice linters failed.
##
## ℹ Current status:
## ✖ Frustration is a natural part of programming :)
##
## ℹ 'pkgcheck' version: 0.1.3.12
## 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).
To avoid potential namespace conflicts with existing CRAN packages,
pkgcheck includes the helper function fn_names_on_cran.
You can use this interactively during development to check if your
proposed function names are already in use. This is a useful step to
perform before committing new functions and running a full
pkgcheck:
fn_names_on_cran (c ("min", "max"))## package version fn_name
## 1 matlab2r 1.5.0 max
## 2 matlab2r 1.5.0 min
## 3 rapportools 1.2 max
## 4 rapportools 1.2 min
## 5 mosaic 1.9.2 max
## 6 mosaic 1.9.2 minpkgcheck GitHub
actionThe 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().)
pkgcheck in the backgroundRunning the pkgcheck
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,
pkgcheck 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 R 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 allcontributors specification.
Contributions of any kind are welcome!
mpadge |
maelle |
assignUser |
ateucher |
markean |
katrinabrock |
n-kall |
AntoineSoetewey |
JesseAlderliesten |
kellijohnson-NOAA |
e-kotov |
annakrystalli |
etiennebacher |
karthik |
piyalkarum |
noamross |
christophsax |
steffilazerte |
phuongquan |
s3alfisc |
Bisaloo |
Robinlovelace |
schneiderpy |
eliocamp |
osorensen |
KlausVigo |
sjentsch |
willgearty |
simpar1471 |
dgkf |
jhollist |
cboettig |
PietrH |
santikka |
bnicenboim |
laijasmine |
b-rodrigues |
philipp-baumann |
Aariq |
TimTaylor |