On 4/17/2009 7:48 AM, ronggui wrote:
2009/4/17 Duncan Murdoch <murd...@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.
It might be helpful, but often new arguments or changed behaviour happen
later, so you'd really need a full change history for the function:
that's what's in the Subversion log, or to some extent, in the NEWS file.
But since we've made an explicit decision not to provide active support
for older versions, it seems rather pointless to devote extra resources
to this. Some new function is only available as of 2.8.0? Why would
you care? You should be using 2.8.1 or 2.9.0 by now. If you're using
2.7.1 you're on your own.
Duncan Murdoch
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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
