Prerequisites

Continuous Integration (CI) is a huge field in software development. There are a lot of resources out there that try to explain what it can do and why you need it (and usually why their particular company/service does it best). If you are just getting started with software development or git based project work you might think:

“Ah I don’t need all of this overhead, I am fine doing X and Y manually for this project. The overhead learning this next additional”tool” is not worth it.

Reading all vignettes of this package will help you understand what {tic} does to simplify all of that specifically for the R language.

However, there is a lot of advanced information in these vignettes which might be a bit overwhelming at first if you are just getting started. Therefore we will explain a few of the most important terms first to give you a kickstart:

Initialization/Setup

The easiest way to use {tic} for CI services is to call tic::use_tic(). This will initialize a setup wizard which will guide you through all possibilities of the offered CI providers by {tic}.

Several yes/no questions need to be answered. Based on the replies we’ll select specific templates.

Besides the question which CI system you want to use, you’ll be asked if you want to

• Deploy from builds to GitHub (e.g. if you are building a {pkgdown} site)

• Test your package on multiple R versions

Last, we’ll add a tic.R file to the project root.

After this, your project is ready for continuous integration. The next push to GitHub will create a build on Circle CI. See the Troubleshooting section in case anything doesn’t work as expected.

tic::use_tic()

## Circle CI
circle::use_circle_deploy() # (optional for deployment)
tic::use_circle_yml(<option here>)

The role of the tic.R file

After having called tic::use_tic() you will find

• .circleci/config.yml
• .github/workflows

and a tic.R file in your repo, depending on the choices you made during use_tic(). The latter will always be present because it will be the main CI config file for all providers from now on. Usually you do not need to touch the YAML files anymore. All build customization is done in tic.R and applies to all providers. For more information about the build lifecycle in general, check the Build lifecycle article.

The basic tic.R template looks as follows:

do_package_checks()

if (ci_on_ghactions()) {
  do_pkgdown()
}

tic.R file has a declarative nature: It should consist of “stages”, “steps” and “macro” functions (see below). These functions will only have an effect when specified in tic.R and should not be used standalone as they will only run in a (simulated) CI run following a certain order.

To run plain R code within the build, encapsulate it within add_code_step(<code>) and add it to a certain build stage. See the Build Lifecycle article for detailed info about how to do this.

list_macros()
#> [1] "do_blogdown"       "do_bookdown"       "do_drat"          
#> [4] "do_package_checks" "do_pkgdown"        "do_readme_rmd"

do_package_checks()

# step_install_deps() in the "install" stage, using the repos argument.
#
# step_rcmdcheck() in the "script" stage, using the warnings_are_errors,
#  notes_are_errors, args, and build_args arguments.
#
# A call to covr::codecov() in the "after_success" stage (only if the codecov flag is set)

if (ci_on_ghactions()) {
  do_pkgdown()
}

# step_install_deps() in the "install" stage, using the repos argument.
#
# step_setup_ssh() in the "before_deploy" to setup the upcoming deployment (if deploy is set),
#
# step_setup_push_deploy() in the "before_deploy" stage (if deploy is set),
#
# step_build_pkgdown() in the "deploy" stage, forwarding all ... arguments.
#
# step_do_push_deploy() in the "deploy" stage.

get_stage("install") %>%
  add_code_step(blogdown::install_hugo())

get_stage("deploy") %>%
  add_code_step(blogdown::build_site()) %>%
  add_step(step_push_deploy())