news.qmd

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

## In-development

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. It's worth emphasizing this point --- the reader of your NEWS entries is likely unfamiliar with the day-to-day development work or internals of your package. Think carefully about how to concisely but clearly summarize what's changed and why it matters for them. If it doesn't matter (i.e. it's a purely internal change), you don't need a bullet.

New bullets should be added to the top of the file (immediately under the first heading) and should be a single line. Organisation and wrapping will happen later, during the release process.

```
# haven (development version)

* Second update.
* First update.
```

If the bullet is related to an issue, include the issue number. If the
contribution is a PR, and the author is not a package author, include the
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)
```

## Pre-release {#news-release}

Prior to release, the NEWS file needs to be thoroughly proofread, groomed, and organised into sections.

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

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

### Headings

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

API breaking changes 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"`.
```

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

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