Your R package is doomed to evolve as you add new features and bug fixes. There is some value in cultivating a NEWS file as a response to package transformation. In this post, we shall go through why keeping track of changes, how to create and maintain a changelog, advocating for the NEWS.md format.
Why cultivate a changelog? You will most probably change stuff in your package. Discussing package evolution is beyond the scope of this post, refer to e.g. this chapter of the rOpenSci dev guide. This post is about documenting changes. Even with a very clear version control history, having a text version of changes can be useful: * to you and other developers, when looking back; * to contributors, if you acknowledge their user name; * to users, when updating the package or wondering when something changed; * to you and other communicators, when drafting content (blog post, tweet, email) about a release.
Why write the changelog as NEWS.md? There are several possible formats for maintaining an R package changelog, according to the documentation of utils::news(): inst/NEWS.Rd formatted like other Rd files, a Markdown NEWS.md, plain-text NEWS or inst/NEWS. In all cases, it means users can access the changelog * From the package CRAN page (in the case of CRAN packages, of course). See commonmark NEWS, ouch NEWS, rhub NEWS. The differences in URL path, display, page title are due to differences in the way the different changelog formats are parsed and rendered. * with utils::news(), either reading it all at once
Some users might get creative and actually write their own function for browsing changelogs.
The actually serious CRAN package ouch uses inst/NEWS.Rd, like 134 other packages at the time of writing. In the case of ouch, inst/NEWS.Rd is actually created from a plain-text inst/NEWS using R CMD Rdconv. As regards plain-text NEWS files like the one in commonmark source, when preparing this post I found 413 inst/NEWS and 1,055 NEWS in CRAN packages. Last but not least, at the time of writing there were 1,174 packages with a NEWS.md file
Limits of NEWS.md as a format There are two limitations to NEWS.md. * One caveat is the utils::news() function. If the user uses that and doesn’t have commonmark and xml2 installed, it will fail – which is documented but not especially pleasant. * Another caveat, more specific to GitHub, is that NEWS.md locally doesn’t render links to issues magically, unlike GitHub releases (and unlike pkgdown). That is why Yihui Xie uses a placeholder inst/NEWS.Rd in e.g. knitr. Maybe a good idea for a function would be one to convert from NEWS.md to an informative inst/NEWS.Rd as feature-rich as pkgdown changelog?
Limits to NEWS as a communication channel Now, no matter as good your NEWS.md file is, you need to keep in mind that some (most?) users will never read it. 😉 How to be sure they are informed, in that case? On the one hand, communicating widely about executed or planned releases in blog posts for users and for developers can be useful. If your blog post RSS feed is not a part of R Weekly, you can submit such links via a PR to the R Weekly repo (“Updated packages” category) or via R Weekly webform. Maybe you even have a mailing list for users? And to come back to pkgdown websites, you can tweak the changelog to have it display one page per major version and related minor versions, and to have the navbar feature release blog posts.
On the other hand, you can add information about changes inside the package manual! For instance, in tidyr docs there are lifecycle badges and explanatory text: compare the page of tidyr::gather() (retired) and tidyr::pivot_longer() (maturing).
Now, in terms of workflow, you could * update the changelog for each contribution; * only update the changelog before releases, by looking at version control history and the issue tracker, potentially using something like GitHub milestones; * use fledge that “has been designed to streamline the process of versioning R packages on Git, with the functionality to automatically update NEWS.md and DESCRIPTION with relevant information from recent commit messages”.