Enhance "Get started" and other vignettes

[krlmlr]

@pat-s: I like the way the new vignettes are organized, they are good read.
The relevant information is presented concisely, with good cross-references.
Especially the automatic linking from code chunks to function documentation done by pkgdown makes the vignettes easy to navigate.

The vignettes could use some graphics, screenshots, and code blocks/listings.
They could be a bit more self-contained, too -- e.g. show an example instead of a bare link pointing to additional information.
The examples are important to give the user an early understanding if following the link is worthwhile.

README

• Link to CI intro (mahugh.com), brief before-after comparison (with image from ) and link to "advantages" website
• "Example projects" is anchored link, just mention when introducing the "Get started" vignette?
• Footer on website?

Get started

• Prerequisites: Second paragraph lengthy and diluted; instead briefly summarize tic's advantages in a comprehensive bullet list (one item per benefit, like in the intro of the "Advantages" vignette), add a before-after like in README, and link to tic-advantages.html
• Initialization: Again, can be a bit longer, showing the call and the expected output in a full-width chunk. Mention that browser pages will open and app authorization is required, and a PAT needs to be created, add screenshots. Explain why this is necessary, especially that PAT creation can't be automated currently.
• Setup
  • Consider renaming section
  • Show and explain example tic.R file (copy template to the package for now, it might stay there for good, or we take the template from usethis later)
  • Don't show example .travis.yml and appveyor.yml files, but point to the "Build lifecycle" article
• Examples
  • In the bullet list, add a brief explanation, e.g. for blogdown: what is blogdown, how is deployment achieved, is there anything special about the example repo, maybe show excerpts from tic.R?
  • The link names should match the repo names
  • figshare publishing doesn't work yet, publishing to Zenodo is work in progress (need to ask Karthik)
  • CTA: share your own nonstandard tic-based solutions?
• What's not covered yet: move to "Advanced"

Advantages

• Title is repeated on rendered website?
• More advantages
  • Easier troubleshooting for local builds (with link); it's mentioned in "CI-Agnostic" but deserves its own section with a working example
  • Less dependent on code we don't control (e.g. r.rb)
• CI-agnostic:
  • tic.R is shorter and easier to parse than .travis.yml
  • AppVeyor is running on Linux since recently
• Easier deployment:
  • Formatting: Indent code blocks and subsequent paragraphs with four spaces to make them indented in the enumeration
  • Shorten, keep first paragraph and link to new "How deployment works" vignette
• R CMD check:
  • Section title unclear
  • rcmdcheck calls into R CMD build and R CMD check (it's not reimplementing it), parses output and returns errors/warnings to the caller as an R object
  • Show excerpts of colored output (use fansi::sgr_to_html() to create HTML)
• Caching:
  • Link to "Build lifecycle"
  • Build deps and check deps are stored in two separate libraries, both are cached. Not sure how to frame it, let's discuss.

tic, travis, and usethis

Pending decision on where setup code is hosted.

Overall, I think a detailed walkthrough (expanding on what will be shown in "Get started") can add some value here.

• Explain all the steps of use_ci() (whether its in tic or usethis) to see how the packages interact

In "Getting Started we only talk on a meta level about the steps of use_ci() and refer to the tic+travis+usethis vignette explaining the steps in detail.

Build lifecycle

• Stages:
  • Article title repeated?
  • Need diagram
  • Mention that .travis.yml is not meant to be edited (include the "DO NOT EDIT" comments in the code)
  • How is a stage accessed from R code? Show an example tic.R file and the output of e.g. get_stage("script") How is a stage accessed from R code and how can a single stage be run?
• Steps:
  • Mention macros (Macros for reoccurring workflows #61, to be implemented)
  • Add steps not mentioned there yet
  • Link steps to help pages, this should happen automatically if you add () after the step names
  • Add more detail to the documentation of the steps

New vignette: How deployment works

Derived from "Easier deployment" in the "Advantages" vignette, and "pkgdown deployment" and "committing single files" in "Advanced usage".

• tic creates public-private key pair
  • public key is added to GitHub repository under the "Deploy keys" section (screenshot), user receives e-mail
  • private key is encoded in base64 and stored in an environment variable, and installed in the ~/.ssh directory during the CI run
• Prefer deployment via public-private key pair, because rights are granted to a single repo only and can be automated
  • We do create per-repo PATs anyway, but these have a very restrictive scope just to avoid rate limitation.
  • Need to revisit: perhaps creating a PAT with write permissions is easier if we can make sure that our scripts never leak the PAT?

Advanced usage

• pkgdown and Committing single files:
  • Move to "How deployment works"
• Running stages conditionally:
  • Mention that tic.R is a file that is processed with source()
  • Steps are added incrementally, existing steps created by macros aren't overwritten
  • R version can be checked with getRversion(), show example where warnings_are_errors depends on the R version used (ignoring warnings for R 3.1)
• Installing packages:
  • s/add_code_step/add_step/
  • Mention that it shouldn't be used in interactive CI runs (ci()$is_interactive())
  • Packages should be installed from DESCRIPTION, install manually only in extraordinary circumstances
• Meta:
  • Remove "Travis" from title
• Running tic locally:
  • Show example output for load_from_file()
  • Important: define steps so that they don't overwrite precious local state. Many steps are careful (double-check this), but custom code may be not
• Entering:
  • Elaborate on opt-in, mention that it needs an e-mail which will be acted upon in less than one day usually.
  • How to get the job ID? Show example in separate code chunk.
  • Link to tmate key bindings documentation, mention similarity with screen and overarching Ctrl + A shortcut (and two or three most important ones, e.g. for scrolling back)
  • Handy functions: Which ones?

Dev info

• "Most steps" -> "Many important steps". Always possible to add a code step, this text is only important for reocurring use if we want to add a new step to tic.
• Point to PR that adds step_install_cran()
• Show source code of the "Hello world" step
• check() doesn't need to be overridden
• prepare() is called by prepare_all_stages()
• Show code of RCMDcheck$prepare
• Start subsection before "If you are unfamiliar"

[pat-s]

brief before-after comparison (with image from )

This is for the README. Which "before-after" comparison do you mean here and which image?

[pat-s]

Footer on website?

I assume you mean to include the ropensci footer? Would be a bit redundant then if we keep the logo in the README.

[pat-s]

Show excerpts of colored output (use fansi::sgr_to_html() to create HTML)

I tried to set it in the knitr header but to get it working we need to render code directly? I cannot really render rcmdcheck() in a tutorial page. How should we get the coloring right here?

old.hooks = fansi::set_knit_hooks(knitr::knit_hooks)
options(crayon.enabled = TRUE)

[pat-s]

Build deps and check deps are stored in two separate libraries, both are cached. Not sure how to frame it, let's discuss.

Here's what I wrote:

tic uses two distinct R libraries for caching: One for the dependencies that are used for checking the R package and another R package library for all other dependencies (e.g. for packages that are used during the "deploy" stage).
The reason for that is that sometimes dependencies for specific stages (e.g. "the deploy" stage) may cause errors when checking the R package because these contain breaking changes which the package is not able to deal with (e.g. if the Github version of a package is installed).
You do not need to worry about this in practice - both will be cached and handled in the background for you!

[pat-s]

How is a stage accessed from R code? Show an example tic.R file and the output of e.g. get_stage("script")

I would not again show the rcmdcheck output of the script stage here as we already show this in the rcmdcheck section in the "advantage" vignette.

Instead I combined the question how a stage is accessed from R code with how to access a single stage.

[pat-s]

Add more detail to the documentation of the steps

I would keep it concise and refer to the detailed help page of each step.

[pat-s]

Important: define steps so that they don't overwrite precious local state. Many steps are careful (double-check this), but custom code may be not

I cannot think of a good example here. Which state might be so precious and at the same time "easily" overwritten by a user by accident?

[krlmlr]

• README: I restructured it (in your branch), works for me now.

• Footer looks good on website now

• Let's think about coloring later (Add more color to the vignettes #91)

[krlmlr]

Closed in #80.