CI Guide

We use the R package tic to specify actions that should be executed on Travis CI.

tic

Why add another layer on top of Travis?

tic is ci-agnostic, meaning that the same script will also be valid on other CI systems (e.g. Appveyor for Windows).
tic makes the deployment of docs easy and transparent.
tic uses R functions instead of Travis own functions.
tic uses rcmdcheck::rcmdcheck() instead of R CMD CHECK. This enhanced version comes with the major among smaller advantages with the feature of showing the full log of failed tests.

In .travis.yml most calls just refer to specfic tic calls. These tic commands are then specified in tic.R. The organization of tic.R is similar to Travis (and CIs in general): It uses "stages", i.e. different levels of logical layers that are executed in a specific order (e.g. before_install runs before stage install).

tic.R is subdivided into groups by environment variables referring to specific build stages.

mlr3

The .travis.yml file should stay static. Everything is redirected to tic.R.

The pkgdown site is deployed into the gh-pages branch. This is done via the tic macro do_pkgdown(). Option orphan = TRUE means that the whole branch is wiped, storing only the most recent deployment.

R CMD Check is run by macro do_package_checks() . The build should fail for errors and warnings, not for notes.

tic.R

do_package_checks(error_on = "warning")

if (ci_has_env("BUILD_PKGDOWN")) {
  do_pkgdown(orphan = TRUE)
}

Some packages of the mlr3 package family need some additional system libraries or other modifications of tic.R and .travis.yml. These repos therefore do not share the tic.R file mentioned above from the mlr-ci repo but have their own distinct file.

For some packages containing compiled code you need to add argument document = FALSE to the do_pkgdown() macro. This has to do with an issue going back to package pkgbuild that has some issues with compiled code in packages. See tic.R in mlr3survival for an example. The mentioned error looks as follows:

Error in getNativeSymbolInfo(symNames, dll, unlist = FALSE, withRegistrationInfo = TRUE) :
  must pass a package name, â€œDLLInfoâ€� or â€œDllInfoReferenceâ€� object

mlr3book

A run of the build is triggered on each run of a mlr3* repo.

This happens via https://github.com/plume-lib/trigger-travis.

The following needs to be put into tic.R :

get_stage("after_success") %>%
  add_code_step(system('sh inst/trigger-mlr3book.sh'))

Additionally, place the following script in inst/trigger-mlr3book.sh :

echo "TRAVIS_BRANCH=$TRAVIS_BRANCH TRAVIS_PULL_REQUEST=$TRAVIS_PULL_REQUEST"
if [[ ($TRAVIS_BRANCH == master) &&
      ($TRAVIS_PULL_REQUEST == false) ]] ; then
  curl -LO --retry 3 https://raw.github.com/mernst/plume-lib/master/bin/trigger-travis.sh
  sh trigger-travis.sh mlr-org mlr3book $TRAVIS_ACCESS_TOKEN "trigger from $TRAVIS_REPO_SLUG $TRAVIS_COMMIT"
else
  echo "Not triggering a mlr3book deployment"
fi

The TRAVIS_ACCESS_TOKEN of the repo can be queried from the terminal if the travis library is installed locally with travis token from the repo root. If you have it, store as an env variable in the TravisCI repo setting.

Travis debug mode

Get your API token from your profile page at: https://travis-ci.org/profile
Send a POST request to /job/:job_id/debug replacing the TOKEN and JOB_ID values below:

#! /usr/bin/env bash curl -s -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Travis-API-Version: 3" \ -H "Authorization: token " \ -d '{ "quiet": true }' \ https://api.travis-ci.org/job/<JOB_ID>/debug

The Job ID is displayed in the build log after expanding "Build system information".

Head back to the web UI and in the log of your job. There you should see the following lines to connect to the VM:

 Setting up debug tools.
 Preparing debug sessions.
 Use the following SSH command to access the interactive debugging environment:
 ssh [[email protected]](mailto:[email protected])