13  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.

13.1 Versioning

13.2 Releasing

  • Using usethis::use_release_issue() and devtools::release() will help you remember about more checks.

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

  • CRAN does not like too frequent updates. That said, if you notice a major problem one week after a CRAN release, explain it in cran-comments.md and try releasing a newer version.

13.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 written about in our newsletter but see next chapter about marketing about how to inform more potential users about the release.
  • For more guidance about the NEWS file we suggest reading the tidyverse NEWS style guide.