使用git / github对R包进行版本控制？

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 xyz
• the develop branch contains code under development. Use version format xyz-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, eg

git checkout master
git tag 1.2.3
git push --tags

That way users can install whatever version they'd like, eg

install_github("owner/repos@1.2.3")

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

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.

Answer 2

One suggestion that I think closely follows your current workflow:

• After you commit and push version 1.0.0 and set the "github release" to 1.0.0, create a dev version and change the DESCRIPTION file version to 1.0.0.9000.

• Then, when you fix bugs, etc, you should move the dev version number in
  the DESCRIPTION file forward to 9001, 9002, ..., n . Don't do a "github release".

• When your ready, drop the .9000 and bump the version to 1.0.1, push an updated DESCRIPTION, and set a new "github release".

This is borrowed from Hadley's solution offered in his book on R Packages.

"Instead always use . to separate version numbers. A released version number consists of three numbers, ... For version number 1.9.2, 1 is the major number, 9 is the minor number, and 2 is the patch number. Never use versions like 1.0, instead always spell out the three components, 1.0.0."

"An in-development package has a fourth component: the development version. This should start at 9000. For example, the first version of the package should be 0.0.0.9000. There are two reasons for this recommendation: first, it makes it easy to see if a package is released or in-development, and the use of the fourth place means that you're not limited to what the next version will be. 0.0.1, 0.1.0 and 1.0.0 are all greater than 0.0.0.9000."

"Increment the development version, eg from 9000 to 9001 if you've added an important feature that another development package needs to depend on."

http://r-pkgs.had.co.nz/description.html#version

In another section on releasing package he says:

"If you've been following the advice in versioning, the version number of your in-development package will have four components, major.minor.patch.dev, where dev is at least 9000. The number 9000 is arbitrary, but provides a strong visual signal there's something different about this version number. Released packages don't have a dev component, so now you need to drop that and pick a version number based on the changes you've made. For example, if the current version is 0.8.1.9000 will the next CRAN version be 0.8.2, 0.9.0 or 1.0.0"