[R] Proposal: Package update log

[Brian Diggs]

On 10/2/2012 10:01 AM, Starkweather, Jonathan wrote:
> I'm relatively new to R and would first like to sincerely thank all
> those who contribute to its development. Thank you.
>
> I would humbly like to propose a rule which creates a standard (i.e.,
> strongly encouraged, mandatory, etc.) for authors to include a
> `change log' documenting specific changes for each update made to
> their package(s). The more detailed the description, the better; and
> it would be exceptionally useful if the document were available from
> the R-console (similar to the help function). In other words, I am
> suggesting that the `change log' file be included in the package(s)
> and preferably accessible from the R-console.

Let me just address the "accessible from the R-console" part of this. 
The infrastructure to support this already exists; check out the news() 
function. It does require a structured NEWS file, but will make some 
attempts to figure out the structure (see the documentation).

> I am aware that many packages available on CRAN have a `change log'
> or `news' page. However; not all packages have something like that
> and many which do, are not terribly detailed in conveying what has
> been updated or changed.

More detail is generally nice. However, I'm not sure what CRAN could 
enforce. A simple check that could be automated is that news() for the 
package and the version declared in the DESCRIPTION file returns a 
non-empty result. But I don't know if that would be a net positive 
(adding another burden for package authors vs giving more detail). Those 
authors that care probably already do so; those that don't will just 
have to work around the check without necessarily adding anything useful.

> I am also aware that package authors are not a particularly lazy
> group, sitting around with nothing to do. My proposal would likely
> add a non-significant amount of work to the already very generous
> (and appreciated) work performed by package authors, maintainers,
> etc. I do, however, believe it would be greatly appreciated and
> beneficial to have more detailed update information available from
> the R-console as some of us (users) update packages daily and are
> often left wondering what exactly has been updated.
>
> I did not post this to the R-devel list because I consider this
> proposal more of a documentation issue than a development issue.
> Also, I would like to see some discussion of this proposal from a
> varied pool of stakeholders (e.g., users and not just developers,
> package authors, package maintainers, etc.).
>
>
> Respectfully,
>
> Jon Starkweather, PhD University of North Texas Research and
> Statistical Support http://www.unt.edu/rss/
>


-- 
Brian S. Diggs, PhD
Senior Research Associate, Department of Surgery
Oregon Health & Science University