How do I add a Changelog or NEWS file to my R package?

Question

I have a package on CRAN that I would like to add a ChangeLog for, but I cannot find information anywhere on how to do this.

I looked on the "Writing R Extensions" document that CRAN provides, but it only mentions ChangeLogs and gives no direction (I could find) about how to create one.

I noticed from downloading tarballs from other packages on CRAN (e.g. seacarb) that their ChangeLogs are Unix Executable Files (I'm on a Mac) so that's not too helpful.

I imagine this is a common problem, but Googling "changelog R package" just brings up ChangeLogs for really popular packages...

Acanthous

Answer 1

You can either provide a NEWS file or a ChangeLog file, or both, to describe changes in your package. You have to add these files in the top level folder of your project, i.e. in the same folder as your DESCRIPTION and NAMESPACE.

This is documented in the R package manual in paragraph 1.1 Package structure. In particular, this paragraph points to the GNU standard:

For the conventions for files NEWS and ChangeLog in the GNU project see http://www.gnu.org/prep/standards/standards.html#Documentation.

---

Hadley points out that "Generally you should use a NEWS file, and not ChangeLog. I think the purpose of ChangeLog (to list every change), has been subsumed by source code control".

---

To create a NEWS file, simply create a text file called NEWS in the top level folder of your package. You maintain this file by hand.

Here is an extract from the NEWS file from my package miniCRAN (CRAN link):

miniCRAN v0.0-21 (Release date: 2014-08-18)
==============

Changes:

* Changes to defaults in plot.pkgDepGraph() to move legend to left of plot area.

miniCRAN v0.0-20 (Release date: 2014-08-18)
==============

Changes:

* Modified examples to reduce running time, mostly using \dontrun{} sections

Thereabouts

Generally you should use a NEWS file, and not ChangeLog. I think the purpose of ChangeLog (to list every change), has been subsumed by source code control. – Batho

Great, I will create a NEWS file instead, but how do I make that file? Should I write up a txt file, and will it be converted to the proper format when I create the tarball? I'm a bit confused on the process of creating the file. I am making the package with RStudio. Since it does most of the creation for me, I may be a little lacking in understanding exactly how the package (and its files) is created. – Acanthous

And for users wanting to see this news news(package="yourPackage") – Mcghee

Answer 2

NEWS.md files are now also supported by CRAN (Which renders them as html) and more recently by the news() function.

https://cran.r-project.org/doc/manuals/r-devel/NEWS.html

Mcghee

Answer 3

If you are following this and opting for NEWS.md then make sure news() reads the same correctly (at the same time it looks great on GitHub).

You can do the same in your local builds of the packages.

It seems like it has a specific format you have to adhere with.

I tried like this (and it works) (check here)

# *News*

# tidycells 0.1.9 (2019-07-31)

## Initial Submission

* **CRAN** Initial Submission

# tidycells 0.1.5 (2019-07-30)

## Final Codebase Release in GitHub

* Final Release in GitHub for **CRAN** Submission
* Only Minor Documentation Change after this and before next **CRAN** Submission

# tidycells 0.1.0 (2019-07-25)

## Initial Release to GitHub

* Initial Release to GitHub
* Prior to this it was private package

Escallop

I'm using the new format NEWS.Rd, actually I use a Rmd and knit it. The current problem yet not solved is that for ex.: devtools::show_news() only looks for the NEWS file, and the generated docs (at least with roxygen) doesn't add the "Package News" link in the documentation. So I use the following pipeline: In NEWS.Rmd I add these lines at the beginning yaml code. output: github_document: html_preview: false md_document: pandoc_args: [ "--output", "NEWS", ] Then run this to knit it: rmarkdown::render("NEWS.Rmd", output_format = "all") – Minette