Have we got NEWS.md for you

The Jumping Rivers Blog

4 mins ago

[This article was first published on The Jumping Rivers Blog, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)

Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

When developing a package it is essential to track the changes you make to your code. This is especially vital if they are breaking changes which have implications for any code written that depends on your package, i.e. a major version bump. Although you can always look back at your version control history in git, it is also convenient to have documentation which summarises the changes.

This is where the NEWS file comes in. Usually a .md file, the NEWS contains a description of the changes made between each version of a package up until the latest version. It is used to log things such as new features that have been added or bugs that have been fixed.

In this blog post we will look at how to write a NEWS file and what guidelines and good practices there are to follow.

Do you use RStudio Pro? If so, checkout out our managed RStudio services

< !-- This is where the ad goes! Just use the name of the shortcode file. -->

Who uses the NEWS

A NEWS file is useful for developers to keep track of changes. However, it is primarily looked at by users of the package to check any changes in a new version that could affect or be of interest to them. Therefore, the changes logged in a NEWS file are specifically user-facing, rather than a complete list of all changes.

NEWS file guidelines

There is not really a strict set of rules when it comes to NEWS files in R. Nevertheless, there are some rough guidelines to keep in mind. See, for example, Sec 1.1 of the R package manual and Ch 18 of R packages (second edition).

Some R package universes also have their own NEWS file guidelines. For example, tidyverse, rOpenSci and Bioconductor. These guidelines have a lot of overlap and mostly follow what we will detail in the following sections.

Location and file type

Let’s first consider where the NEWS should sit within your package.

The NEWS file is usually found at the top level of the package folder, and can take one of the following formats:

Plain text (NEWS)
Markdown (NEWS.md) – this is the most common format
R document (inst/NEWS.Rd) – note that this sits in the inst subdirectory of your package, so gets copied into the top level when the package is installed

Whether you include a NEWS file is actually entirely optional. From our own analyses of the CRAN packages for diffify.com, we have found that less than half contain NEWS!

Content

The R package manual recommends the GNU standard. Referring to Sec 6.7, these guidelines state the following:

The NEWS should contain “user-visible” changes that are “worth mentioning”.
Changes for the latest release should be displayed at the top of the file, alongside a heading which indicates the version number.
Older items should be displayed further down the file and should never be discarded, since they will be of interest to a user upgrading from a previous version.
If the file gets very long, you can move some of the older changes to a separate ONEWS file.

What exactly is meant by the first point here? In general, the NEWS is intended first and foremost for the package users. It should therefore focus on changes that are likely of interest to the users, including new features, bug fixes and breaking changes.

Some R packages may also have a ChangeLog, the purpose of which is to list all changes (including to source code). This is more relevant to the package developers, and over time it’s purpose has become increasingly subsumed by version control softwares like GitHub.

Top tips for writing “good” NEWS

Since the guidelines above are a bit vague and open-ended when it comes to format, we will share some top tips and examples to help ensure your NEWS is readable and easily accessible!

Markdown is best

R packages (second edition) recommends the markdown format (NEWS.md) over the plain text and .Rd formats. Some advantages of NEWS.md include:

Markdown is readable as both plain text (e.g., when copied into an email) and HTML (e.g., when viewed on GitHub/GitLab).
If you’re building a {pkgdown} website for your package, the NEWS.md will get nicely rendered (including any links to GitHub users and issues).
Access to a usethis::use_news_md() shortcut for incrementing the version and adding a new heading to your NEWS.md file (for more info on version bumping, see semver.org).

In terms of how NEWS.md should be presented, we recommend something close to the template below, which includes both a major release (containing a lot of changes which have been divided into subsections) and a minor release:

# packageName 3.0.0

This is a major release adding a range of substantial new features and fixing a
large number of bugs

## Breaking changes

* `enhancedFunction()` now accepts an extra argument `newArg`, which controls
  the behaviour of ... (#18, #20, @parisa1)

* `legendFunction()` by default now generates a legend with no border, rather
  than a black border

## New features

* `newFunction()` added which does ... (#16, @myles-mitchell)

* `enhancedFunction()` now accepts an argument `newArg`, which controls the
  behaviour of ... (#18, #20, @parisa1)

## Bug fixes

* Axes generated using `plottingFunction()` no longer overlap (#25,
  @myles-mitchell)

# packageName 2.3.0

* Feature: added a new function which does... (#33, @parisa1)

* Fix: resolved a minor bug which prevented... (#46, @myles-mitchell)

When viewed in GitLab, this will be nicely rendered:

Note that the heading for each release is made up of the package name followed by the version number, and the changes are listed using bullet points. This also follows the format given in the tidyverse style guide which recommends that “each user-facing change to a package should be accompanied by a bullet” and that “each release should have a level 1 (#) heading”.

For enhanced readability, a major release with a lot of changes may be divided into subsections, including:

Breaking changes – any changes that may cause a user’s code to break or produce an unexpected output
New features – could include new functions and options
Bug fixes – self-explanatory

Note that items listed under Breaking changes should also be included again under the relevant section.

Rather than dividing into subsections, you could also label individual bullet points, as we have done for the minor release above.

For some of the changes above, we have credited individual developers and referenced the corresponding GitLab issues. These links have been automatically rendered in GitLab.

NEWS at Jumping Rivers

At Jumping Rivers we use a NEWS file format similar to the minor release in the example above:

Each item is recorded in a single line.
Items are listed altogether, rather than in separate sections.
Items are recorded following the Conventional Commits specification.

The choice of this format is due to the fact we roughly follow the GitLab flow model and have a short merge request cycle. Thus, few user-facing changes are added to the main branch in any one merge request (in theory).

Compatibility with utils::news()

The quickest way for a user to access package news is with the news() function (from the base-R utils package), which can handle the NEWS, NEWS.md and NEWS.Rd formats:

news(package = "packageName")

If you’re working in RStudio, this will display the NEWS under the Help tab, identifying the version number along with each set of changes. The screenshot below shows an excerpt for {dplyr}:

If you don’t have the package installed, you can also point the function to the package folder location using:

news(package = "packageName", lib.loc = "package_dir/")

where package_dir/ would be the directory containing the package folder.

When writing a NEWS file for your package, it is always a good idea to check that the news() function can correctly display it:

This is a quick and easy way to test your formatting.
It ensures your package NEWS can be easily accessed by your users.

As an example, here is an excerpt from the NEWS.md file for the {benchmarkme} package:

# benchmarkme Version 1.0.8 _2022-06-02_
  * fix: `get_ram()` for windows (thanks to @ArkaB-DS @xiaodaigh #45)
  * internal: linting & format NEWS.md file
  
# benchmarkme Version 1.0.7 _2022-01-17_
  * Internal: Suppress warnings on `sysctl` calls
  * Fix: `get_ram()` for windows (thanks to @ArkaB-DS #41)
  * Deprecate Solaris support

This is perfectly readable and consistent with the guidelines mentioned above.

Now, here is the output from the news() function:

The date is getting picked up by news() as the version number, making it unclear which version each set of changes corresponds to. The bullet points also look off.

The news() documentation provides precise formatting guidelines for all three file types. For the .md format, the guidelines are consistent with our template provided earlier. However, if you also want to show the release date, this should be enclosed in parentheses. A good heading would then be:

# packageName X.Y.Z (YYYY-MM-DD)

Beyond NEWS

Whilst the NEWS file is a great place to record user-facing changes to your package, you can’t be sure that people will actually read it. They could be missing out on some great new features that you have worked hard to introduce! Accompanying a version release with a blog post which highlights major new features and bug fixes can be an effective way to inform your users. This is also recommended by the tidyverse style guide.

From the user side you might find that looking through a NEWS file is fine for comparing a small number of changes or checking for new features. However, it can sometimes be hard to directly compare long lists of changes. Diffify is a tool that allows you to easily check what has changed between two versions of a package:

It directly shows you any dependencies that have changed, as well as any functions that have been added, removed or changed.
It also displays the NEWS file for each release between the two versions, so allows you to check the NEWS of any package in one place.

Disclaimer: We are developers on Diffify so may be slightly biased in recommending it, but we think it’s really useful and complementary to the NEWS!