[Rd] suggestion for R >= 3.0: computer-readable CHANGELOG

[Duncan Murdoch]

Philippe Grosjean wrote:
> Hello,
>
> Here are a few questions that would be useful to get an answer via 
> dedicated functions in utils or tools packages:
> - When did function foo appeared in R or in a given package?
> - When did argument myarg appeared in function foo?
> - When did function bar get deprecated or when did it disappeared?
> - I wrote a script using functions foo and bar with R 1.9.1. My script 
> does not work any more with current version. What were all the changes 
> made to foo and/or to bar since then (this could obviously help me to 
> update my script for current R version)?
>
> Currently, we have to read NEWS (or perhaps a non official changelog) 
> manually to get such answers.
>
> The basic function to retrieve data that would answer to these questions 
> would be something like:
>
>  > changes(c("foo", "bar"))
>
> That function could, for instance, read information in a 
> computer-readable file named CHANGELOG... because the problem is there! 
> Changes are currently recorded in NEWS, but ONLY in a human-readable 
> form! A quick suggestion for a format for CHANGELOG by example:
>   

There is the tools::readNEWS function to read the NEWS file.  It's not 
just human readable.  That's what the RSS feed uses.
> Date       Object   Action  Value   Message
> 2009-04-17 package  commit  1.1-0   Enhanced version of my package
> 2009-04-15 foo      add     foo(y)  New function foo in my package
> 2009-04-14 bar      debug           bar(NULL) returned wrong result
> 2009-04-01 package  commit  1.0-0   First version of package on CRAN
>   

It doesn't contain dates, and dates don't really make sense.  (Many 
additions are introduced over a sequence of changes.  Do you give the 
first date, the last date?  What if the change is very minor, e.g. a 
typo in the docs?)   NEWS does contain R version numbers, and those are 
well defined.

The RSS feed does list the date on which it noticed each change to the 
NEWS file, but I think that is more useful for keeping up to date with 
changes, rather than defining when something happened.
> It should be kept simple. May be an "Author" field in the records would 
> be nice too. Also a function to record a new entry in the CHANGELOG 
> could look like:
>   

Maybe you want the Subversion log.  It is machine readable; just use 
Subversion to read it.  (Something nice would be R-level access to the 
Subversion API.) You can be very specific about which files you want to 
read about, or just read the whole thing on developer.r-project.org.

Duncan Murdoch
>  > track("XXX", action = "debug", message = "my comment", file = 
> "/somewhere/CHANGELOG")
>
> The file NEWS would not change and should be kept to present the same 
> information in a human-readable format.
>
> Also, a function that lists all functions used in a script or a package 
> (Romain François is working in this direction with svTools package), 
> plus a function to plot one or several "changes" objects as returned by 
> changes() on a time axis or "version axis" would be welcome additions to 
> further track and plot evolution of R, or of R packages for a group of 
> functions of interest. Finally, a function to easily record the 
> dependences used and their versions in a script would complete the set 
> of tools.
>
> These 4-5 functions are not difficult to write (although I suspect that 
> this simplistic proposal would become more complex if one consider to 
> interact with subversion, to separate development and release versions, 
> ...). But to be really useful, they should be better designed and 
> proposed by the R core team, and included in the official specifications 
> for writing package. May I suggest to think about such a change for R 
> version 3.0?
>
> Things get more complicated for verifying CHANGELOG in R CMD check. At 
> least, one could check actions like:
> - object or function addition, deprecation or disappearance,
> - argument changes in functions, slot changes in objects,
> - function refactoring (change in the code from previous version)
> but only if we provide also the previous version of a package to R CMD 
> check.
>
> I would be happy to contribute, but the concept must certainly be 
> further discussed and enhanced (here?), and then, accepted by the R core 
> team before going any further.
>
> All the best,
>
> Philippe Grosjean
>