Versioning an R package with git/github?

Question

I'm having trouble determining a workflow for updating the version number of my R packages on github to avoid incorrectly named "in-between" versions. Here's what I do now.

• commit and push, say, version 1.0.0, and set the release to be 1.0.0
• commit and push some bug fixes, etc, without changing the DESCRIPTION file
• eventually decide I should bump the version to, say, 1.0.1, and so commit and push an updated DESCRIPTION, then set a new release.

The problem with this is that if someone (say, me) downloads from github after I've made some fixes but before I've bumped the version, the version they think they have is 1.0.0 (because that's what's still in the DESCRIPTION) but it's really got something in between 1.0.0 and 1.0.1.

Something like this seems to be discussed at the question "Is it possible to add a version number using git / github", where but is not specific to R and so I can't tell if it's talking about the same thing or not or how that would be implemented for R, anyway.

There's also the question "Automating version increase of R packages" which has an answer which automatically updates it, though in the comments, we see that Hadley is "basically not sold on the benefits of incrementing version automatically" (https://github.com/hadley/devtools/issues/501). The code there also depends on Make so isn't cross-platform.

Answer 1

I highly recommend to follow the Git Flow branching model, where:

• the master branch contains code of the latest stable release. Use version format x.y.z
• the develop branch contains code under development. Use version format x.y.z-9000

Let master be the default checkout branch on GitHub. That way users will always get the latest release, when they install R packages using:

install_github("owner/repos")

Users who wish to install the developers version, can use:

install_github("owner/repos@develop")

Next, if your package is also on CRAN, be strict and have master reflect exactly what is on CRAN. That way the user install the same identical package version regardless whether they use:

install.packages("repos")

or

install_github("owner/repos")

This way people also see the same info regardless of they visit your CRAN page or your GitHub page. Moreover, you can rest assured that all users will see the same stable information / version, even if you tag along updating the develop (only savvy users will be aware of this branch).

Next, when you release new versions, you can git tag them with their version number, e.g.

git checkout master
git tag 1.2.3
git push --tags

That way users can install whatever version they'd like, e.g.

install_github("owner/repos@1.2.3")

Tools for this? The git flow extension is an awesome tool to orchestrate the above, e.g.

git checkout develop
git flow release start 1.2.4
emacs DESCRIPTION ## Update version x.y.z-9000 -> x.y.z+1
R CMD build ...
R CMD check ...
git flow release finish 1.2.4
git checkout master
git push
git push --tags
git checkout develop
emacs DESCRIPTION ## Bump version to x.y.(z+1)-9000
git commit -am "Bump develop version [ci skip]"
git push

I've used the above on a daily basis for a good two years - I cannot imagine not using it.