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

[Philippe Grosjean]

OK, then, I catch the practical point of view that is: nobody will use 
it and we cannot force people to use it. So, it means that we should 
think about tools to *automatically* generate a limited set of entries 
in the CHANGELOG.

Something like new functions appearing in a package, functions being 
deprecated, change in the function's interface (arguments definition), 
change in the dependence of packages could be tracked automatically if 
the previous version of the package is available. This should be the 
case for packages on CRAN and Bioconductor, after first release. So, 
those "changelog" tools should be best deployed at this level.

Further details could be provided directly inside the code, using simple 
formatting, and proposed as a purely optional feature. I think at 
something like:

foo <- function (x, mynewarg) {
     #CHANGE# arg:mynewarg:A new argument in my function
     ...
}

or

bar <- function (y) {
     #CHANGE# fun:Short details about this new function
}

Those #CHANGE# tags would be located by the function that automatically 
builds the CHANGELOG and corresponding details would be added. If I 
define a new function without documenting change, the CHANGELOG would 
still get an entry for the addition of this function, but just without 
comment.

After all, these #CHANGE# tags could be useful in the code too! So, that 
would encourage programmers to use them,... and it is not that far away 
from current practices for documenting code.

I am open to any other proposition for the syntax of those tags, of course.
Best,

Philippe Grosjean

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