Write R-specific tutorials for CI

[alistaire47]

Talking with @ataustin, we agreed that when it comes to CI (Travis, Appveyor, Jenkins, etc.), people (myself still included) tend to copy other people's code and treat it as magic incantations they want to work but not touch, because it'll probably break.

There are already tools like usethis::use_travis() to get people started, but it would be really useful to build some R-specific docs for how you can tweak your CI to do useful things (updating a pkgdown site, running R CMD check on multiple versions of R, rebuilding docs with roxygen, ???). Maybe a bookdown site with chapters contributed by anyone with ideas would be a logical format?

I know a little on the subject, but I know at least @jameslamb and @angela-li (1) have done some cool CI stuff.

[ataustin]

🙌 I also wonder what, if any, use the new GitHub actions can be to this end.

[jdblischak]

Some related resources:

• Jim Hester gave a talk on Azure Pipelines and GitHub Actions at this year's rstudio::conf
• I've written some blog posts about using CI services with a focus on R

[jameslamb]

@alistaire47 thanks for the @. Love this idea! I have some examples that I've found useful. I'm hoping to work on #1 , but happy to drop some links on you! Sorry to everyone reading that a lot of these links are to things I've worked on...I'm not trying to self-promote, I promise. These may have my name on them but they're collections of things I learned from a lot of awesome people, including @jsal13 and @GKMAN and one other person I won't tag because he's on his honeymoon right now 😀

In general, I really really like the pattern of pushing CI logic into scripts in a folder like .ci/, and then having .appveyor.yml, .travis.yml, Jenkinsfile, etc. only be responsible for calling those scripts. I have lived that life of "managing dozens of lines of bash in YAML lists" and it is not one I recommend!

Here are a few such scripts that I've found valuable.

• using covr to run your tests and failing in CI if coverage drops below some threshold
  • I think this is better than just using R CMD CHECK to run the tests. You can get codecov, coveralls etc. to do something similar, but using a little script like this one means you don't need to bring in another integration and can easily test locally
• installing R on any linux VM without relying on provider-specific images like language:r in Travis
  • using language: r on Travis is a great way for projects to get started very fast with Travis, and I'm grateful to everyone who works to maintain it. But if you want more certainty that your jobs will run day to day, and you don't want to wait for things like the fixes rolled out after devtools 2.0.0, this script works pretty well! It also is then easy to pick up and re-use in a docker container, or a random virtual machine from some other CI provider.
• linting all R code in a project (not just package code) with lintr
  • I LOVE the lintr projects, but personally disagree with Jim's guidance on how to use lintr in CI.
  • I like to do something like the script linked here, because it can be used to test ALL R code in a project and doesn't rely on the package structure the way lint_package() does.
  • I usually have a couple other R scripts lying around that are not package code, so I've found this useful. I also like to use it in projects that aren't R packages at all
• building pkgdown site (this + this)
  • these were contributed to a project I worked on by @BruceZhaoR, who could comment more on them
  • honestly I'm still not sure about the best way to manage hosting pkgdown docs. I would love to work on an Rmarkdown converter for Sphinx so the R community could take advantages of readthedocs the way the Python community does
  • I think @jayqi and @bburns632 have good experience with that and maybe some opinions

[eddelbuettel]

I still think there is value in breaking it down into small and basic operations. When Jim Hester, Craig Citro, and I wrote the first version of r-travis it was all somewhat contingent on Travis CI's ruby framework. I preferred to get more plain shell script behavior out to not be beholden to a framework.

So these days I mostly build simple custom Docker containers based on Rocker and plug those in. I am still mostly with Travis, but by being based on Docker it should move easily to to Azure, GH Actions, GitLab, ... all of which can take Docker.

[jayqi]

honestly I'm still not sure about the best way to manage hosting pkgdown docs. I would love to work on an Rmarkdown converter for Sphinx so the R community could take advantages of readthedocs the way the Python community does

I don't have any experience making Sphinx docs on my own and don't know how much control there is, but FWIW but I find pkgdown sites way easier to navigate than most Python packages' Sphinx docs.

[alistaire47]

FWIW but I find pkgdown sites way easier to navigate than most Python packages' Sphinx docs.

+1; I think the consistent structure of pkgdown plays a big role in its effectiveness.

I do think there's room to make it easier to nest pkgdown sites inside of larger sites, though. ROpenSci has an approach (as does updoc, for that matter), but navigating back and forth is pretty clunky; it'd be much nicer to have clearer top-level nav regardless of where you are.