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

[Duncan Murdoch]

On 4/17/2009 10:12 AM, Dirk Eddelbuettel wrote:
> On 17 April 2009 at 09:05, Duncan Murdoch wrote:
> | That would be a waste of time.  People don't use the package 
> | documentation schemes that are in place; why would they use a new one?
>  
> Because of scattered documentation and lack of best practices?  Many things
> are possible with R and packages, how many are really done consistently?  I
> think this points to a need for better examples, better docs, and better
> package checking tools.
> 
> I happended to have the same discussion via email last night with Brian
> (CCed) who wanted to see NEWS / Changes in my CRANberries RSS feed for CRAN.
> I suggested pretty much what Philippe suggested in the first post in this
> thread --- with one addition.  I think we need a test in R CMD check that
> emits a warning if there is no inst/NEWS or inst/Changes or inst/Changelog.

I think it would have to do more than that to be useful.  It would need 
to warn about a lack of an entry for the current version.  Otherwise 
package.skeleton would create a blank one, and that would satisfy the 
check from then on.

To recognize an entry for the current version, it would need a standard 
format.  But then, unless whoever put together the format was willing to 
do updates to the hundreds of existing files out there, there would be a 
lot of resistance to any particular change.  I'd expect to hear messages 
like "Why not just use the format I've been using all along?  Why should 
I change to suit your design?  I don't have time to go through the 
dozens of packages that I maintain and update them." --- and that's from 
the careful developers who already have a changelog of some sort.  The 
majority of package writers who don't have one would just complain that 
you were wasting their time.


> Your reminder of the parseable NEWS file was timely.  I would suggest to have
> both NEWS (for 'big' events) and Changes (for 'smaller', incremental
> changes).   

I'd say that's too elaborate:  I want to write everything in one place. 
  We could use tags like NEWS uses to identify big versus small events, 
but even that is more elaborate than I'd expect most package writers to 
follow.

   I'd be happy to help code an additional parser Changes and/or
> some checks for R CMD check if a consensus emerges that this is doable.  

Could you take a look at CRAN and Bioconductor, and count how many 
packages already have a news/changelog file, and how hard it would be to 
convert them to a standard format?

Duncan Murdoch