Chapter 10 Releasing a package

Your package should have different versions over time: snapshots of a state of the package that you can release to CRAN for instance. These versions should be properly numbered, released and described in a NEWS file. More details below.

Note that you could streamline the process of updating NEWS and versioning your package by using the fledge package.

10.1 Versioning

  • We strongly recommend that rOpenSci packages use semantic versioning. A detailed explanation is available in the description chapter.

10.2 Releasing

  • Git tag each release after every submission to CRAN. more info

10.3 News file

A NEWS file describing changes associated with each version makes it easier for users to see what’s changing in the package and how it might impact their workflow. You must add one for your package, and make it easy to read.

  • It is mandatory to use a NEWS or NEWS.md file in the root of your package. We recommend using NEWS.md to make the file more browsable.
  • Please use our example NEWS file as a model. You can find a good NEWS file in the wild in the taxize package repo for instance.
  • If you use NEWS, add it to .Rbuildignore, but not if you use NEWS.md
  • Update the news file before every CRAN release, with a section with the package name, version and date of release, like (as seen in our example NEWS file):
foobar 0.2.0 (2016-04-01)
=========================
  • Under that header, put in sections as needed, including: NEW FEATURES, MINOR IMPROVEMENTS, BUG FIXES, DEPRECATED AND DEFUNCT, DOCUMENTATION FIXES and any special heading grouping a large number of changes. Under each header, list items as needed (as seen in our example NEWS file). For each item give a description of the new feature, improvement, bug fix, or deprecated function/feature. Link to any related GitHub issue like (#12). The (#12) will resolve on GitHub in Releases to a link to that issue in the repo.
  • After you have added a git tag and pushed up to GitHub, add the news items for that tagged version to the Release notes of a release in your GitHub repo with a title like pkgname v0.1.0. See GitHub docs about creating a release.
  • New CRAN releases will be tweeted about automatically by roknowtifier and written about in our biweekly newsletter but see next chapter about marketing about how to inform more potential users about the release.