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

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