Continuous Integration

Overview

In modern software companies hundreds of people are simultaneously working on the source code of the same product while they develop different features for that product. At the same time those programmers are depending upon software that might be built by other teams within the company, or they may be using software built by other companies or individuals, which in turn is being actively developed and updated. The software development technique of continuous integration was developed to ensure that all of the components in this web of software are working together harmoniously.

R packages are usually not as big in terms of lines of code compared to software like Google’s search engine, however it’s plausible that your package may depend on several other packages which you want to make sure are still working the way you expected them to when you first included them in your code. When it comes to R packages continuous integration means ensuring that your package builds without any errors or warnings, and making sure that all of the tests that you’ve written for you package are passing. Building your R package will protect you against some big errors, but the best way that you can ensure continuous integration will be useful to you is if you build robust and complete tests for every function in your package.

Web services for continuous integration

We’ll discuss various services for continuous integration, most common are GitHub Actions , Travis , CircleCI and AppVeyor. Appveyor though has all environments to test, it is good for testing your package on Windows. All these services are free for R packages that are built in public GitHub repositories. These continuous integration services will run every time you push a new set of commits for your package repository. All these services integrate nicely with GitHub so you can see in GitHub’s pull request pages whether or not your package is building correctly.

Using GitHub Actions

Within the repository, run the commmand

library(usethis)
use_github_actions()

Using Travis

To start using Travis go to https://travis-ci.org and sign in with your GitHub account. Clicking on your name in the upper right hand corner of the site will bring of a list of your public GitHub repositories with a switch next to each repo. If you turn the switch on then the next time you push to that repository Travis will look for a .travis.yml file in the root of the repository, and it will run tests on your package accordingly.

Open up your R console and navigate to your R package repository. Now load the usethis package with library(usethis) and enter use_travis() into your R console. This command will set up a basic .travis.yml for your R package. You can now add, commit, and push your changes to GitHub, which will trigger the first build of your package on Travis. Go back to https://travis-ci.org to watch your package be built and tested at the same time! You may want to make some changes to your .travis.yml file, and you can see all of the options available in this guide.

Once your package has been built for the first time you’ll be able to obtain a badge, which is just a small image generated by Travis which indicates whether you package is building properly and passing all of your tests. You should display this badge in the README.md file of your package’s GitHub repository so that you and others can monitor the build status of your package.

Using Appveyor

You can start using AppVeyor by going to https://www.appveyor.com/ and signing in with your GitHub account. After signing in click on “Projects” in the top navigation bar. If you have any GitHub repositories that use AppVeyor you’ll be able to see them here. To add a new project click “New Project” and find the GitHub repo that corresponds to the R package you’d like to test on Windows. Click “Add” for AppVeyor to start tracking this repo.

Open up your R console and navigate to your R package repository. Now load the usethis package with library(usethis) and enter use_appveyor() into your R console. This command will set up a default appveyor.yml for your R package. You can now add, commit, and push your changes to GitHub, which will trigger the first build of your package on AppVeyor. Go back to https://www.appveyor.com/ to see the result of the build. You may want to make some changes to your appveyor.yml file, and you can see all of the options available in the r-appveyor guide which is maintained by Kirill Muller. Like Travis, AppVeyor also generates badges that you should add to the README.md file of your package’s GitHub repository.

Using CircleCI

TravisCI works great, is popular among data scientists & developers, has built-in community support for R and is free only for open source projects. However using it for private repositories is not free. CircleCI v2.0 is thus a great alternative with a free plan that also includes private repositories. You can start using CircleCI by going to https://circleci.com/ and signing in with your GitHub or Bitbucket account. To add a project, find the bar on left and click Add Project after which you will find your repositories including the private ones. Then Set Up Project for the repo you want to continuously integrate.

To use this CI service for your R package,

  • Create a folder named .circleci in the package and add a file config.yml inside

  • Populate the config.yml. See here

  • Start building once you set up the project

Other easy option is to execute

library(usethis)
use_circleci()

Like Travis and AppVeyor, CircleCI also generates badges that you should add to the README.md file of your package’s GitHub/Bitbucket repository.

See an example here.

Summary

Continuous integration is a strategy for testing new features and changes to your package as often as possible. Web services like GitHub Actions and AppVeyor make it possible to re-test your code on different platforms after every git push. Using continuous integration makes it easy for you and for others to simultaneously work on building an R package without breaking package features by mistake.