news.Rmd

# News

Each user-facing change to a package should be accompanied by a bullet in `NEWS.md`. Minor changes to documentation don't need to be documented, but it's worthwhile to draw attention to sweeping changes and to new vignettes.

## Bullets

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 written with a user (not developer) in mind.

New bullets should be added to the top of the file (under the first heading).
Organisation of bullets will happen later, during the release process (Section \@ref(news-release)).

### 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).
```

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 computations 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 
  computations 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)
  ```
````

### Acknowledgement

If the bullet is related to an 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)
```

### Code style

Functions, arguments, and file names should be wrapped in backticks. Function names should include parentheses; omit "the argument" or "the function"

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

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

### Common patterns

The following excerpts 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.
    ```

## Organisation

### Development

During development, new bullets should be added to the top of the file, immediately under a "development" heading:

```
# haven (development version)

* Second update.

* First update.
```

### Release {#news-release}

Prior to release, the NEWS file needs to be thoroughly proofread 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 modelr 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 many bullets, the version heading should be followed by 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 organise 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 the bullet at the top of the section.

### 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"`.
```

## Blog post

For all major and minor releases, the latest news should be turned into a blog
post. The blog post should highlight major user-facing changes, and point to
the release notes for more details. 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.