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
______________________________________________
R-help@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-help
PLEASE do read the posting guide http://www.R-project.org/posting-guide.html
and provide commented, minimal, self-contained, reproducible code.
