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

[ronggui]

2009/4/17 Duncan Murdoch <murdoch at stats.uwo.ca>:
> 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.

Yes. Yet, as the FreeBSD, I found something like "this function first
appears in R/ foo package  version xxx" in man page helpful. It is not
bad to put such section in the R help page, I think.


> 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
>>
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>



-- 
HUANG Ronggui, Wincent
PhD Candidate
Dept of Public and Social Administration
City University of Hong Kong
Home page: http://asrr.r-forge.r-project.org/rghuang.html