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

[Max Kuhn]

On Fri, Apr 17, 2009 at 2:09 PM, Philippe Grosjean
<phgrosjean at sciviews.org> wrote:
> 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.

Of course this tells you what was changed but not why. I'd like to
know a more top-level "what" and, more importantly, "why".

It would also pick up code formatting changes.

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

My code is ugly enough without the extra help, and this would take
things to a new level of ugly.

Sorry to pick on this, but it is also optional and suffers from the
same issues as you mentioned above.

-- 

Max