Correct workflow to develop (and make available) an R package via GitHub?

gianmarco

TS Contributor
#1
Hi All,
I would very like to have some guidance on the use of Github to store and share R packages. Thank's to Dason and Jake for drawing my attention (to put it in a polite way) to my wrong use of Github as far as storing and making available different versions of the same package are concerned.

I would like to have some guidance (however short) on what follows:
let's assume I have a 'mypackage' package sitting on my pc. What I use to do (as a first basic step) is to create a Github repository and then uploading (i.e., copying; I am not familiar with technical jargon, sorry) 'mypackage' to the online repository. Now, my problem is with versioning.

As far as I have understood after Jake gave me some web references, I ought to create a release (say, v. 0.1.0) and 'link' (again, in a colloquial, not technical, jargon) the release to 'mypackage'. I would get, I imagine, 'mypackage v.0.1.0'.

Questions:
(1) What am I supposed to do when I want to add new features to my package, or to fix errors. Am I supposed to modify the 'mypackage' repository (it that called 'master'?) and then create a new version?

(2) What am I supposed to indicate in the field 'ver' in the master's DESCRIPTION file?

(3) once I got different releases, how users are supposed to install the latest version, or any of the earlier ones? Are they still supposed to use something like:
install_github("johnsmith/mypackage") ?


Thanks for any guidance you will provide.
Gm
 

trinker

ggplot2orBust
#2
Questions:
(1) What am I supposed to do when I want to add new features to my package, or to fix errors. Am I supposed to modify the 'mypackage' repository (it that called 'master'?) and then create a new version?
Whenever you feel like. I do after a release to CRAN. So do this whenever you normally would want to release a new version. To the second question you don't do anything special other than update the evrsion number in the DESCRIPTION file. When you have a version you want a release for and you've pushed it to GitHub then you got yo the repo and add /releases to the end of the url (e.g., https://github.com/trinker/qdap/releases) and make a release there.

(2) What am I supposed to indicate in the field 'ver' in the master's DESCRIPTION file?
I don't know of a `ver` field. I use Version: . You can have different meanings of the numbers and decimals here but what ever you choose be consistent. For me (https://github.com/trinker/qdap/blob/master/DESCRIPTION) I use:

Code:
Releases will be numbered with the following semantic versioning format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

* Breaking backward compatibility bumps the major (and resets the minor 
  and patch)
* New additions without breaking backward compatibility bumps the minor 
  (and resets the patch)
* Bug fixes and misc. changes bumps the patch
(3) once I got different releases, how users are supposed to install the latest version, or any of the earlier ones? Are they still supposed to use something like:
install_github("johnsmith/mypackage") ?
Youi use devtools::install_github with username/repo@tag. For example I have:

Code:
devtools::install_github('trinker/qdap@qdap_vers2.0.0')
You can see your tags (you create them when you make a release) by typing /tags at the end of the github repo url. E.G. https://github.com/trinker/qdap/tags

Now my versioning naming is stupid. Hadely uses better version names https://github.com/r-lib/httr/tags

So to get v1.3.1 of httr use:

Code:
install_github(c("hadley/httr@v1.3.1")
 

trinker

ggplot2orBust
#4
PPS you only ever have one repo of mypackage. You keep pushing to it and changing the version. Don't create multiple repos for the same package with different version numbers.
 

gianmarco

TS Contributor
#5
Thank you Trinker for taking the time to address my questions.
So, let's see if I got it right:

(1) I simply work on 'mypackage' repository
(2) When I modify things, or when I fix errors, I do all that working on the 'master' repository (is that name/adjective correct?) and then, when I am finished, I create a new release, passing from (say) v0.14 to 0.15
(3) I can (must?) update the package version in the DESCRIPTION file, and (quite obviously) use the same version number when I create the release for the package
(4) when I create a release, the version number is provided under "tag version"

Assuming that the preceding points are correct, I am wondering the following: do the users have to go through the hassle of keeping track of the current version of the package in order for them to add the version at the end of the 'devtools' command install_github() (let's say, install_github('johnsmith/mypackage@v0.15')?

EDIT:
I have created a release for the v0.14 of my CAinterpTools package. The tag I used was v0.14. Am I supposed to use install_github("gianmarcoalberti/CAinterprTools@v0.14") to install it? If I am, that means that users have to know in advance which version is the latest....or I am missing something.
 

Dason

Ambassador to the humans
#6
If you only want them using the newest version instead of the newest commit then yes they have to specify the version.

You could instead learn how to use branches so that the current version always resides as the head of the master branch and when you want to update the version you just merge your branch into master. Then people can just use install_github("gianmarcoalberti/CAinterprTools") to get the newest version.
 

Dason

Ambassador to the humans
#7
Question: do you have your old repositories for the other versions stored anywhere on your system? If so we could rebuild the history and get the repository looking the way it should.
 

Dason

Ambassador to the humans
#9
It's possible to merge them all into one repository so you save the revision history. I'm assuming that when you go from one version to another you don't go back and modify the code from a previous version at all? If that's the case then it should be a breeze to bring it all into one. I'd be willing to help with that if you make those folders available somehow. I don't remember if you're a part of the shared talkstats folder on dropbox or if you use dropbox at all but if you upload them somehow and get me a link I could bring them all together for you. Maybe even make a video with some commentary to explain the process of how to do it so you understand how git works a bit better.
 

gianmarco

TS Contributor
#10
What if I create releases for each individual earlier version, and attach the corresponding zipped source code to each release? Is there anything wrong with that?
 

Dason

Ambassador to the humans
#11
That happens automatically when you create a release in GitHub. And that was going to be the plan while bringing it all together.