[Rd] suggestion for R >= 3.0: computer-readable CHANGELOG
murdoch at stats.uwo.ca
Fri Apr 17 12:38:05 CEST 2009
Philippe Grosjean wrote:
> 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
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.
> > track("XXX", action = "debug", message = "my comment", file =
> 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
> 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
More information about the R-devel