[R] Proposal: Package update log
diggsb at ohsu.edu
Tue Oct 2 22:07:52 CEST 2012
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.).
> 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
More information about the R-help