I got my first package onto CRAN, and YOU CAN TOO

It’s almost 2 weeks since I had my first package successfully submitted to CRAN. The runcharter package is special to me for lots of reasons – it was a tough problem to crack, and it’s one I’ve worked on with a variety of tools over the years. If this package had existed back in 2012, (and if I’d known what R was back then), my working life would have been much easier.

The package has been gathering dust on github for a couple of years now. Spurred on by the success of my NHS-R colleagues, who recently successfully submitted the NHSRplothedots package to CRAN (I’ll let them write about that), I decided to go for it, and try my luck.

I was pretty confident that the package was in a good shape – I’d set up GitHub actions to run R CMD checks on each commit. The benefit of this, in addition to running those checks on your own laptop/PC, is that the checks are running on several operating systems, rather than just your native one, and different versions of R, including the development versions. If your package won’t work on the development versions, it won’t make it to CRAN.

You can set the github actions up via the {usethis} package, which, it has to be said, has lowered the barriers in package development significantly.

You’ll also need to have set up unit tests – most likely using {testthat} (although I really like the combination of {checkmate} and {tinytest}).

I’m not sure if there is a defined percentage of code that has to be covered by testing – I’ve seen some packages with large codebases on CRAN with relatively low code coverage. The higher you can get it the better. runcharter is at 94% currently, the NHSRplotthedots package is at 100%, with an extensive battery of tests, mainly due to @tomjemmet, who is an absolute pro at this kind of stuff.

Both these steps go a long way to getting your package ready.

I’m glossing over things like package documentation, READMEs and package websites using pkgdown. While a website is an optional extra, pkgdown does make it pretty straightforward to get a website up and running. You should probably take advantage of it.

You’re most likely to get tripped up by relatively minor details.

Here are a few things you will need to check and/or think about:

The DESCRIPTION file

The title should be in title case (this is not title case)
For clarity:
The Title Should Be in Title Case

That last line IS in title case.

If you’re not sure – this title case converter will help you check.

The actual description part needs to be a short paragraph (somewhere around 3-4 sentences) and the spacing / indenting needs to be accurate. Your package probably won’t even build locally if the indentation is incorrect – which, is why, until the night I submitted it, my description was a one liner. I managed to flesh it out, and keep it aligned correctly (using 4 spaces for the second line onwards).

URLS

I somehow had a URL in my description file that did not have a trailing ‘/’. So that was a failed submission.

If your URL points to ‘http://’ rather than ‘https://’ that will also be a problem. If your URL has a redirect – you have a problem.

Thankfully there is a {urlchecker} package that helps with all these issues.

I’ve set up a file here with a some links and guides I’ve found over the last few months or so:

https://github.com/johnmackintosh/CRANt-touch-this

If you have any more good ones, or encounter a stumbling block that is not already covered, please raise a PR.

I hope this helps someone else get their package onto CRAN