TLDR; If you want to do the reverse dependency check on your package, you can
edit the Github Action
rev-check.yaml:
change the repository
from yihui/knitr
to your username/repo, and follow the
Github guide to create a pull request. The check results will be available in
Github Actions.
There are a lot of things to check before you submit an R package to CRAN, and the last thing is probably to make sure your new version will not break any existing packages on CRAN, otherwise you may hear Gandalf tell you that "You shall not pass."
The way to make sure your new version will not break packages that depend on your package is to run reverse dependency checks. The basic idea is the following:
-
Install the new version (development version) of your package, and run
R CMD check
on all packages that depend on yours. In theory, all these checks should pass. If that's the case, you are good to go. -
If any of your reverse dependency fails to pass the check, there are two possible reasons:
-
A certain change that you made in the new version broke it. For this case, you should either undo the change, or contact the maintainer of the reverse dependency and see if they'd like to change their package to accommodate your (breaking) changes.
-
The reverse dependency is currently also failing on CRAN. For this case, usually you are good to go. To verify it, we can run the check again with the current CRAN version of your package. If it also fails, perhaps it is not your fault.
-
This repo provides a service based on Github Actions to run reverse dependency
checks via xfun::rev_check(),
which is one implementation of the above idea.
Features include:
- The checks are run on macOS, and it will try to automatically install system dependencies for R packages via Homebrew (thanks to sysreqsdb).
- It uses the LaTeX distribution TinyTeX, which means missing LaTeX packages will be automatically installed, including those used in package vignettes.
Note that this service has two caveats:
- It will try its best to install as many packages required by the checks as possible, but it doesn't guarantee all can be installed.
- Currently it only installs CRAN packages but not packages from other repositories. This may change in the future.
As a result, even if your package passes the checks, it does not guarantee that all reverse dependencies would not be broken, because some of them may not have been checked. Even with a subset of reverse dependencies checked, this service may help you discover potential problems without you running all the checks locally.
The option xfun.rev_check.sample = 0
in .Rprofile
means that soft reverse
dependencies are not checked. Here "soft" means packages that list your package
in their Suggests
or Enhances
field in the DESCRIPTION
file. This number
indicates the number of soft reverse dependencies that you want to check (they
will be randomly sampled).
When the checks for any reverse dependencies fail, the Github action run will
have an artifact macOS-rev-check-results
for you to download (see this
example). It contains
the R CMD check
logs of failed packages as well as an HTML file
00check_diff.html
, which contains a summary of the failed checks, indicating
the errors caused by the new version of the package (compared to its CRAN
version).
After you fix the problems revealed by the initial check and push to the Github
repo of your package, you can add a recheck
file to the root directory of this
repo. In this file, you specify the names of packages that you want to recheck.
This may save you some time by skipping checking packages that have been checked
and have passed last time. However, please note that your fix might break those
passed packages. To be conservative, you can always check the full list of
reverse dependencies, which can just be time-consuming for a package that has a
large number of reverse dependencies.
When your package has a large number of reverse dependencies, the job may take longer than six hours to finish, which will lead to timeout. There are two possible ways to avoid it:
-
Check a subset of packages each time. You can write a subset of package names into the
recheck
file, commit it, and push to the branch corresponding to the pull request. Then write another subset, and repeat. All reverse dependencies to be checked can be obtained viaxfun::pkg_dep()
, e.g.,res = xfun:::pkg_dep('survival', reverse = TRUE) writeLines(res[1:100], 'recheck')
-
Or fork this repo, go to
Settings -> Actions
and allow all actions in your forked repo. Then change therepository
inrev-check.yaml
to your repo that you want to check. Commit and push to your repo. Wait for the action to finish, which will cache the reverse dependencies and their dependencies. This can save quite a bit of R package installation time in the future. Then create a new branch, make an arbitrary change, and send yourself a pull request. The pull request is just for triggering the Github Action to do the reverse dependency checks, because these checks are performed only in pull requests. If timeout still occurs with this method of caching R packages, you will have to use the first method.
From my experience, checking a package takes about one or two minutes on average. You are likely to hit the timeout if you need to check more than 300 packages.
You can also run xfun::rev_check()
locally in this repo. The help page
?xfun::rev_check
has more information on its usage. Basically, you need to
pass the package name and the path of its development version to this function,
e.g.,
xfun::rev_check('knitr', src = '~/Downloads/repo/knitr')
If you want to run xfun::rev_check()
locally in this repo, please note that it
will create an R library at ~/R-tmp
, which will be used to install reverse
dependencies and their dependencies (which you probably don't use routinely, so
a dedicated path ~/R-tmp
is used instead of the usual .libPaths()
). Other
than that, all file I/O will only occur inside this repo.