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
- We strongly recommend that rOpenSci packages use semantic versioning. A detailed explanation is available in the description chapter.
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.mdfile in the root of your package. We recommend using
NEWS.mdto 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
taxizepackage repo for instance.
- If you use
NEWS, add it to
.Rbuildignore, but not if you use
- 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:
DEPRECATED AND DEFUNCT,
DOCUMENTATION FIXESand 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)will resolve on GitHub in Releases to a link to that issue in the repo.
- After you have added a
git tagand 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.
- For more guidance about the NEWS file we suggest reading the tidyverse NEWS style guide.