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. 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. 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/
There is already support in the packaging system for a NEWS file which can be accessed within R using the 'news' function. What would the changelog that you are proposing contribute or contain beyond what the NEWS file already does? Creating and updating NEWS is not mandatory, but is encouraged. Making the update of NEWS mandatory would probably not change anything for the authors already using it, for those that don't it may cause the author to be less likely to share or update their package rather than bother with logging the updates (though whether that is a bad thing or a good thing is a whole different discussion). How would you mandate the update log? just requiring a change could result in a lazy author adding a single line of gibberish or a statement like "updated on this date". To enforce something more meaningful would require some form of moderation and place additional burden where there is already a lot of volunteer work happening. If a package is on R-forge (or other similar locations) then you can get a details view of the changes between versions. Packages on CRAN have previous versions available and there are tools that will let you compare the differences in detail. On Tue, Oct 2, 2012 at 11:01 AM, Starkweather, Jonathan <Jonathan.Starkweather at unt.edu> 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. > > 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. > > 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/ > > ______________________________________________ > R-help at 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.-- Gregory (Greg) L. Snow Ph.D. 538280 at gmail.com
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