3.10 Continuous Integration

The objectives of this section are:

• Create an R package that is tested and deployed on Travis
• Create an R package that is tested and deployed on Appveyor

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.

3.10.1 Web Services for Continuous Integration

We’ll discuss two services for continuous integration: the first is Travis which will test your package on Linux, and then there’s AppVeyor which will test your package on Windows. Both of 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. Both services integrate nicely with GitHub so you can see in GitHub’s pull request pages whether or not your package is building correctly.

3.10.1.1 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 up 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 devtools package with library(devtools) 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.

3.10.1.2 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 devtools package with library(devtools) 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 bud 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 Müller. Like Travis, AppVeyor also generates badges that you should add to the README.md file of your package’s GitHub repository.

3.10.2 Summary

Continuous integration is a strategy for testing new features and changes to your package as often as possible. Web services like Travis 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.