doc+ci+repo: fix style and release guide

dshemetov · dshemetov · commit 9885f704cea5 · 2024-03-04T17:36:12.000-08:00
* update with fixes from epidatr
* update pull request template
* bugfix pkgdown.yaml
* add workflow_dispatch buttons to most actions
* remove release_helper.yaml which we don't use
* update the DEVELOPMENT.md guide with a release checklist
* update pkgdown.yaml to match epidatr
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -2,20 +2,21 @@
 
 Please:
 
--   [ ] Make sure this PR is against "dev", not "main".
--   [ ] Request a review from one of the current epiprocess main reviewers:
-        brookslogan, nmdefries.
--   [ ] Makes sure to bump the version number in `DESCRIPTION` and `NEWS.md`.
-        Always increment the patch version number (the third number), unless you are
-        making a release PR from dev to main, in which case increment the minor
-        version number (the second number).
--   [ ] Describe changes made in NEWS.md, making sure breaking changes
-        (backwards-incompatible changes to the documented interface) are noted.
-        Collect the changes under the next release number (e.g. if you are on
-        0.7.2, then write your changes under the 0.8 heading).
+- [ ] Make sure this PR is against "dev", not "main" (unless this is a release
+      PR).
+- [ ] Request a review from one of the current main reviewers:
+      brookslogan, nmdefries.
+- [ ] Makes sure to bump the version number in `DESCRIPTION`. Always increment
+      the patch version number (the third number), unless you are making a
+      release PR from dev to main, in which case increment the minor version
+      number (the second number).
+- [ ] Describe changes made in NEWS.md, making sure breaking changes
+      (backwards-incompatible changes to the documented interface) are noted.
+      Collect the changes under the next release number (e.g. if you are on
+      1.7.2, then write your changes under the 1.8 heading).
 
 ### Change explanations for reviewer
 
 ### Magic GitHub syntax to mark associated Issue(s) as resolved when this is merged into the default branch
 
--   Resolves #{issue number}
+- Resolves #{issue number}
diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml
@@ -7,6 +7,7 @@ on:
     branches: [main, dev]
   pull_request:
     branches: [main, dev]
+  workflow_dispatch:
 
 name: R-CMD-check
 
diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml
@@ -1,12 +1,13 @@
 # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
 # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
 #
-# Created with usethis + edited to run on PRs to dev, use API key.
+# Edits from above workflow: also check pkgdown for PRs to `dev` branch, and
+# update the documentation web site on pushes to `dev` branch.
 on:
   push:
-    branches: [dev, main]
+    branches: [main, dev]
   pull_request:
-    branches: [dev, main]
+    branches: [main, dev]
   release:
     types: [published]
   workflow_dispatch:
@@ -15,14 +16,14 @@ name: pkgdown
 
 jobs:
   pkgdown:
-    # only build docs on the main repository and not forks
     if: github.repository_owner == 'cmu-delphi'
     runs-on: ubuntu-latest
     # Only restrict concurrency for non-PR jobs
     concurrency:
       group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }}
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+      DELPHI_EPIDATA_KEY: ${{ secrets.SECRET_EPIPROCESS_GHACTIONS_DELPHI_EPIDATA_KEY }}
     steps:
       - uses: actions/checkout@v3
 
@@ -34,19 +35,29 @@ jobs:
 
       - uses: r-lib/actions/setup-r-dependencies@v2
         with:
-          extra-packages: any::pkgdown, local::.
+          extra-packages: any::pkgdown, local::., any::cli
           needs: website
 
       - name: Build site
-        env:
-          DELPHI_EPIDATA_KEY: ${{ secrets.SECRET_EPIPROCESS_GHACTIONS_DELPHI_EPIDATA_KEY }}
         run: |
-          if (startsWith("${{ github.event_name }}", "pull_request")) {
-              mode <- ifelse("${{ github.base_ref }}" == "main", "release", "devel")
+          override <- if (startsWith("${{ github.event_name }}", "pull_request")) {
+              if ("${{ github.base_ref }}" == "main") {
+                list(development = list(mode = "release", version_label = "light"))
+              } else {
+                list(development = list(mode = "devel", version_label = "success"))
+              }
           } else {
-              mode <- ifelse("${{ github.ref_name }}" == "main", "release", "devel")
+              if ("${{ github.ref_name }}" == "main") {
+                list(development = list(mode = "release", version_label = "light"))
+              } else {
+                list(development = list(mode = "devel", version_label = "success"))
+              }
           }
-          pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE, override=list(PKGDOWN_DEV_MODE=mode))
+          pkg <- pkgdown::as_pkgdown(".", override = override)
+          cli::cli_rule("Cleaning files from old site...")
+          pkgdown::clean_site(pkg)
+          pkgdown::build_site(pkg, preview = FALSE, install = FALSE, new_process = FALSE)
+          pkgdown:::build_github_pages(pkg)
         shell: Rscript {0}
 
       - name: Deploy to GitHub pages 🚀
diff --git a/.github/workflows/release-helper.yaml b/.github/workflows/release-helper.yaml
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -19,38 +19,62 @@ devtools::check() # check package for errors
 
 ## Developing the documentation site
 
-The [documentation site](https://cmu-delphi.github.io/epidatr/) is built off of the `main` branch. The `dev` version of the site is available at https://cmu-delphi.github.io/epidatr/dev.
+Our CI builds two version of the documentation:
 
-The documentation site can be previewed locally by running in R
+- https://cmu-delphi.github.io/epiprocess/ from the `main` branch and
+- https://cmu-delphi.github.io/epiprocess/dev from the `dev` branch.
+
+The documentation site can be previewed locally by running in R:
 
 ```r
+# Should automatically open a browser
 pkgdown::build_site(preview=TRUE)
 ```
 
-The `main` version is available at `file:///<local path>/epidatr/docs/index.html` and `dev` at `file:///<local path>/epidatr/docs/dev/index.html`.
+If the above does not open a browser, you can try using a Python server from the
+command line:
 
-You can also build the docs manually and launch the site with python. From the terminal, this looks like
 ```bash
 R -e 'devtools::document()'
+R -e 'pkgdown::build_site()'
 python -m http.server -d docs
 ```
 
 ## Versioning
 
-Please follow the guidelines in the PR template document (reproduced here):
-
--   [ ] Make sure this PR is against "dev", not "main".
--   [ ] Request a review from one of the current epiprocess main reviewers:
-        brookslogan, nmdefries.
--   [ ] Makes sure to bump the version number in `DESCRIPTION` and `NEWS.md`.
-        Always increment the patch version number (the third number), unless you are
-        making a release PR from dev to main, in which case increment the minor
-        version number (the second number).
--   [ ] Describe changes made in NEWS.md, making sure breaking changes
-        (backwards-incompatible changes to the documented interface) are noted.
-        Collect the changes under the next release number (e.g. if you are on
-        0.7.2, then write your changes under the 0.8 heading).
+Please follow the guidelines in the [PR template document](.github/pull_request_template.md).
 
 ## Release process
 
-TBD
+Open a release issue and then copy and follow this checklist in the issue (modified from the checklist generated by `usethis::use_release_issue(version = "1.0.2")`):
+
+- [ ] `git pull`
+- [ ] Check [current CRAN check results](https://cran.rstudio.org/web/checks/check_results_epiprocess.html)
+- [ ] `devtools::check(".", manual = TRUE, env_vars = c(NOT_CRAN = "false"))`.
+  - Aim for 10/10, no notes.
+- [ ] If check works well enough, merge to main. Otherwise open a PR to fix up.
+- [ ] [Polish NEWS](https://github.com/cmu-delphi/epiprocess/blob/dev/NEWS.md).
+  - Some [guidelines](https://style.tidyverse.org/news.html#news-release).
+- [ ] `git checkout main`
+- [ ] `git pull`
+- [ ] `urlchecker::url_check()`.
+  - This may choke on the MIT license url, and that's ok.
+- [ ] `devtools::build_readme()`
+- [ ] `devtools::check_win_devel()`
+- [ ] Check email for problems
+- [ ] `revdepcheck::revdep_check(num_workers = 4)`.
+  - This may choke, it is very sensitive to the binary versions of packages on a given system. Either bypass or ask someone else to run it if you're concerned.
+- [ ] Update `cran-comments.md`
+- [ ] PR with any changes
+
+Submit to CRAN:
+
+- [ ] `devtools::submit_cran()`
+- [ ] Approve email
+
+Wait for CRAN...
+
+- [ ] Accepted :tada:
+- [ ] `dev`
+- [ ] `usethis::use_github_release(publish = FALSE)` (publish off, otherwise it won't push).
+- [ ] check the release notes and publish the branch on github
diff --git a/_pkgdown.yml b/_pkgdown.yml
@@ -1,92 +1,100 @@
-template:
-    bootstrap: 5
+# Colors should stay consistent across epipredict, epiprocess, and epidatr,
+# using Carnegie Red
+# https://www.cmu.edu/brand/brand-guidelines/visual-identity/colors.html
+
+# This is to give a default value to the `mode` parameter in the
+# `pkgdown::build_site` function. This is useful when building the site locally,
+# as it will default to `devel` mode. In practice, this should all be handled
+# dynamically by the CI/CD pipeline.
+development:
+  mode: devel
+  version_label: success
 
+template:
+  bootstrap: 5
+  bootswatch: cosmo
+  bslib:
+    font_scale: 1.0
+    primary: "#C41230"
+    link-color: "#C41230"
 
-# Colors from epipredict & epidatr, including Carnegie Red https://www.cmu.edu/brand/brand-guidelines/visual-identity/colors.html
 navbar:
-    bg: "#C41230"
-    fg: "#f8f8f8"
-    bootswatch: cosmo
-    bslib:
-        font_scale: 1.0
-        primary: "#C41230"
-        link-color: "#C41230"
-        navbar-bg: "#C41230"
-        navbar-fg: "#f8f8f8"
+  bg: primary
+  type: dark
 
 url: https://cmu-delphi.github.io/epiprocess/
 
 home:
-    links:
-        - text: Introduction to Delphi's Tooling Work
-          href: https://cmu-delphi.github.io/delphi-tooling-book/
-        - text: Get the epipredict R package
-          href: https://cmu-delphi.github.io/epipredict/
-        - text: Get the epidatr R package
-          href: https://github.com/cmu-delphi/epidatr
-        - text: Get the epidatasets R package
-          href: https://cmu-delphi.github.io/epidatasets/
+  links:
+    - text: Introduction to Delphi's Tooling Work
+      href: https://cmu-delphi.github.io/delphi-tooling-book/
+    - text: Get the epipredict R package
+      href: https://cmu-delphi.github.io/epipredict/
+    - text: Get the epidatr R package
+      href: https://github.com/cmu-delphi/epidatr
+    - text: Get the epidatasets R package
+      href: https://cmu-delphi.github.io/epidatasets/
 
 articles:
-    - title: Using the package
-      desc: Basic usage and examples.
-      navbar: ~
-      contents:
-          - epiprocess
-          - slide
-          - growth_rate
-          - correlation
-          - aggregation
-          - outliers
-          - archive
-          - advanced
-          - compactify
+  - title: Using the package
+    desc: Basic usage and examples.
+    navbar: ~
+    contents:
+      - epiprocess
+      - slide
+      - growth_rate
+      - correlation
+      - aggregation
+      - outliers
+      - archive
+      - advanced
+      - compactify
 
 repo:
-    url:
-        home: https://github.com/cmu-delphi/epiprocess/tree/main/
-        source: https://github.com/cmu-delphi/epiprocess/blob/main/
-        issue: https://github.com/cmu-delphi/epiprocess/issues
-        user: https://github.com/
+  url:
+    home: https://github.com/cmu-delphi/epiprocess/tree/main/
+    source: https://github.com/cmu-delphi/epiprocess/blob/main/
+    issue: https://github.com/cmu-delphi/epiprocess/issues
+    user: https://github.com/
 
 reference:
-    - title: "`epi_df` basics"
-      desc: Details on `epi_df` format, and basic functionality.
-    - contents:
-          - matches("epi_df")
-    - title: "`epi_*()` functions"
-      desc: Functions that act on `epi_df` objects.
-    - contents:
-          - epi_slide
-          - epi_cor
-    - title: Vector functions
-      desc: Functions that act directly on signal variables.
-    - contents:
-          - growth_rate
-          - detect_outlr
-          - detect_outlr_rm
-          - detect_outlr_stl
-    - title: "`epi_archive` basics"
-      desc: Details on `epi_archive`, and basic functionality.
-    - contents:
-          - matches("archive")
-    - title: "`epix_*()` functions"
-      desc: Functions that act on an `epi_archive` and/or `grouped_epi_archive` object.
-    - contents:
-          - starts_with("epix")
-          - group_by.epi_archive
-    - title: Example data
-    - contents:
-          - archive_cases_dv_subset
-          - incidence_num_outlier_example
-          - contains("jhu_csse")
-    - title: Basic automatic plotting
-    - contents:
-          - autoplot.epi_df
-    - title: internal
-    - contents:
-          - epiprocess
-          - max_version_with_row_in
-          - next_after
-          - guess_period
-          - key_colnames
+  - title: "`epi_df` basics"
+    desc: Details on `epi_df` format, and basic functionality.
+  - contents:
+      - matches("epi_df")
+  - title: "`epi_*()` functions"
+    desc: Functions that act on `epi_df` objects.
+  - contents:
+      - epi_slide
+      - epi_cor
+  - title: Vector functions
+    desc: Functions that act directly on signal variables.
+  - contents:
+      - growth_rate
+      - detect_outlr
+      - detect_outlr_rm
+      - detect_outlr_stl
+  - title: "`epi_archive` basics"
+    desc: Details on `epi_archive`, and basic functionality.
+  - contents:
+      - matches("archive")
+  - title: "`epix_*()` functions"
+    desc: Functions that act on an `epi_archive` and/or `grouped_epi_archive` object.
+  - contents:
+      - starts_with("epix")
+      - group_by.epi_archive
+  - title: Example data
+  - contents:
+      - archive_cases_dv_subset
+      - incidence_num_outlier_example
+      - contains("jhu_csse")
+  - title: Basic automatic plotting
+  - contents:
+      - autoplot.epi_df
+  - title: internal
+  - contents:
+      - epiprocess
+      - max_version_with_row_in
+      - next_after
+      - guess_period
+      - key_colnames
