January 31, 2022 From rOpenSci (https://deploy-preview-488--ropensci.netlify.app/blog/2022/01/31/package-build-failures/). Except where otherwise noted, content on this site is licensed under the CC-BY license.
The rOpenSci R-universe is a bit special as, compared to other R-universes, it builds docs for all the packages in our suite.
Looking at the dashboard helps us identify failures in building the packages as well as in building the pkgdown websites.
We then help authors fix these issues in order to comply with our package curation policy.
As a package author you should also rely on continuous integration in your own repo for catching e.g. R CMD check
problems.
Following one of our latest rounds of monitoring, we summarize some common and less common mistakes.
Many of them are not specific to our build system.
If you maintain an rOpenSci package and notice an error for your package in the dashboard and the error message is not clear enough,
pkgdown::build_site()
.rotemplate::build_ropensci_docs()
(it might generate a logo and favicons that you’d have to delete).Packages needed in the vignettes should be listed in the Suggests
dependency field of DESCRIPTION
.
For packages needed in articles (vignettes that are .Rbuildignore
d) you can (at least for the rOpenSci docs building) use the extra_packages
field in _pkgdown.yml
as the docs building system will install those too.
For system dependencies needed in the vignettes, you can also list APT packages in _pkgdown.yml
. Alternatively, your code could also automatically install any dependency on pkgdown or CI (cf example in rdataretriever).
Remember that your vignette cannot be built if it’s missing other necessary information (e.g. credentials), as those are not available on R-universe. Therefore, you need to resort to pre-computing your vignette or article.
Before knitr 1.35, a chunk like the one below, with 4 opening back ticks but only 3 closing back ticks, would have been valid:
````{r}
1 + 1
```
Well it no longer is so a vignette with such a chunk will no longer be rendered! Thankfully since knitr 1.37 the error message is quite clear and it is rather straightforward to find the lines to fix.
NEWS.md
structure
In order for pkgdown to build your website changelog, your package changelog in NEWS.md
needs to be structured with h1 or h2, optionally with lesser headings below each version heading.
If you e.g. have no heading, you’ll get an error message such as
x callr subprocess failed: Invalid NEWS.md: inconsistent use of section headings.
ℹ Top-level headings must be either all <h1> or all <h2>.
ℹ See ?build_news for more details.
If you use temporary directories in your examples or tests, do not use tempdir()
directly but rather a subdirectory of it.
Also make sure to always clean after yourself.
Otherwise you might end up with a hard-to-debug error.
For more info, refer to the excellent “Test fixtures” testthat vignette by Jenny Bryan.
If you have tests or vignettes depending on non-cached API queries, and the API changes, you might end up with an error (e.g., if a data station changes IDs). Thankfully these errors are rather straightforward to fix. For tests, find more guidance in HTTP testing in R.
Now, if the API your package was wrapping no longer exists, the easiest way forward is to archive your package… and maybe create another one for an alternative API if there’s one?
.gitignore
When things work perfectly on your computer but not on R-universe or any other continuous integration, one potential problem is .gitignore
if it lists a folder or file that’s actually necessary for building the package or its docs!
In that case, either fix .gitignore
or the way that folder/file is used.
pkgdown will build any Markdown files in your package in ./
or ./.github
.
If you have e.g. an old issue template from when these files contained only HTML comments, there will be a pkgdown failure.
The fix is to fix, move or delete the Markdown file.
This isn’t a failure but is slightly annoying: If your README badges aren’t moved to the sidebar by pkgdown, check the structure of your badges paragraph.
In this post we provided you with a bouquet of some mistakes to avoid when developing a package. If you enjoyed this content, subscribe to our monthly newsletter that features a Package Development Corner section with tips!