R devel - Apr 2009 - suggestion for R >= 3.0: computer-readable CHANGELOG

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:

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 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:

 > 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
-- 
..............................................<?}))><........
  ) ) ) ) )
( ( ( ( (    Prof. Philippe Grosjean
  ) ) ) ) )
( ( ( ( (    Numerical Ecology of Aquatic Systems
  ) ) ) ) )   Mons-Hainaut University, Belgium
( ( ( ( (
..............................................................

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
>

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.
Hi,

I agree with the usefulness of having this available, but there is 
absolutely no way people are going to log such information in a 
systematic fashion. In the other hand, if you have version 1 and version 
2 of some package, then why not do some programmatic investigation of 
the code to get (some of) these answers.

This looks like CRANberries, but working at the object level instead of 
working at the file level, but then you can imagine to parse the 
package, dump each function/object/class in its own file, and cranberry 
that. Is CRANberry an R package ?

Romain
> 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:
>
> 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 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:
>
> > 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

-- 
Romain Francois
Independent R Consultant
+33(0) 6 28 91 30 30
http://romainfrancois.blog.free.fr