From mxkuhn at gmail.com  Mon Apr 20 19:25:46 2009
From: mxkuhn at gmail.com (Max Kuhn)
Date: Mon, 20 Apr 2009 13:25:46 -0400
Subject: [Rd] suggestion for R >= 3.0: computer-readable CHANGELOG
In-Reply-To: <49E8C5C4.6030304@sciviews.org>
References: <49E82D9C.9090402@sciviews.org> <49E85C0D.6040809@stats.uwo.ca>
	<49E87A59.2010003@life.ku.dk> <49E87E85.4050700@stats.uwo.ca>
	<18920.36404.547796.504974@ron.nulle.part>
	<49E893F1.9000007@stats.uwo.ca> <49E8C5C4.6030304@sciviews.org>
Message-ID: <6731304c0904201025m3e8a66a8ue9dddab6ba29253b@mail.gmail.com>

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



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