pkg_ci.Rmd

# Continuous Integration Best Practices {#ci}

```{block, type='summaryblock'}
This chapter summarizes our guidelines about continuous integration after explaining what continuous integration is.

Along with [last chapter](#building), it forms our guidelines for Software Peer Review.
```

## Why use continuous integration (CI)?

All rOpenSci packages must use one form of continuous integration. This ensures that all commits, pull requests and new branches are run through `R CMD check`. rOpenSci packages' continuous integration must also be linked to a code coverage service, indicating how many lines are covered by unit tests.

Both test status and code coverage should be reported via badges in your package README.

## How to use continuous integration?

The `usethis` package offers a few functions for continuous integration setup, see [the documentation](https://usethis.r-lib.org/reference/ci.html).

Details will be provided below for different services.

## Which continuous integration service(s)? {#whichci}

Different continuous integration services will support builds on different operating systems.

R packages should have CI for all platforms when they contain:

* Compiled code

* Java dependencies

* Dependencies on other languages

* Packages with system calls

* Text munging such as getting people's names (in order to find encoding issues).

* Anything with file system / path calls

In case of any doubt regarding the applicability of these criteria to your package, it's better to add CI for all platforms, and most often not too much hassle.

### Travis CI (Linux and Mac OSX)

Travis offers continuous integration for Linux and Mac OSX. Set it up using [`rodev::use_ro_travis()`](https://docs.ropensci.org/rodev/reference/use_ro_travis.html) or `usethis::use_travis()`.

R is now a [natively supported language on Travis-CI](https://blog.travis-ci.com/2015-02-26-test-your-r-applications-on-travis-ci/), making it easier than ever to do continuous integration. See [R Packages](http://marker.to/NEr8Bd) and Julia Silge's [Beginner's Guide to Travis-CI for R](https://juliasilge.com/blog/Beginners-Guide-to-Travis/) for more help.

To customize your build, have a look at [Travis' docs](https://docs.travis-ci.com/user/languages/r/) and at existing Travis config files over rOpenSci's ropensci GitHub organization, e.g. [this one for the `spelling` package](https://github.com/ropensci/spelling/blob/master/.travis.yml).

#### Testing using different versions of R

We require that rOpenSci packages are tested against the latest, previous and development versions of R to ensure both backwards and forwards compatibility with base R. You can enable this on Travis by adding the following to your `.travis.yml` configuration file:

```
r:
  - oldrel
  - release
  - devel
```
Details of how to run tests/checks using different versions of R locally can be found in the R-hub vignette on running [Local Linux checks with Docker](https://r-hub.github.io/rhub/articles/local-debugging.html). 

You can fine tune the deployment of tests with each versions by using a testing matrix. See this [more complex example](https://github.com/r-hub/rhub/blob/master/.travis.yml#L5) of a Travis configuration where pkgdown documentation is built during the release R version testing only.

#### Minimizing build times on Travis

Please use these tips to minimize build time on Travis especially after your package project gets transferred to ropensci Travis account:

* Cache installation of packages. Add `cache: packages` at the beginning of the config file. [Example in the wild](https://github.com/ropensci/crul/blob/ee31c0128fd3279165360ef5ee2a1775ab00c82f/.travis.yml#L3). It'll already be in the config file if you set Travis up using `usethis::use_travis()`.

* [Enable auto-cancellation of builds](https://blog.travis-ci.com/2017-03-22-introducing-auto-cancellation).

* If you have a matrix to test your package on several Travis systems, place any `after_success` or `before_deploy` commands within one single matrix build to avoid them being executed on every matrix build.

### AppVeyor CI (Windows)

For continuous integration on Windows, see [R + AppVeyor](https://github.com/krlmlr/r-appveyor). Set it up using `usethis::use_appveyor()`.

Here are tips to minimize AppVeyor build time:

* Cache installation of packages. [Example in a config file](https://github.com/r-lib/usethis/blob/2c52c06373849d52f78a26c5a0e080f518a2f825/inst/templates/appveyor.yml#L13). It'll already be in the config file if you set AppVeyor CI up using `usethis::use_appveyor()`.

* Enable [rolling builds](https://www.appveyor.com/docs/build-configuration/#rolling-builds).

We no longer transfer AppVeyor projects to ropensci AppVeyor account so after transfer of your repo to rOpenSci's "ropensci" GitHub organization the badge will be `[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/ropensci/pkgname?branch=master&svg=true)](https://ci.appveyor.com/project/individualaccount/pkgname)`.

### Circle CI

[Circle CI](https://circleci.com/) is used, for example, by rOpenSci package [`bomrang`](https://github.com/ropensci/bomrang) as an alternative to Travis CI.

## Test coverage {#coverage}

Continuous integration should also include reporting of test coverage via a testing service such as [Codecov](https://codecov.io/) or [Coveralls](https://coveralls.io/).  See the [README for the **covr** package](https://github.com/jimhester/covr) for instructions, as well
as `usethis::use_coverage()`. 

If you run coverage on several CI services [the results will be merged](https://docs.codecov.io/docs/merging-reports).

## Even more CI: OpenCPU

After transfer to rOpenSci's "ropensci" GitHub organization, each push to the repo will be built on OpenCPU and the person committing will receive a notification email. This is an additional CI service for package authors that allows for R functions in packages to be called remotely via https://ropensci.ocpu.io/ using the [opencpu API](https://www.opencpu.org/api.html#api-json). For more details about this service, consult the OpenCPU [help page](https://www.opencpu.org/help.html) that also indicates where to ask questions.

## Even more CI: rOpenSci docs

After transfer to rOpenSci's "ropensci" GitHub organization, a pkgdown website will be built for your package after each push to the GitHub repo. You can find the status of these builds at `https://dev.ropensci.org/job/package_name`, e.g. [for `magick`](https://dev.ropensci.org/job/magick); and the website at `https://docs.ropensci.org/package_name`, e.g. [for `magick`](https://docs.ropensci.org/magick). The website build will use your pkgdown config file if you have one, except for the styling that will use the [`rotemplate` package](https://docs.ropensci.org/rotemplate/). Please report bugs, questions and feature requests about the central builds at https://github.com/ropensci/docs/ and about the template at https://github.com/ropensci/rotemplate/.