CI Guide

General

The following guide describes the CI setup that is used in mlr3 and all of its extension packages. We use tic to simplify CI tasks. To get a basic overview of tic, read its vignettes. Especially the one listing its advantages compared to using Travis without tic support.

Enabling CI for an extension package

Note: To do this, you need to have administration rights for the "mlr-org" organization.

1. Run travis::use_tic(). During the process, browser pages will open up, ensuring that all permissions are set correctly and all apps are authorized. Also a Personal Access Token (PAT) will be created on GitHub and stored as an encrypted variable on Travis. This avoids hitting rate limitations when accessing the GitHub API. The access token does not need any additional rights.
2. Copy the .travis.yml file from mlr3 and paste its content into the respective file in your package that was just created in the previous step.
3. Do the same for the tic.R file.

Now you should have a working setup the does the following:

1. Installs all required dependencies based on your DESCRIPTION
2. Runs R CMD check on the package (scripts fails if errors are found)
3. Builds a pkgdown site of the package which is served from the docs/ directory of the master branch
4. Runs covr::codecov() to calculate the code coverage of the package

Doc files (man/, NAMESPACE and DESCRIPTIPON) are created and auto-deployed during the CI run.

Enabling the pkgdown site

Now that the pkgdown site if the package was built by Travis, you need to enable it. We have our own domain for the mlr-org (https://mlr-org.com) and use subdomains for all our packages to host their pkgdown sites.

1. Go to "Settings" in the repository and under "Github Pages" set "Source" to "master branch docs/ folder".
2. Click "Save"
3. Scroll down again to "Github pages". Now there is a field "Custom domain". Enter the following: <pkg name>.mlr-org.com.
4. Our DNS server is managed via Netlify. Ping one of the admins (@larskotthof, @berndbischl, @mllg, @jakob-r, @pat-s) and ask them to add your subdomain to the DNS configuration (when logged in, the DNS configuration can be found under "Settings - Domain Management". Then click on the three dots of "mlr-org.com" and select "Go to DNS Panel").
5. Add the subdomain url to the "website" field in the main repo window (at the top of the repo, below the menu bar listing "code", "issues" etc.).
6. Don't worry if the site is not instantly accessible over https. It takes some time until the DNS server has picked up the change. However, the site should already be available via http.
7. Add ^docs$ and ^pkgdown$ to .Rbuildignore.
8. Copy man/figures/logo_navbar.png to your repo.

Almost done. To have a consistent pkgdown theme across all packages, please also copy the pkgdown folder to your repo. Update the pkgdown/_pkgdown.yml file so that it matches your repo.

• Change URL field
• Update "navbar" entries

ToDO: Provide a package that can be used as the default "template". Advantage: Changes there will be ported to all subsequent packages using the template. See https://github.com/tidyverse/tidytemplate.

Preview of docs in Pull Requests

Whenever a Pull Request changes content in a vignette, the changes can be preview in a fully-rendered pkgdown site. To enable this, follow these steps:

1. Go to Netlify and click "Create new site from git"
2. Choose the repo and accept all defaults.
3. Go to "Settings - General - Site Details" and change the site name to <pkgname>-preview.
4. Go to "Build & Deploy - Continuous Deployment" and set "Build command = true" and "Publish directory = docs".
5. Go to "Build & Deploy - Deploy Notifications" and remove all outgoing notifications. Add the following ones by clicking on "Add notification - Github commit status": "Add deploy notifications to git commits when deploy starts/succeeded/failed".
6. Go to "Build & Deploy - Deploy contexts" and change to "Branch deploys - All".