18  Other markdown files

In this chapter we highlight two files that are conventionally used to provide some package-level documentation. These two are important, because they are featured on both the CRAN landing page and the pkgdown site for a package:

Even if your package is intended for a very limited audience and might not ever be released on CRAN, these files can be very useful. These two files don’t have to be written in Markdown, but they can be. In keeping with our practices for help topics and vignettes, it’s our strong recommendation and it’s what we describe here.

18.1 README

First, we’ll talk about the role of the README file and we leave off the file extension, until we’re ready to talk about mechanics.

The goal of the README is to answer the following questions about your package:

  • Why should I use it?
  • How do I use it?
  • How do I get it?

The README file is a long-established convention in software, going back decades. Some of its traditional content is found elsewhere in an R package, for example, we use the DESCRIPTION file to document authorship and licensing.

When you write your README, try to put yourself in the shoes of someone who’s come across your package and is trying to figure out if it solves a problem they have. If they decide that your package looks promising, the README should also show them how to install it and how to do one or two basic tasks. Here’s a good template for README:

  1. A paragraph that describes the high-level purpose of the package.

  2. An example that shows how to use the package to solve a simple problem.

  3. Installation instructions, giving code that can be copied and pasted into R.

  4. An overview that describes the main components of the package. For more complex packages, this will point to vignettes for more details. This is also a good place to describe how your package fits into the ecosystem of its target domain.

18.1.1 README.Rmd and README.md

As mentioned above, we prefer to write README in Markdown, i.e. to have README.md. This will be rendered as HTML and displayed in several important contexts:

Given that it’s best to include a couple of examples in README.md, ideally you would generate it with R Markdown. That is, it works well to have README.Rmd as the main source file, which you then render to README.md.

The easiest way to get started is to use usethis::use_readme_rmd().1 This creates a template README.Rmd and adds it to .Rbuildignore, since only README.md should be included in the package bundle. The template looks like this:

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# somepackage

<!-- badges: start -->

<!-- badges: end -->

The goal of somepackage is to ...

## Installation

You can install the development version of somepackage from [GitHub](https://github.com/) with:

``` r
# install.packages("devtools")
devtools::install_github("jane/somepackage")
```

## Example

This is a basic example which shows you how to solve a common problem:

```{r example}
library(somepackage)
## basic example code
```

What is special about using `README.Rmd` instead of just `README.md`?
You can include R chunks like so:

```{r cars}
summary(cars)
```

You'll still need to render `README.Rmd` regularly, to keep `README.md` up-to-date.
`devtools::build_readme()` is handy for this.

You can also embed plots, for example:

```{r pressure, echo = FALSE}
plot(pressure)
```

In that case, don't forget to commit and push the resulting figure files, so they display on GitHub and CRAN.

A few things to note about this starter README.Rmd:

  • It renders to GitHub Flavored Markdown.

  • It includes a comment to remind you to edit README.Rmd, not README.md.

  • It sets up our recommended knitr options, including saving images to man/figures/README- which ensures that they’re included in your built package. This is important so that your README works when it’s displayed by CRAN.

  • It sets up a place for future badges, such as results from automatic continuous integration checks (Section 20.2). Examples of functions that insert development badges:

  • It includes placeholders where you should provide code for package installation and for some basic usage.

  • It reminds you of key facts about maintaining your README.

You’ll need to remember to re-render README.Rmd periodically and, most especially, before release. The best function to use for this is devtools::build_readme(), because it is guaranteed to render README.Rmd against the current source code of your package.

The devtools ecosystem tries to help you keep README.Rmd up-to-date in two ways:

  • If your package is also a Git repo, use_readme_rmd() automatically adds the following pre-commit hook:

    #!/bin/bash
if [[ README.Rmd -nt README.md ]]; then
  echo "README.md is out of date; please re-knit README.Rmd"
  exit 1
fi

    This prevents a git commit if README.Rmd is more recently modified than README.md. If the hook is preventing a commit you really want to make, you can override it with git commit --no-verify. Note that Git commit hooks are not stored in the repository, so this hook needs to be added to any fresh clone. For example, you could re-run usethis::use_readme_rmd() and discard the changes to README.Rmd.

  • The release checklist placed by usethis::use_release_issue() includes a reminder to call devtools::build_readme().

18.2 NEWS

The README is aimed at new users, whereas the NEWS file is aimed at existing users: it should list all the changes in each release that a user might notice or want to learn more about. As with README, it’s a well-established convention for open source software to have a NEWS file, which is also sometimes called a changelog.

As with README, base R tooling does not require that NEWS be a Markdown file, but it does allow for that and it’s our strong preference. A NEWS.md file is pleasant to read on GitHub, on your pkgdown site, and is reachable from your package’s CRAN landing page. We demonstrate this again with dplyr:

You can use usethis::use_news_md() to initiate the NEWS.md file; many other lifecycle- and release-related functions in the devtools ecosystem will make appropriate changes to NEWS.md as your package evolves.

Here’s a hypothetical NEWS.md file:

# foofy (development version)

* Better error message when grooving an invalid grobble (#206).

# foofy 1.0.0

## Major changes

* Can now work with all grooveable grobbles!

## Minor improvements and bug fixes

* Printing scrobbles no longer errors (@githubusername, #100).

* Wibbles are now 55% less jibbly (#200).

The example above demonstrates some organizing principles for NEWS.md:

  • Use a top-level heading for each version: e.g. # somepackage 1.0.0. The most recent version should go at the top. Typically the top-most entry in NEWS.md of your source package will read # somepackage (development version).2

  • Each change should be part of a bulleted list. If you have a lot of changes, you might want to break them up using subheadings, ## Major changes, ## Bug fixes, etc.

    We usually stick with a simple list until we’re close to a release, at which point we organize into sections and refine the text. It’s hard to know in advance exactly what sections you’ll need. The release checklist placed by usethis::use_release_issue() includes a reminder to polish the NEWS.md file. In that phase, it can be helpful to remember that NEWS.md is a user-facing record of change, in contrast to, e.g., commit messages, which are developer-facing.

  • If an item is related to an issue in GitHub, include the issue number in parentheses, e.g. (#​10). If an item is related to a pull request, include the pull request number and the author, e.g. (#​101, @hadley). This helps an interested reader to find relevant context on GitHub and, in your pkgdown site, these issue and pull request numbers and usernames will be hyperlinks. We generally omit the username if the contributor is already recorded in DESCRIPTION.

The main challenge with NEWS.md is getting into the habit of noting any user-visible change when you make it. It’s especially easy to forget this when accepting external contributions. Before release, it can be useful to use your version control tooling to compare the source of the release candidate to the previous release. This often surfaces missing NEWS items.

  1. If it really doesn’t make sense to include any executable code chunks, usethis::use_readme_md() is similar, except that it gives you a basic README.md file.↩︎

  2. pkgdown supports a few other wording choices for these headings, see more at https://pkgdown.r-lib.org/reference/build_news.html.↩︎