How to auto-update a Package version number

Andy Nicholls, Head of Consulting, Mango Solutions

On Monday I was supporting Aimée Gott’s EARL workshop on “Current Best Practices in Formal Package Development”. A question came up which often comes up on our public and private training courses as we talk through the benefits of devtools and roxygen2. That is, “Is there any way I can automatically update the version number each time I build my package?” Currently neither devtools nor roxygen2 offer this functionality but in a few lines of R code you can write a script to do this for you.

To illustrate what we’re trying to achieve let’s create an empty package using the create function from devtools.

The create function prints the package DESCRIPTION file to screen but find the file and read the information into R directly.

As you can see we start with a package of version 0.0.0.9000. What we want to do is ensure that when we next build our package the version number updates to 0.0.0.9001. Generally, it’s good to manually update the other numbers as they represent key milestones in the lifecycle of our package.

To achieve this I’m going to borrow from one of Mango’s R build scripts. If you’ve not come across a build script before it’s simply an R script that runs through the typical steps we always take when building an R package. Build scripts are generally used in formal package development and can be very complicated. However even if you’re just building R packages locally I would still recommend writing one to ensure consistency in the way you build R packages. A simple build script might run through the following stages:

1. Run tests
2. Build documentation
3. Update DESCRIPTION file
4. Run an R CMD check
5. Build package

Of the five steps above all but number 3 are handled by devtools and roxygen2. So let’s look at number 3. Specifically we use the following code to update the version number. This example is a simplified version of one we use at Mango with all the error checking removed for simplicity. The function updates our DESCRIPTION file and returns the new version number to the console.

Now we call our function on our example file.

So now we have a function that can automatically update the version number in the DESCRIPTION file. This can be added in to your build script with a switch so that it’s only triggered after the package builds successfully.