README.Rmd

---
title: "R Package Development at ICES"
output:
  html_vignette:
    toc: true
    toc_depth: 2
    number_sections: true
    mathjax: null
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{R Package Development at ICES}
  \usepackage[utf8]{inputenc}
---

<br>

# Introduction

## ICES GitHub

For a general introduction to ICES GitHub, see
https://github.com/ices-tools-dev/doc.

## This document

### A guided tour

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](https://github.com/ices-tools-prod/icesAdvice/tree/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.

### References

The overview concludes with a list of free books and manuals related to R
package development, where topics are covered in greater depth.

## Where ICES packages live

### CRAN

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

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 icesAdvice package

### On CRAN and GitHub

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

### Roxygen

The icesAdvice package is developed using Roxygen. This means that the
`NAMESPACE` and `*.Rd` documentation files are produced automatically from the
main `*.R` source files.

<br><br>

# Root files

## .Rbuildignore

List of files that are not a part of the R package itself.

## .travis.yml

Configuration file that enables automatic Travis build tests.

## DESCRIPTION

The backbone of an R package: version number, authors, required packages,
license, etc.

## NAMESPACE

List of functions that the package provides for users, as well as functions
required from other packages. (This file is automatically generated by Roxygen.)

## NEWS

Version history and user-visible changes in each release.

## README.md

GitHub front page, including Travis and CRAN badges.

<br><br>

# R files

## Bpa.R

Source code and documentation for the `Bpa` function. Note how the Roxygen
comments end up in `man/Bpa.Rd` and `NAMESPACE`.

## Fpa.R, sigmaCI.R, sigmaPA.R

Similar to the `Bpa.R` file.

## icesAdvice-package.R

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`.

<br><br>

# Development guidelines

The first two points are important: to build and check, and to document
user-visible changes.

## Build and check

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.gz
```

or 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.

## Document user-visible changes

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.

## Version number

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:

1. 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.

2. 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.

3. 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.

## Dependencies

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

Adding a new function to an existing ICES R package typically involves modifying
more than one file:

1. `myfunction.R` defining and documenting the function.

2. `otherfunctions.R` adding cross references (See Also) from other related help
   pages.

3. `ices*-package.R` describing where the function fits logically with the rest
   of the package.

4. `NEWS` adding the function to a news entry, corresponding to a version number
   and date.

5. `DESCRIPTION` updating the version number and date.

## Help page sections

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.

## Style

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.

<br><br>

# Release procedure

## Pre-release

### Documentation

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..HEAD
```

All 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.

### Repository maintenance

Once the package has been built and checked, one can merge the most recent
changes into the stable branch, for example:

```
git checkout master
git merge develop
```

This is also a good time to tag the release:

```
git tag 1.1-0
```

## Submit

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.

## Post-release

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.

<br><br>

# References

## Writing R packages

- 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.pdf

- Wickham, H. 2015. ***R packages***. Sebastopol: O'Reilly. Available at:\
  http://r-pkgs.had.co.nz

## Development tools

- Chacon, S. and B. Straub. 2014. ***Pro Git***, 2nd ed. New York: Apress.
  Available at:\
  https://git-scm.com/book/en/v2

- ESS Developers. ***Emacs Speaks Statistics***. User manual. Available at:\
  http://ess.r-project.org/Manual/ess.html and\
  http://ess.r-project.org/ess.pdf

- RStudio. ***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