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

[Duncan Murdoch]

On 4/17/2009 9:16 AM, Philippe Grosjean wrote:
> Duncan Murdoch wrote:
>> On 4/17/2009 7:48 AM, ronggui wrote:
>>> 2009/4/17 Duncan Murdoch <murdoch at stats.uwo.ca>:
>> [...]
>> 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.
> 
> Only a few packages on CRAN use subversion and/or make it accessible to 
> others.

Sorry, I missed the point that you were asking package writers to do 
this.  I think that's pretty much impossible.  You might be able to 
convince R Core to adopt documentation standards, but you will never be 
able to get package writers to do so.

For example:  the R Extensions manual has been recommending the use of a 
package man page since 2005, but very few packages bother.  If we invent 
a new format for a news/changelog file, it would only punish the careful 
package writers who already maintain such a file, but not in the desired 
format.  The ones who have no such file won't be impacted at all, 
because they'll just ignore it.

Duncan Murdoch


  OK, this is improving with R-Forge. The proposed CHANGELOG
> should not duplicate subversion info. It would only be a collection of 
> major milestones for each function, i.e., a new entry is written in 
> CHANGELOG when changes are done and included in a new version of R or of 
> a package, but individual steps followed to get there from one version 
> to the other would NOT be recorded (use a subversion for that).
> 
>> 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
> 
> It is not uncommon to use R to analyze some particular data, to save the 
> script of the analysis, and to write a paper (or a book) about the 
> results with some electronic supplements (including that script). From 
> that moment on, the analysis is frozen. However, we may expect that 
> other people would be interested to rerun the analysis at a later time, 
> or even, to reuse the script on other data.

The paper should cite R, and the recommended citation format includes 
the R version number.  We do make old versions available, so if someone 
wants to reproduce an old analysis, there's a very good chance they can 
do so.

Now, running the old script in new R may well be difficult, as you say. 
   The documentation you are suggesting would make it less difficult. 
But I don't think the big problem is creating a new format for people to 
use; I think the big problem is getting people to use anything at all.

> Thus, the decision for not providing active support for older versions 
> should go together with the development of tools that would help people 
> to upgrade such an old script when needed. I think the proposed tools 
> fit this goal.

I agree with that, and I'm glad that you've volunteered to work on this.

Duncan Murdoch

> Philippe Grosjean
> 
>> [...]
> 
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel