For a general introduction to ICES GitHub, see https://github.com/ices-tools-dev/doc.
This document provides a basic overview of how we might organize R package development at ICES. The intended audience is R programmers within the ICES community, who might contribute functions to R packages maintained by the ICES Secretariat.
The overview is organized as a quick walk through the inner structure of the icesAdvice package version 1.1-0 (CRAN version from 18 May 2016). Using this minimal example, the essential topics are visited by going through one file at a time.
CRAN is the official R archive for distributing packages to the global user community. Packages on CRAN are the latest official release, guaranteed to pass integrity tests of code and documentation.
GitHub is a code repository, where development versions of packages reside. Several people can have write-access and work together on development and maintenance. ICES provides two GitHub areas for R packages:
github.com/ices-tools-prod contains packages that are operational and maintained by the ICES Secretariat
github.com/ices-tools-dev contains everything else (operational packages maintained by scientists outside the Secretariat, experimental projects, etc.)
The latest official release of the package is on CRAN:
https://cran.r-project.org/package=icesAdvice
The development of the package takes place on GitHub:
https://github.com/ices-tools-prod/icesAdvice
Previous releases are available on CRAN and GitHub, including version 1.1-0 that the following commentary is based on:
https://cran.r-project.org/src/contrib/Archive/icesAdvice/
https://github.com/ices-tools-prod/icesAdvice/releases
https://github.com/ices-tools-prod/icesAdvice/tree/1.1-0
The backbone of an R package: version number, authors, required packages, license, etc.
List of functions that the package provides for users, as well as functions required from other packages. (This file is automatically generated by Roxygen.)
Source code and documentation for the Bpa function. Note how the Roxygen comments end up in man/Bpa.Rd and NAMESPACE.
Package help page: annotated list of functions, where related functions are grouped together. This gives users a much better overview of the package than a dry alphabetical list of functions. To view the package help page, the user simply types ?icesAdvice in the R console.
A link to this main page is found in the See Also section of all help pages in the package. References, such as publications and websites, can describe how the package is related to the world outside of R. Note how the Roxygen comments end up in icesAdvice-package.Rd.
The first two points are important: to build and check, and to document user-visible changes.
When developers make changes to the package, they should check if the package builds without errors or warnings, before committing changes to the central repository. This can be done in the command line by running
R CMD build icesAdvice
R CMD check --as-cran icesAdvice_1.1-0.tar.gzor inside an R session using the devtools package,
library(devtools)
check()along with related devtools functions such as document(), install(), and load_all().
The same test is used by Travis and CRAN to test whether the package is broken.
Whenever user-visible functionality is added/modified, this should be documented in the NEWS file. Keeping track of new functions/arguments/behavior is very useful for package developers and users.
The tradition for R packages is to use version numbers that consist of three counters, for example 1.2-3. It’s practical to have the three counters indicate the nature of changes between releases:
The first counter (major) is incremented when existing user scripts will not give the same output as before. Breaking backward compatibility with a major release can be inconvenient for users, but is sometimes done to adopt an improved overall design.
The second counter (minor) means new functions, new arguments, or the like. A minor release suggests that it’s worthwhile for the user to read about the new functionality.
The third counter (patch) is used for other improvements. A patch release may introduce bug fixes, improved documentation, etc.
The package version number is mainly referring to formal releases, and does not have to be changed during incremental development. At the time of release, the list of changes in the NEWS file is reviewed to determine the appropriate version number.
The number of required packages should be kept at an absolute minimum. This will make the package more reliable and easier to maintain. Furthermore, many users will appreciate if the package can be used without installing additional packages.
A key difference between personal R scripts and a general R package is that scripts tend to require many packages, but R packages should ideally require only the core R packages, like base, graphics, and stats.
It is fine for developers to use dependency-intensive tools like devtools, knitr, rmarkdown, and roxygen2 for developing packages. The end user does not require these tools to install and use the package.
R programmers work in a variety of development environments: Linux/Windows, Emacs/RStudio, etc. When collaborating with others in package development and maintenance, files or pathways that are specific to one development environment should be avoided.
Adding a new function to an existing ICES R package typically involves modifying more than one file:
myfunction.Rdefining and documenting the function.otherfunctions.Radding cross references (See Also) from other related help pages.ices*-package.Rdescribing where the function fits logically with the rest of the package.NEWSadding the function to a news entry, corresponding to a version number and date.DESCRIPTIONupdating the version number and date.
R pages have several sections informing the user how the function can be used.
Title is the main heading of an R help page. It should use only a few words, including words from the function name itself, to describe some computation or action. Use title case (most words capitalized).
Description should be short, extending the title into a proper sentence or two.
Arguments entries start in lowercase and end with a period.
Details can be used to elaborate on specific function arguments. This allows for relatively brief entries in the arguments section.
Notes can be used for all further commentary.
This division is efficient for the reader skimming through the help page, since the Details section appears right after the arguments, and the Notes section right after the returned value.
There is no need to enforce some ICES style of R code appearance when it comes to indentation, spaces between characters, maximum length of lines, naming of objects, etc. It is nevertheless helpful to have a consistent style within a given file. The easiest way to achieve this is polite coding:
When modifying an existing file, follow (exactly) the style found within that file.
When creating a new file, use a consistent style within that file.
This means that within a given project (e.g., a package) several styles may coexist, but each file uses a consistent style. Among the common characteristics of good programming styles are that trailing spaces should be avoided, and at the very end of a text file the last character should be a newline.
New user-visible functionality should be documented, both in R help pages and as entries in the NEWS file. To get an overview of functionality that has been added since the last release, it may be useful to view the commit log entries:
git log 1.0-0..HEADAll user functions should have R help pages that cross-reference related pages, and also have an entry in the package help page.
After reviewing the news entries, the date and version number can be finalized in the DESCRIPTION and NEWS files.
In the case of a CRAN release, the submission form can be found at https://cran.r-project.org/submit.html along with instructions.
This can also be done inside an R session using the release() function in the devtools package.
The TAF package maintenance page (https://ices-taf-dev.github.io/r.html) provides a compact overview of the release history of many ICES packages (icesAdvice, icesDatras, icesSAG, icesSD, icesTAF, icesVocab).
To update this page, add a line with the following information: version number, date in description file, date of tar.gz file on CRAN, size of tar.gz file on CRAN, GitHub SHA code, and new functions introduced in this release.
R Core Team. Writing R extensions. Vienna: R Foundation for Statistical Computing. Available at:
https://cran.r-project.org/doc/manuals/r-release/R-exts.html and
https://cran.r-project.org/doc/manuals/r-release/R-exts.pdfWickham, H. 2015. R packages. Sebastopol: O’Reilly. Available at:
http://r-pkgs.had.co.nz
Chacon, S. and B. Straub. 2014. Pro Git, 2nd ed. New York: Apress. Available at:
https://git-scm.com/book/en/v2ESS Developers. Emacs Speaks Statistics. User manual. Available at:
http://ess.r-project.org/Manual/ess.html and
http://ess.r-project.org/ess.pdfRStudio. RStudio cheat sheets: RStudio IDE, devtools, R Markdown. User manuals. Available at:
https://www.rstudio.com/resources/cheatsheets/Wickham, H. Introduction to roxygen2. R package vignette. Available at:
https://cran.r-project.org/web/packages/roxygen2/vignettes/roxygen2.html