Continuous integration - CI
Vignette Author
2019-03-22
continuous-integration.RmdIntroduction to CI
Continuous integration - or CI - is a development practice where developers push and merge their code modifications as often as possible to a shared branch in a remote repository (i.e. Github.com repository), where automatic tests and build are made using external tools. In practice, it means that when a developer made changes on its branch and request a pull to the master branch, the code is exported from Github.com automatically to another server that test the package’s integrity by running the testthat tests in the package along with the CRAN tests (R CMD check).
Put into simple terms, the CRAN checks and unit tests of your package and the build of its website can be done online each time a push has been done to github.com. This is called continuous integration, or CI.
The main goal of this practice is to reduce the risk of progressive divergence between developers code to reduce at the minimum the time spent on integrating the code to the main project. It helps find conflicts and bugs very early in the development, and makes everybody save time on the end.
Badges
Before going further in the CI explanations, let’s talk about badges. Badges, or shields allows a quick look to the status of a repository at a given moment. For example there is a badge that shows which licence the repository uses. These badges can be found on shields.io or from other websites. For example, the project status is an interesting information for new users:
.
The badges are often integrated in the head of the README file, and are used as a summary of your repository status. The CI external tools make an extensive use of the badges to communicate their results.
CI
Travis CI and AppVeyor are two well-known external tools for CI. The first one is used to test the package for Linux-based systems, and the second one for windows. To set up automatic tests online, you need to link the repository to these services (only for project admins), and to add a configuration file for each one.
First, add the configuration files to the repository:
The first command creates a .travis.yml file in the project root, and the second one the appveyor.yml. These files are configuration files for each service. Each command execution gives you a link that you can copy and paste in your README.md file such as on this README. This link will add a badge that indicates the status of the build on each service. For example here is the badge comming from TRAVIS-CI for the sandbox package:
.
If you have the rights, then you can go to the services to set up the CI as described below.
Code coverage
The code coverage is a statistic that express how many functions are tested in a project. This is very useful to control the code quality of a repository at a glance. To set up code coverage, you can use the service from codecov.io, and set it up like the CIs.
First, install the covr package:
And set the configuration file:
And then, you’ll have to add a line of code on the Travis-CI configuration file to make Travis-CI build the report of coverage. Please modify your .travis.yml file such as:
# R for travis: see documentation at https://docs.travis-ci.com/user/languages/r
language: R
sudo: false
cache: packages
r_github_packages:
- r-lib/covr
after_success:
- Rscript -e 'covr::codecov()'You can add the badge to your README, such as:
.
Finally, go to codecov.io, log in with your github account, and activate the repository.
Licence
As stated in the vignette Make a package, the easier way to set a licence to your project is by using the functions from usethis, e.g.:
It will create the licence file, add it to the DESCRIPTION file of your package, and add it to .Rbuildignore.
You can also add a licence badge to your project so people can quickly see which one it is using. shields.io is a good platform to find a badge for your license. For exemple, the GPL-3 license can be added using this code in your markdown file:
Which yield:
