After learning how to create packages, I found myself wrestling with simultaneously maintaining development and stable releases.

Git creates a SHA hash for each commit. Here’s an example d2c488a892a15af4b5e488bd5ac085cb666eaf80. Not exactly user-friendly and moreover, it’s impossible to figure out the chronological order of the commits. However, Git has a tag feature which can be used to create a user-friendly name for the commit.

GitHub’s Release feature builds upon Git’s tag feature to easily provide software to others. The steps are:

  1. Create a new Release of your project - https://github.com/<username>/<repo_name>/releases/new

    GitHub New Release
  2. Enter your package’s DESCRIPTION file’s version field for the Tag version box and select the branch and commit for your code.
  3. Enter the Release title.
  4. Enter a short description of the Release.
  5. Publish the Release.

Almost done!

  1. Now create a tag named Current and associate it with the same branch and commit as you did above. Or if there is already a Current tag, edit it so it points to the new version of the code.

The Current tag will automatically install the current version of your package without needing to know an explicit version number with this R statement:

devtools::install_github("<username>/<repo_name>@Current")

For one-person projects, especially those done on 2 computers, changes can be checked on the master branch without impacting others using your package. What?! You have unreleased code on the master branch! There are small changes that are not worth releasing nor maintaining on a separate branch. However, for new features, I create a branch and a new R file which allows for easy merges.

But wait, there’s one more file, README.md. I use the README file to note changes and document the details in the R files, so pkgdown will generate an up-to-date website. The releases are listed in reverse chronological order. Before I commit the final changes, I decide on the tag name and edit the README to reflect the URL. Here’s an example from my rprofile.site project

#### [10-Jan-2017](https://github.com/dgabbe/rprofile.site/tree/2017-01-10) Changes
* `.py` files renamed to `.command` so scripts can be doubled clicked or run from command line.

Just remember the URL will be broken until the tag is created in GitHub.