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”.
Installation
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 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
Setup
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:
Usage
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)
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.
## ✔ uses 'roxygen2'.
## ✔ 'DESCRIPTION' has a URL field.
## ✖ 'DESCRIPTION' does not have a BugReports field.
## ✖ Package has no HTML vignettes
## ✔ All functions have examples.
## ✖ Package has no continuous integration checks.
## ✖ Package coverage failed
## ✔ 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
GitHub action
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)
What is checked?
Summary of Check Results
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.)
The full list of checks which packages are expected to pass currently includes:
- Package must use
roxygen2
for documentation. - Package must have a
contributing.md
file. - Package must have a
CITATION
file in theinst
directory. - Package must have a
codemeta.json
file. - All exported functions must include examples in their documentation.
- Left-assign operators must be used consistently throughout all code (so either all
=
or all<-
, but not a mixture of both). - Package
DESCRIPTION
file must have a “URL” field. - Package
DESCRIPTION
file must have a “BugReports” field. - Package name must be available (or package must already be) on CRAN.
- Package must have continuous integration tests.
- Package must have test coverage of at least 75%.
- No function should have a cyclomatic complexity of 15 or greater.
-
R CMD check
(implemented via thercmdcheck
package) must generate no warnings or errors. - All statistical standards must be documented, as confirmed by the
srr::srr_pre_submit()
function.
Several of these are by default only shown when they fail; absence from a resultant checklist may be interpreted to indicate successful checks.
Detailed Check Results
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.) This object is itself a list including the following items:
names (x)
## [1] "pkg" "info" "checks" "meta" "goodpractice"
The first four of these contain information on the package. The remainder include:
-
summary
containing summary statistics on package structure (such as lines of code, and numbers of files and functions). -
git
containing information and statistics on thegit
repository associated with a package (if any), including date of first commit, total number of commits and of committers. -
srr
summarising information on statistical packages generated by thesrr
package, including a link to a locally-generated HTML report on standards compliance. -
file_list
as a list of binary flags denoting presence of absence of all files required for an R package to be submitted to rOpenSci -
fns_have_exs
with a list of any functions which do not have documented examples -
left_assigns
with a logical value indicating whether or not global assignment operators (<<-
) are used; and a tally of the two types of left-assignment operators (<-
and=
). One one of these should be non-zero, reflecting consistent usage of the same type. -
pkgstats
containing several statistics of package structure, along with associated percentiles assessed against the entire distribution of all current CRAN packages. -
network_file
with the path to a local HTML file containing a .visjs representation of the network of relationships between objects (such as functions) within a package, within and between each computer language used in the package. -
gp
containing the output of thegoodpractice
package, itself including results from:- the
rcmdcheck
package for runningR CMD check
- the
covr
package for assessing code coverage - the
cyclocomp
package for quantifying the cyclomatic complexity of package functions - the
desc
package for analysing the structure ofDESCRIPTION
files - the
lintr
package - additional checks applied by the
goodpractice
package
- the
Note that results from lintr
package are not reported in the check summary, and that lintr
results are reported only in the detailed results, and have no influence on whether a package passes the summary checks.
HTML-formatted check results
Printing pkgcheck
results to screen is nice, but sometimes it’s even better to have a nicely formatted full-screen representation of check results. 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()
.)
Caching and running pkgcheck
in the background
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, in a pkgcheck
subdirectory of the location determined by
rappdirs::user_cache_dir ()
As explained in the help file for that function, these locations are:
System | location |
---|---|
Mac OS X | ~/Library/Caches/pkgcheck |
Linux | ~/.cache/pkgcheck |
Win XP | C:\\Documents and Settings\\<username>\\Local Settings\\Application Data\\<AppAuthor>\\pkgcheck\\Cache |
Vista | C:\\Users\\<username>\\AppData\\Local\\<AppAuthor>\\pkgcheck\\Cache |
You may manually erase the contents of this pkgcheck
subdirectory at any time at no risk beyond additional time required to re-generate contents. This default location may also be over-ridden by setting an environmental variable named PKGCHECK_CACHE_DIR
. 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.
Prior Work
The checklist
package for “checking packages and R code”.
Code of Conduct
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.
Contributors
All contributions to this project are gratefully acknowledged using the allcontributors
package following the all-contributors specification. Contributions of any kind are welcome!
Issue Authors
piyalkarum |
christophsax |
steffilazerte |