Merge pull request #318 from lorenzwalthert/issue-291

lorenzwalthert · web-flow · commit a6e1e20f539b · 2021-11-26T22:37:21.000+01:00
- Template for GitHub Action Workflow (#291).
diff --git a/API b/API
@@ -16,6 +16,7 @@ roxygenize_with_cache(key, dirs)
 snippet_generate(snippet, open = rstudioapi::isAvailable(), root = here::here())
 uninstall_precommit(scope = "repo", ask = "user", root = here::here())
 update_precommit()
-use_precommit(config_source = getOption("precommit.config_source"), force = FALSE, legacy_hooks = "forbid", open = rstudioapi::isAvailable(), install_hooks = TRUE, root = here::here())
+use_ci(ci = getOption("precommit.ci", "native"), force = FALSE, root = here::here())
+use_precommit(config_source = getOption("precommit.config_source"), force = FALSE, legacy_hooks = "forbid", open = rstudioapi::isAvailable(), install_hooks = TRUE, ci = getOption("precommit.ci", "native"), root = here::here())
 use_precommit_config(config_source = getOption("precommit.config_source"), force = FALSE, open = rstudioapi::isAvailable(), verbose = FALSE, root = here::here())
 version_precommit()
diff --git a/NAMESPACE b/NAMESPACE
@@ -14,6 +14,7 @@ export(roxygenize_with_cache)
 export(snippet_generate)
 export(uninstall_precommit)
 export(update_precommit)
+export(use_ci)
 export(use_precommit)
 export(use_precommit_config)
 export(version_precommit)
diff --git a/NEWS.md b/NEWS.md
@@ -5,6 +5,12 @@ includes switching to R based hook for `readme-rmd-render`, avoiding the
 {usethis} dependency, integration tests via GitHub Actions, auto-updates for 
 used packages, roxygen snippet generation and more. In addition:
 
+* `use_precommit()` gains a `ci` argument, defaulting to `"native"`, which will
+  guide the user to set up continuous integration of the hooks with either 
+  [pre-commit.ci](https://pre-commit.ci) or 
+  [GitHub Actions](https://github.com/features/actions). New exported 
+  function `use_ci(ci = "native")` can be used to migrate existing repos. The
+  default behavior for `ci` is governed by the R option `precommit.ci`.
 * `use_precommit(..., install_hooks = TRUE)` is no longer blocking by default.
   New option `precommit.block_install_hooks` (defaults to `FALSE`) governs the
   behavior (#312).
diff --git a/R/setup.R b/R/setup.R
@@ -3,6 +3,7 @@
 #' This function sets up pre-commit for your git repo.
 #' @param install_hooks Whether to install environments for all available hooks.
 #'   If `FALSE`, environments are installed with first commit.
+#' @inheritParams use_ci
 #' @param legacy_hooks How to treat hooks already in the repo which are not
 #'   managed by pre-commit. "forbid", the default, will cause  `use_precommit()`
 #'   to fail if there are such hooks. "allow" will run these along with
@@ -39,6 +40,7 @@ use_precommit <- function(config_source = getOption("precommit.config_source"),
                           legacy_hooks = "forbid",
                           open = rstudioapi::isAvailable(),
                           install_hooks = TRUE,
+                          ci = getOption("precommit.ci", "native"),
                           root = here::here()) {
   rlang::arg_match(legacy_hooks, c("forbid", "allow", "remove"))
   assert_is_installed()
@@ -52,10 +54,61 @@ use_precommit <- function(config_source = getOption("precommit.config_source"),
   install_repo(root, install_hooks, legacy_hooks)
   if (open) {
     open_config(root)
+    use_ci(ci)
+  } else {
+    if (ci == "gha") {
+      use_ci(ci, force = force, root = root)
+    }
   }
+
   invisible(NULL)
 }
 
+
+#' Use continuous integration with pre-commit
+#'
+#' Sets up continuous integration, or prompts the user to do it manually.
+#'
+#' @param ci Specifies which continuous integration service to use. See
+#'   `vignette("ci", package = "precommit")` for details. Defaults to
+#'   `getOption("precommit.ci", "native")`, which is set to
+#'   `"native"` on package loading (if unset). `"native"` sets up
+#'   [pre-commit.ci](https://pre-commit.ci). Alternatively, `"gha"` can be used
+#'   to set up [GitHub Actions](https://github.com/features/actions). Set value
+#'   to `NULL` if you don't want to use a continuous integration.
+#' @param force Whether or not to overwrite an existing ci config file (only
+#'   relevant for `ci = "gha"`).
+#' @inheritParams fallback_doc
+#' @export
+use_ci <- function(ci = getOption("precommit.ci", "native"),
+                   force = FALSE, root = here::here()) {
+  if (is.na(ci)) {
+    return()
+  } else if (ci == "gha") {
+    dest <- fs::path(root, ".github/workflows/pre-commit.yaml")
+    fs::dir_create(fs::path_dir(dest))
+    fs::file_copy(
+      system.file("pre-commit-gha.yaml", package = "precommit"),
+      dest,
+      overwrite = force
+    )
+    cli::cli_alert_success(paste0(
+      "Added GitHub Action template to ",
+      "{.code .github/workflows/pre-commit.yaml}. Pre-commit hooks will ",
+      "run on pull requests. If workflow fails, please file an issue in ",
+      "{.code https://github.com/lorenzwalthert/precommit}."
+    ))
+  } else if (ci == "native") {
+    cli::cli_ul("Sign in with GitHub to authenticate {.url https://pre-commit.ci}.")
+    Sys.sleep(2)
+    utils::browseURL("https://pre-commit.ci")
+  } else {
+    rlang::abort(
+      'Argument `ci` must be one of `"native"` (default), `"gha"` or `NULL`.'
+    )
+  }
+}
+
 #' Auto-update your hooks
 #'
 #' Runs [`pre-commit autoupdate`](https://pre-commit.com/#pre-commit-autoupdate).
diff --git a/R/zzz.R b/R/zzz.R
@@ -2,7 +2,8 @@
   op <- options()
   op.precommit <- list(
     precommit.executable = path_derive_precommit_exec(),
-    precommit.block_install_hooks = FALSE
+    precommit.block_install_hooks = FALSE,
+    precommit.ci = "native"
   )
   toset <- !(names(op.precommit) %in% names(op))
   if (any(toset)) options(op.precommit[toset])
diff --git a/inst/WORDLIST b/inst/WORDLIST
@@ -59,6 +59,7 @@ getwd
 gh
 github
 gitignore
+Gitlab
 grDevices
 grepl
 gsub
diff --git a/inst/pre-commit-gha.yaml b/inst/pre-commit-gha.yaml
@@ -0,0 +1,55 @@
+name: pre-commit
+on:
+  push:
+    branches-ignore:
+      - 'master'
+      - 'main'
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-18.04
+    if: >-
+      !contains(github.event.head_commit.message, 'ci skip') &&
+      (
+        startsWith(github.ref, 'refs/heads') ||
+        github.event.pull_request.draft == false
+      )
+    steps:
+      - name: Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.6.0
+        with:
+          access_token: ${{ github.token }}
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Install system dependencies
+        if: runner.os == 'Linux'
+        run: |
+          # your system installation code here
+          # sudo apt-get install -y libcurl4-openssl-dev
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+          architecture: "x64"
+      - name: Run pre-commit
+        uses: pre-commit/action@v2.0.3
+      - name: Commit files
+        if: failure() && startsWith(github.ref, 'refs/heads')
+        run: |
+          if [[ `git status --porcelain --untracked-files=no` ]]; then
+            git config --local user.email "github-actions[bot]@users.noreply.github.com"
+            git config --local user.name "github-actions[bot]"
+            git checkout -- .github/workflows
+            git commit -m "pre-commit" -a
+          fi
+      - name: Push changes
+        if: failure() && startsWith(github.ref, 'refs/heads')
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ github.ref }}
+    env:
+      RENV_CONFIG_CACHE_ENABLED: FALSE
diff --git a/man/use_ci.Rd b/man/use_ci.Rd
diff --git a/man/use_precommit.Rd b/man/use_precommit.Rd
diff --git a/test.R b/test.R
diff --git a/tests/testthat/test-setup.R b/tests/testthat/test-setup.R
@@ -1,5 +1,7 @@
 test_that("snippet generation works", {
-  local_test_setup(git = FALSE, use_precommit = FALSE, package = TRUE, install_hooks = FALSE)
+  local_test_setup(
+    git = FALSE, use_precommit = FALSE, package = TRUE, install_hooks = FALSE
+  )
   usethis::use_package("styler")
   usethis::use_package("R", "Depends", "3.6.0")
   expect_warning(
@@ -18,3 +20,21 @@ test_that("snippet generation works", {
     out, "    -   id: roxygenize\n.*        -    styler\n        -    testthat\n$",
   )
 })
+
+
+test_that("GitHub Action CI setup works", {
+  expect_error(use_ci("stuff"), "must be one of")
+  local_test_setup(
+    git = FALSE, use_precommit = FALSE, package = TRUE, install_hooks = FALSE
+  )
+  use_ci("gha", root = getwd())
+  expect_true(fs::file_exists(".github/workflows/pre-commit.yaml"))
+})
+
+test_that("Pre-commit CI setup works", {
+  local_test_setup(
+    git = FALSE, use_precommit = FALSE, package = TRUE, install_hooks = FALSE
+  )
+  use_ci(root = getwd())
+  expect_false(fs::file_exists(".github/workflows/pre-commit.yaml"))
+})
diff --git a/vignettes/ci.Rmd b/vignettes/ci.Rmd
@@ -0,0 +1,73 @@
+---
+title: "Continuous Integration"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Continuous Integration}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+# Setting up CI/CD
+
+When initializing pre-commit in your repo with `precommit::use_precommit()`, 
+you can specify the Continuous integration provider with `ci = "native"` if you 
+want to use [pre-commit.ci](https://pre-commit.ci) or `ci = "gha"` if you want 
+to use GitHub Actions. For existing repos, see below.
+
+# Comparison 
+
+Next, we quickly introduce the two options. We recommend 
+[pre-commit.ci](https://pre-commit.ci) unless your package has system 
+dependencies that are not shipped with the R package on Linux 
+**and at the same time** you want to use the 
+[roxygenize hook](https://lorenzwalthert.github.io/precommit/dev/articles/available-hooks.html#roxygenize-1).
+
+
+## pre-commit.ci
+
+**Pros:**
+
+- by the creator of pre-commit. Certain CI settings in `.pre-commit-config.yaml`
+  [are supported](https://pre-commit.ci).
+- actively developed.
+- very fast.
+- will at some point also be supported for repos hosted outside of GitHub.
+- No maintenance effort for you.
+- No additional file in the repo.
+
+**Cons:**
+
+- You need to authenticate the pre-commit.ci App in GitHub. 
+- System dependencies are not supported. In particular, since {roxygen2} loads
+  your package for the roxygenize hook, this hook will fail if your package has
+  system dependencies that are not shipped with the package.
+  
+## GitHub Actions
+
+**Pros:**
+
+- more control over environment, e.g. system dependencies.
+- No new authentication needed. 
+- If your package has system dependencies and you want to use the roxygenize 
+  hook, you can install them.
+  
+**Cons:**
+
+- out-of-the-box action is in 
+  [maintenance only mode](https://github.com/pre-commit/action) and less 
+  feature complete than [pre-commit.ci](https://pre-commit.ci). For example, 
+  if your hooks fail on first attempt, the corrections are committed and pushed, 
+  but they won't trigger a new CI and you can't make them do it without 
+  [exposing credentials](https://github.com/pre-commit/action/pull/49). The only
+  way is to close and re-open the PR.
+- You need to maintain the workflow file with a lot of boilerplate code and 
+  when GitHub changes the syntax, you need to adapt it to prevent failing 
+  builds.
+- You'll have one additional file per provider (e.g. GitHub, Gitlab).
+
+
+# Migrating existent repos
+
+We provide helper functionality to set up CI/CD. Use `precommit::use_ci("gha")` 
+for GitHub Actions or `precommit::use_ci("native")` for pre-commit.ci 
+respectively.
