R versions of a package from git / github?
I am having trouble defining a workflow to update the version number of my R packages on github to avoid incorrectly named "in-between" versions. This is what I am doing now.
- commit and push, say version 1.0.0 and install 1.0.0 release
- commit and push some bug fixes etc. without changing the DESCRIPTION file
- will ultimately decide that I should bump the version up to, say 1.0.1, and thus commit and press the updated DESCRIPTION and then install the new version.
The problem is if someone (say me) downloads from github after I did some fixes, but before I pushed the version, the version they think has is 1.0.0 (because what's still in the DESCRIPTION), but it did get somewhere between 1.0.0 and 1.0.1.
Something like this seems to be discussed on the question " Is it possible to add a version number with git / github ", but this is not the case for R, and so I cannot tell if it says the same thing or not or how it is will be implemented for R anyway.
This also raises the question " Automatically increasing the version of R packages ", which has an answer that automatically updates it, although in the comments we see that Hadley is "mostly" not sold on the benefits of the incremental version automatically "( https://github.com / hadley / devtools / issues / 501 ) The code there also depends on Make, so it is not cross-platform.
source to share
I highly recommend following the Git Flow diagram where:
- the branch
master
contains the code for the latest stable release. Use version formatx.y.z
- the branch
develop
contains the code under development. Use version formatx.y.z-9000
Let's master
be the default checkout branch on GitHub. This way, users will always get the latest version when they install R packages using:
install_github("owner/repos")
Users wishing to install the developer version can use:
install_github("owner/repos@develop")
Then, if you are also using the CRAN package, be strict and master
accurately reflect what is on the CRAN. This way the user installs the same identical version of the package regardless of whether they use:
install.packages("repos")
or
install_github("owner/repos")
This way, people also see the same information regardless of whether they visit your CRAN page or your GitHub page. Also, you can be sure that all users will see the same stable info / version, even if you flag an update develop
(only advanced users will know about this branch).
Further, when you release new versions, you can use git tag
them with your version number, for example
git checkout master
git tag 1.2.3
git push --tags
This way, users can install any version they want eg.
install_github("owner/repos@1.2.3")
Tools for this? The extension git flow
is a great tool for organizing the above, for example
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 been using this on a daily basis for two years - I can't imagine not using it.
source to share
One suggestion that I think follows your current workflow closely:
-
After you commit and click version 1.0.0 and set the "github release" to 1.0.0, create a dev version and change the version DESCRIPTION file to 1.0.0.9000.
-
Then when you fix bugs etc. you have to move dev version number to
DESCRIPTION file go to9001, 9002, ..., n
. Don't make a "github release". -
When you're ready, uncheck 0.9000 and set the version to 1.0.1, hit the updated DESCRIPTION, and install the new "github release".
This is borrowed from Hadley's solution proposed in his book on R Packages.
"Instead, always use. To separate the version numbers. The released version number consists of three numbers, ... For version 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 specify three components: 1.0.0.
"There is a fourth component in the development package: 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 the package has been released or is in development, and using fourth place means you are not limited to what the next version will be. 0.0.1, 0.1.0 and 1.0.0 are all larger than 0.0.0.9000. "
"Increase the development version, for example from 9000 to 9001, if you have added an important feature that another development package depends on."
http://r-pkgs.had.co.nz/description.html#version
In another section on package release, he says:
"If you've followed the guidelines for version control, your development package's version number will contain four components major.minor.patch.dev, where dev is at least 9000. The number 9000 is arbitrary, but provides a strong visual cue. It has something different about it. version number. The released packages do not have a dev component, so now you need to drop that and choose a version number based on the changes you made. For example, if the current version is 0.8.1.9000 the next CRAN version will be 0.8.2, 0.9.0 or 1.0.0 "
source to share