Address ropensci review

.Rbuildignore

@@ -11,3 +11,5 @@
 ^\.circleci/config\.yml$
 ^\.pre-commit-config\.yaml$
 ^\.lintr$
+^tests/testthat/tic$
+^\.vscode$

.gitignore

@@ -6,3 +6,4 @@
 inst/doc
 .DS_Store
 .vscode
+tests/testthat/tic

.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
     #  R package development
     -   id: roxygenize
     -   id: use-tidy-description
-    -   id: deps-in-desc
+    # -   id: deps-in-desc
 -   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v2.4.0
     hooks:

DESCRIPTION

@@ -61,8 +61,10 @@ Suggests:
     git2r,
     knitr,
     openssl,
+    pkgdown,
     rcmdcheck,
     rmarkdown,
+    rprojroot,
     testthat (>= 2.1.0),
     travis (>= 0.2.11.9001),
     usethis

R/dsl-storage.R

@@ -26,9 +26,24 @@ dslobj_init <- function(envir = parent.frame()) {
 }
 
 
-#' Storage for stages and steps
+#' Stages and steps
 #'
 #' @description
+#' \pkg{tic} works in a declarative way, centered around the `tic.R` file
+#' created by [use_tic()].
+#' This file contains the *definition* of the steps to be run in each stage:
+#' calls to [get_stage()] and [add_step()], or macros like
+#' [do_package_checks()].
+#'
+#' Normally, this file is never executed directly.
+#' Running these functions in an interactive session will **not** carry out
+#' the respective actions.
+#' Instead, a description of the code that would have been run is printed
+#' to the console.
+#' Edit `tic.R` to configure your CI builds.
+#' See `vignette("build-lifecycle", package = "tic")` for more details.
+#'
+#' @details
 #' Stages and steps defined using tic's [DSL] are stored in an
 #' internal object in the package.
 #' The stages are accessible through `dsl_get()`.
@@ -119,10 +134,8 @@ dsl_load <- function(path = "tic.R", force = FALSE, quiet = FALSE) {
 #' @export
 dsl_init <- function(quiet = FALSE) {
   if (!quiet) {
-    cat_bullet(
-      "Creating a blank tic stage configuration",
-      bullet = "tick", bullet_col = "green"
-    )
+    cli_alert_success("Creating a clean tic stage configuration")
+    cli_alert_info("See {.code ?tic::dsl_get} for details")
   }
 
   env <- asNamespace(packageName())

R/local.R

@@ -4,17 +4,22 @@ LocalCI <- R6Class(
 
   public = list(
     get_branch = function() {
-      system2("git", "rev-parse --abbrev-ref HEAD", stdout = TRUE)
+      suppressWarnings(system2("git", "rev-parse --abbrev-ref HEAD", stdout = TRUE))
     },
     get_tag = function() {
-      system2("git", "describe", stdout = TRUE)
+      suppressWarnings(system2("git", "describe", stdout = TRUE))
     },
     is_tag = function() {
-      length(system2("git", c("tag", "--points-at", "HEAD"), stdout = TRUE)) > 0
+      suppressWarnings(length(system2("git", c("tag", "--points-at", "HEAD"), stdout = TRUE)) > 0)
     },
     get_slug = function() {
-      remote <- gh::gh_tree_remote()
-      paste0(remote$username, "/", remote$repo)
+      tryCatch(
+        {
+          remote <- gh::gh_tree_remote()
+          paste0(remote$username, "/", remote$repo)
+        },
+        error = ""
+      )
     },
     get_build_number = function() {
       "local build"
@@ -23,7 +28,7 @@ LocalCI <- R6Class(
       NULL
     },
     get_commit = function() {
-      git2r::revparse_single(revision = "HEAD")$sha
+      tryCatch(git2r::revparse_single(revision = "HEAD")$sha, error = "")
     },
     can_push = function(name = "TRAVIS_DEPLOY_KEY") {
       TRUE

R/macro-bookdown.R

@@ -121,4 +121,6 @@ do_bookdown <- function(...,
   #' @description
   #' By default, the `_book/` directory is deployed
   #' to the `gh-pages` branch, keeping the history.
+
+  dsl_get()
 }

R/macro-package-checks.R

@@ -68,6 +68,8 @@ do_package_checks <- function(...,
     get_stage("after_success") %>%
       add_code_step(covr::codecov(quiet = FALSE))
   }
+
+  dsl_get()
 }
 
 #' Deprecated functions

R/macro-pkgdown.R

@@ -119,4 +119,6 @@ do_pkgdown <- function(...,
   #' @description
   #' By default, the `docs/` directory is deployed to the `gh-pages` branch,
   #' keeping the history.
+
+  dsl_get()
 }

R/print.R

@@ -1,6 +1,8 @@
 #' @import cli
 #' @export
 print.TicStages <- function(x, ...) {
+  cli_h1("tic configuration")
+
   if (all(vlapply(x, stage_is_empty))) {
     cat_bullet(
       "No steps defined in any stage",

R/stage.R

@@ -33,6 +33,9 @@ TicStage <- R6Class( # nolint
     },
 
     prepare_all = function() {
+      # We don't necessarily require a DESCRIPTION file.
+      # Steps that need one can check beforehand and warn the user with a
+      # legible message.
       lapply(private$steps, private$prepare_one)
       invisible()
     },

R/steps-install.R

@@ -9,6 +9,9 @@ InstallDeps <- R6Class(
     },
 
     prepare = function() {
+      if (!file.exists("DESCRIPTION")) {
+        stopc("No DESCRIPTION file found. The step_install_deps step and the do_package_checks macro are only available for packages.")
+      }
       verify_install("remotes")
     },
 

R/steps-pkgdown.R

@@ -20,6 +20,9 @@ BuildPkgdown <- R6Class(
     },
 
     prepare = function() {
+      if (!file.exists("DESCRIPTION")) {
+        stopc("No DESCRIPTION file found. The step_build_pkgdown step and the do_pkgdown macro are only available for packages.")
+      }
       verify_install(c("pkgdown", "remotes"))
       super$prepare()
     }

README.md

@@ -14,7 +14,7 @@ The goal of tic is to enhance and simplify working with continuous integration (
 
 The following ones are supported: 
 
-- [Travis CI](https://travis-ci.org) (Linux, macOS)
+- [Travis CI](https://travis-ci.org) (both https://travis-ci.org and https://travis-ci.com) (Linux, macOS)
 - [AppVeyor](https://www.appveyor.com/) (Windows)
 - [Circle CI](https://circleci.com/) (Linux)
 
@@ -32,34 +32,47 @@ The most important improvements over existing solutions are:
 
 ## Installation
 
-It can be installed from GitHub with:
+{tic} can be installed from GitHub with:
 
-```r
-# install.packages("remotes")
+``` r
 remotes::install_github("ropenscilabs/tic")
 ```
 
 ## Setup
 
 By calling `tic::use_tic()` a production ready CI setup is initialized, tailored to your specific R project.
-The created templates will use the providers https://travis-ci.org, https://appveyor.com and https://circleci.com.
+The created templates will use the providers https://travis-ci.com, https://appveyor.com and https://circleci.com.
+For more information about the difference between https://travis-ci.org and https://travis-ci.com see the vignette about [Travis CI '.org' vs '.com'](https://ropenscilabs.github.io/tic/articles/org-vs-com.html).
 
-If only the CI YAML templates from _tic_ are desired, the `use_<provider>_yml()` functions can be used.
+If only the CI YAML templates from {tic} are desired, the `use_<provider>_yml()` functions can be used.
 Refer to [the complete list of options](https://docs.ropensci.org/tic/reference/yaml-templates.html).
 
 For an R package, the following steps will be set up for the CI workflow:
 
-- Installation of required dependencies for the project
-- Satisfying build-time dependencies of steps to be run in all CI stages
-- Running `rcmdcheck::rcmdcheck()`
-- Building of a `pkgdown` site with deployment GitHub
-- Running a code coverage and uploading it to [codecov.io](https://codecov.io/)
+- Installation of required dependencies for the project (by checking the mandatory(!) DESCRIPTION file)
+- Satisfying build-time dependencies of steps to be run in all CI stages (by scraping `pkg::fun` calls in `tic.R`)
+- Checking of package via `rcmdcheck::rcmdcheck()`
+- Creation of a `pkgdown` site including Github deployment
+- Running a code coverage and upload to [codecov.io](https://codecov.io/)
 
 See the [Getting Started](https://ropenscilabs.github.io/tic/articles/tic.html) vignette for more information and links to [minimal example repositories](https://ropenscilabs.github.io/tic/articles/tic.html#examples-projects) for various R projects (package, blogdown, bookdown and more).
 
+## Good to know
+
+We would like to mention that {tic} is a choice and sits on top of existing community efforts providing R support for various CI providers.
+While {tic} will prevent you from dealing/learning every CIs YAML syntax, you will have to learn {tic}'s way of specifying your tasks on CI systems.
+
+Also, there is no way around familiarizing yourself with the basics of CI systems in general. 
+Without this knowledge, you will also have a hard way understanding {tic}. 
+
+There is not yet an automated way of updating the templates installed by {tic}, hence you need to manually check every once in a while if we made some changes to the templates.
+
+We also recommend to take a look at the projects providing the direct R support for each CI system (which {tic} builds upon) to gain a deeper understanding of the whole concept.
+
 ## Examples
 
-All examples listed here work with Travis, some work with AppVeyor too. The badges link to the most recent build of the master branch.
+All examples listed here work with Travis, some work with AppVeyor too. 
+The badges link to the most recent build of the master branch.
 
 - [tic.blogdown](https://github.com/ropenscilabs/tic.blogdown): Blogs with [_blogdown_](https://bookdown.org/yihui/blogdown/)
 
@@ -120,9 +133,13 @@ All examples listed here work with Travis, some work with AppVeyor too. The badg
 
 - [Custom Steps](https://ropenscilabs.github.io/tic/articles/custom-steps.html)
 
+- [Travis CI '.org' vs '.com'](https://ropenscilabs.github.io/tic/articles/org-vs-com.html)
+
 ## Limitations
 
-The setup functions in this package assume Git as version control system, and GitHub as platform.  Automated setup works best if the project under test is located in the root of the Git repository.  Multi-project repositories are not supported, see [the comment by @jwijffels](https://github.com/ropenscilabs/tic/issues/117#issuecomment-460814990) for guidance to work around this limitation.
+The setup functions in this package assume Git as version control system, and GitHub as platform.
+Automated setup works best if the project under test is located in the root of the Git repository.
+Multi-project repositories are not supported, see [the comment by @jwijffels](https://github.com/ropenscilabs/tic/issues/117#issuecomment-460814990) for guidance to work around this limitation.
 
 ---
 

pkgdown/_pkgdown.yml

@@ -70,6 +70,8 @@ navbar:
       href: articles/deployment.html
     - text: Custom Steps
       href: articles/custom-steps.html
+    - text: Travis CI .org vs .com
+      href: articles/org-vs-com.html
   - text: Changelog
     href: news/index.html
 

tests/testthat/out/bookdown.txt

@@ -0,0 +1,4 @@
+── install ──────────────────────────────────────────────────────────── stage ──
+▶ step_install_deps(repos = repo_default())
+── deploy ───────────────────────────────────────────────────────────── stage ──
+▶ step_build_bookdown()

tests/testthat/out/pkgdown.txt

@@ -0,0 +1,7 @@
+── install ──────────────────────────────────────────────────────────── stage ──
+▶ step_install_deps()
+▶ step_install_deps(repos = repo_default())
+── script ───────────────────────────────────────────────────────────── stage ──
+▶ step_rcmdcheck()
+── deploy ───────────────────────────────────────────────────────────── stage ──
+▶ step_build_pkgdown()

vignettes/advanced.Rmd

@@ -138,17 +138,36 @@ $install
 ▶ step_install_deps(repos = repo_default())
 ```
 
+
 ### Emulating a CI run locally
 
-`run_all_stages()` emulates a CI run on your local machine by executing all stages and their corresponding steps as defined in `tic.R`.
+A tic configuration can be emulated locally.
+
+First, ensure that all prerequisites are met:
+
+```{r eval = FALSE}
+prepare_all_stages()
+```
+
+This might install additional packages, or even fail with a descriptive message.
+
+Then, run all steps defined in `tic.R`:
 
+```{r}
+run_all_stages()
+```
+
+This emulates a CI run on your local machine by executing all stages and their corresponding steps.
 Note that this action this will use your local system libraries and not the CI environment.
 Only the steps that are shown with `dsl_get()` are executed.
 Some steps will not be executed as they are conditioned to run on non-interactive environments only, e.g. `add_step(covr::codcov())` added by the macro `do_package_checks()`.
 
 ```{r, eval = FALSE}
 run_all_stages()
-ℹ Using existing tic stage configuration, use `force = TRUE` to reload
+```
+
+```
+✓ Loading tic stage configuration from tic.R
 Running install: step_install_github("ropensci/rotemplate")
 Skipping install of 'rotemplate' from a github remote, the SHA1 (bec3e6eb) has not changed since last install.
   Use `force = TRUE` to force installation

vignettes/build-lifecycle.Rmd

@@ -68,7 +68,7 @@ Some important points:
   It also does not trigger a CI build.
 All commands just define the workflow of the CI build.
 - The workflow can be loaded using `dsl_load()`, however this will not run any of the commands defined.
-- For testing purposes, all stages and steps defined in `tic.R` can be  executed by calling `run_all_stages()`.
+- For testing purposes, all stages and steps defined in `tic.R` can be executed by calling `run_all_stages()`.
   This emulates a CI build on your local system.
   See [Troubleshooting: Running tic locally](advanced#troubleshooting-running-tic-locally) for more information.