Address ropensci review (#213)

* Make it possible to pass the endpoint arg from {travis} funs to use_tic()
* mention the difference between .com and .org -> new vignette "org-vs-com")
* prepare moving to ropensci org

.Rbuildignore

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

.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

@@ -26,16 +26,29 @@ Authors@R:
              family = "Ooms",
              role = "aut",
              email = "jeroen.ooms@stat.ucla.edu"),
+      person(given = "Max",
+             family = "Held",
+             role = "rev",
+             comment = "Max reviewed the package for ropensci, see <https://github.com/ropensci/software-review/issues/305>"),
+      person(given = "Anna",
+             family = "Krystalli",
+             role = "rev",
+             comment = "Anna reviewed the package for ropensci, see <https://github.com/ropensci/software-review/issues/305>"),
+      person(given = "Laura",
+             family = "DeCicco",
+             role = "rev",
+             comment = "Laura reviewed the package for ropensci, see <https://github.com/ropensci/software-review/issues/305>"),
       person(given = "rOpenSci",
              role = "fnd"))
 Description: Provides a way to describe common build and
     deployment workflows for R-based projects: packages, websites (e.g.
     blogdown, pkgdown), or data processing (e.g. research compendia).  The
     recipe is described independent of the continuous integration tool
     used for processing the workflow (e.g.  'Travis CI' or 'AppVeyor').
+    This package has been peer-reviewed by rOpenSci (v. 0.3.0.9004).
 License: GPL (>= 2)
-URL: https://github.com/ropenscilabs/tic
-BugReports: https://github.com/ropenscilabs/tic/issues
+URL: https://github.com/ropensci/tic
+BugReports: https://github.com/ropensci/tic/issues
 Depends: 
     R (>= 3.2.0)
 Imports: 
@@ -61,8 +74,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,26 @@ LocalCI <- R6Class(
 
   public = list(
     get_branch = function() {
-      system2("git", "rev-parse --abbrev-ref HEAD", stdout = TRUE)
+      # Suppress warnings that occur if not in a Git repo
+      suppressWarnings(system2("git", "rev-parse --abbrev-ref HEAD", stdout = TRUE))
     },
     get_tag = function() {
-      system2("git", "describe", stdout = TRUE)
+      # Suppress warnings that occur if not in a Git repo
+      suppressWarnings(system2("git", "describe", stdout = TRUE))
     },
     is_tag = function() {
-      length(system2("git", c("tag", "--points-at", "HEAD"), stdout = TRUE)) > 0
+      # Suppress warnings that occur if not in a Git repo
+      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)
+      # Suppress error that occurs if not in a Git repo
+      tryCatch(
+        {
+          remote <- gh::gh_tree_remote()
+          paste0(remote$username, "/", remote$repo)
+        },
+        error = ""
+      )
     },
     get_build_number = function() {
       "local build"
@@ -23,7 +32,8 @@ LocalCI <- R6Class(
       NULL
     },
     get_commit = function() {
-      git2r::revparse_single(revision = "HEAD")$sha
+      # Suppress error that occurs if not in a Git repo
+      tryCatch(git2r::revparse_single(revision = "HEAD")$sha, error = "")
     },
     can_push = function(name = "TRAVIS_DEPLOY_KEY") {
       TRUE

R/macro-bookdown.R

@@ -119,4 +119,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

@@ -118,4 +118,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,7 @@ InstallDeps <- R6Class(
     },
 
     prepare = function() {
+      cli_alert_danger("The {.code step_install_deps()} step and the {.code do_package_checks()} macro are only available for packages.")
       verify_install("remotes")
     },
 

R/steps-pkgdown.R

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

R/use_tic.R

@@ -3,6 +3,10 @@
 #' @title Initialize CI testing using tic
 #' @description Prepares a repo for building and deploying supported by
 #' \pkg{tic}.
+#' Depending on your choice of CI system, this function requires
+#' properly set up authentication with Travis CI and/or Circle CI.
+#' See `vignette("travis", package = "travis")` and
+#' `vignette("circle", package = "circle")` for details.
 #'
 #' @importFrom utils menu
 #' @details

R/utils.R

@@ -65,7 +65,7 @@ check_travis_pkg <- function() {
     cli::cat_rule(col = "red")
     stopc(
       "`use_tic()` needs the `travis` package. Please ",
-      'install it using `remotes::install_github("ropenscilabs/travis")`.'
+      'install it using `remotes::install_github("ropensci/travis")`.'
     )
   }
 }
@@ -156,7 +156,7 @@ get_install_tic_code <- function() {
     # We are on CRAN!
     "remotes::install_cran('tic', upgrade = 'always')"
   } else {
-    "remotes::install_github('ropenscilabs/tic', upgrade = 'always')"
+    "remotes::install_github('ropensci/tic', upgrade = 'always')"
   }
 }
 

README.md

@@ -1,11 +1,11 @@
 # tic
 
 <!-- badges: start -->
-[![Travis build status](https://img.shields.io/travis/ropenscilabs/tic/master?logo=travis&style=flat-square&label=Linux)](https://travis-ci.com/ropenscilabs/tic)
+[![Travis build status](https://img.shields.io/travis/ropensci/tic/master?logo=travis&style=flat-square&label=Linux)](https://travis-ci.com/ropensci/tic)
 [![AppVeyor build status](https://img.shields.io/appveyor/ci/ropensci/tic?label=Windows&logo=appveyor&style=flat-square)](https://ci.appveyor.com/project/ropensci/tic)
-[![CircleCI](https://img.shields.io/circleci/build/gh/ropenscilabs/tic/master?label=Linux&logo=circle&logoColor=green&style=flat-square)](https://circleci.com/gh/ropenscilabs/tic)
+[![CircleCI](https://img.shields.io/circleci/build/gh/ropensci/tic/master?label=Linux&logo=circle&logoColor=green&style=flat-square)](https://circleci.com/gh/ropensci/tic)
 [![CRAN status](https://www.r-pkg.org/badges/version/tic)](https://cran.r-project.org/package=tic)
-[![codecov](https://codecov.io/gh/ropenscilabs/tic/branch/master/graph/badge.svg)](https://codecov.io/gh/ropenscilabs/tic)
+[![codecov](https://codecov.io/gh/ropensci/tic/branch/master/graph/badge.svg)](https://codecov.io/gh/ropensci/tic)
 [![Lifecycle: maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://www.tidyverse.org/lifecycle/#maturing)
 [![](https://badges.ropensci.org/305_status.svg)](https://github.com/ropensci/software-review/issues/305)
 <!-- badges: end -->
@@ -14,11 +14,11 @@ 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)
 
-To learn more about CI, read [the "Travis CI for test automation" blog post](http://mahugh.com/2016/09/02/travis-ci-for-test-automation/) and our [Getting Started](https://ropenscilabs.github.io/tic/articles/tic.html#prerequisites) vignette.
+To learn more about CI, read [the "Travis CI for test automation" blog post](http://mahugh.com/2016/09/02/travis-ci-for-test-automation/) and our [Getting Started](https://docs.ropensci.org/tic/articles/tic.html#prerequisites) vignette.
 
 The most important improvements over existing solutions are:
 
@@ -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")
-remotes::install_github("ropenscilabs/tic")
+``` r
+remotes::install_github("ropensci/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://docs.ropensci.org/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).
+See the [Getting Started](https://docs.ropensci.org/tic/articles/tic.html) vignette for more information and links to [minimal example repositories](https://docs.ropensci.org/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/)
 
@@ -106,23 +119,27 @@ All examples listed here work with Travis, some work with AppVeyor too. The badg
 
 ## Vignettes
 
-- [Get started](https://ropenscilabs.github.io/tic/articles/tic.html)
+- [Get started](https://docs.ropensci.org/tic/articles/tic.html)
+
+- [Feature Overview](https://docs.ropensci.org/tic/articles/features.html)
 
-- [Feature Overview](https://ropenscilabs.github.io/tic/articles/features.html)
+- [The CI Build Lifecycle](https://docs.ropensci.org/tic/articles/build-lifecycle.html)
 
-- [The CI Build Lifecycle](https://ropenscilabs.github.io/tic/articles/build-lifecycle.html)
+- [CI Client Packages](https://docs.ropensci.org/tic/articles/ci-client-packages.html)
 
-- [CI Client Packages](https://ropenscilabs.github.io/tic/articles/ci-client-packages.html)
+- [Advanced Usage](https://docs.ropensci.org/tic/articles/advanced.html)
 
-- [Advanced Usage](https://ropenscilabs.github.io/tic/articles/advanced.html)
+- [Deployment](https://docs.ropensci.org/tic/articles/deployment.html)
 
-- [Deployment](https://ropenscilabs.github.io/tic/articles/deployment.html)
+- [Custom Steps](https://docs.ropensci.org/tic/articles/custom-steps.html)
 
-- [Custom Steps](https://ropenscilabs.github.io/tic/articles/custom-steps.html)
+- [Travis CI '.org' vs '.com'](https://docs.ropensci.org/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/ropensci/tic/issues/117#issuecomment-460814990) for guidance to work around this limitation.
 
 ---