7 News

7.1 News bullets

Each user-facing change should be accompanied by a bullet in NEWS.md. The goal of the bullet is to briefly describe the change so users of the packages can understand what’s changed. This can be similar to the commit message, but often the commit message will be developer facing, and the bullet will be user facing.

It is not necessary to describe minor documentation changes. But it’s worthwhile to draw attention to sweeping changes, and to new vignettes.

New bullets should be added to the top of the file (under the version heading). Organisation of bullets will happen later, during the release process (as described below).

7.1.1 General style

Strive to place the name of the function as close to the beginning of the bullet as possible. A consistent location makes the bullets easier to scan, and easier to organise prior to release.

# Good
* `ggsave()` now uses full argument names to avoid partial match warning (#2355).

# Bad
* Fixed partial argument matches in `ggsave()` (#2355).

Lines should be wrapped to 80 characters, and each bullet should end in a full stop.

Frame bullets positively (i.e. what now happens, not what used to happen), and use the present tense.

# Good
* `ggsave()` now uses full argument names to avoid partial match warnings (#2355).

# Bad
* `ggsave()` no longer partially matches argument names (#2355).

If the bullet is related to a issue, include the issue number. If the contribution was a PR, and the author is not a package author, include their GitHub user name. Both items should be wrapped in parentheses and will generally come before the final period.

# Good
* `ggsave()` now uses full argument names to avoid partial match warnings 
  (@wch, #2355).

# Bad
* `ggsave()` now uses full argument names to avoid partial match warnings.

* `ggsave()` now uses full argument names to avoid partial match warnings.
  (@wch, #2355)

Functions and arguments should be wrapped in back ticks, and function names should include parentheses.

# Good
* In `stat_bin()`, `binwidth` now also takes functions.

# Bad
* In the `stat_bin` function, the `binwidth` argument now also takes functions.

Many news bullets will be a single sentence. This is typically adequate when describing a bug fix or minor improvement, but you may need more detail when describing a new feature. For more complex features, include longer examples in fenced code blocks (```). These will be useful inspiration when you later write the blog post.

# Good
* In `stat_bin()`, `binwidth` now also takes functions.

# Better
* In `stat_bin()`, `binwidth` now also takes functions. The function is 
  called with the scaled `x` values, and should return a single number.
  This makes it possible to use classical binwidth computatons with ggplot2.

# Best
* In `stat_bin()`, `binwidth` now also takes functions. The function is 
  called with the scaled `x` values, and should return a single number.
  With a little work, this makes it possible to use classical bin size 
  computatons with ggplot2.
  
  ```R
  sturges <- function(x) {
    rng <- range(x)
    bins <- nclass.Sturges(x)
    
    (rng[2] - rng[1]) / bins
  }
  ggplot(diamonds, aes(price)) +
    geom_histogram(binwidth = sturges) + 
    facet_wrap(~ cut)
  ```

7.1.2 Common patterns

The following exercepts from tidyverse news entries provide helpful templates to follow.

  • New family of functions

    * Support for ordered factors is improved. Ordered factors throw a warning 
      when mapped to shape (unordered factors do not), and do not throw warnings 
      when mapped to size or alpha (unordered factors do). Viridis is used as 
      default colour and fill scale for ordered factors (@karawoo, #1526).
    
    * `possibly()`, `safely()` and friends no longer capture interrupts: this
      means that you can now terminate a mapper using one of these with
      Escape or Ctrl + C (#314).
  • New function

    * New `position_dodge2()` provides enhanced dogding for boxplots...
    
    * New `stat_qq_line()` makes it easy to add a simple line to a Q-Q plot. 
      This line makes it easier to judge the fit of the theoretical distribution 
      (@nicksolomon).
  • New argument to existing function:

    * `geom_segment()` gains a `linejoin` parameter.
  • Function argument changes behaviour:

    * In `separate()`, `col = -1` now refers to the far right position. 
      Previously, and incorrectly, `col = -2` referred to the far-right 
      position.
  • Function changes behaviour.

    * `map()` and `modify()` now work with calls and pairlists (#412).
    
    * `flatten_dfr()` and `flatten_dfc()` now aborts with informative 
       message if dplyr is not installed (#454).
    
    * `reduce()` now throws an error if `.x` is empty and `.init` is not
      supplied.

7.2 Organisation

Prior to release, the NEWS file needs to be thoroughly proof read and groomed.

Each release should have a level 1 heading (#) containing the package name and version number. For smaller packages or patch releases this amount of organisation may be sufficient. For example, here is the NEWS for model 0.1.2:


# modelr 0.1.2

* `data_grid()` no longer fails with modern tidyr (#58).

* New `mape()` and `rsae()` model quality statistics (@paulponcet, #33).

* `rsquare()` use more robust calculation 1 - SS_res / SS_tot rather 
  than SS_reg / SS_tot (#37).

* `typical()` gains `ordered` and `integer` methods (@jrnold, #44), 
  and `...` argument (@jrnold, #42).

If there are manymany bullets, the version heading should be following issues grouped into related areas with level 2 headings (##). Three commonly used sections are shown below:

# package 1.1.0

## Breaking changes

## New features

## Minor improvements and fixes

It is fine to deviate from these headings if another organisation makes sense. Indeed, larger packages will often require a finer break down. For example, ggplot2 2.3.0 included these headings:

# ggplot 2.3.0
## Breaking changes
## New features
### Tidy evaluation
### sf
### Layers: geoms, stats, and position adjustments
### Scales and guides
### Margins
## Extension points
## Minor bug fixes and improvements
### Facetting
### Scales
### Layers
### Coords
### Themes
### Guides
### Other

It is not worthwhile to organis bullets into headings during development, as it’s not typically obvious what the groups will be in advance.

Within a section, bullets should be ordered alphabetically by the first function mentioned. If no function is mentioned, place at the top of the section.

7.2.1 Breaking changes

If there are API breaking changes (as discovered during revdepchecks) these should also appear in their own section at the top. Each bullet should include a description of the symptoms of the change, and what is needed to fix it. The bullet should also be repeated in the appropriate section.

## Breaking changes

* `separate()` now correctly uses -1 to refer to the far right position, 
  instead of -2. If you depended on this behaviour, you'll need to condition
  on `packageVersion("tidyr") > "0.7.2"`.

7.3 Blog post

For all major and minor releases, the latest news should be turned into a blog post. The blog post should hightlight major user-facing changes, and point to the release notes for more deatils. Generally, you should focus on new features and major improvements, including examples showing the new features in action. You don’t need to describe minor improvements and bug fixes, as the motivated reader can find these in the release notes.