ci+doc: pull request template, version instructions, pkgdown

Author: dshemetov

.github/pull_request_template.md

@@ -0,0 +1,21 @@
+### Checklist
+
+Please:
+
+-   [ ] Make sure this PR is against "dev", not "main".
+-   [ ] Request a review from one of the current epipredict main reviewers:
+        dajmcdon.
+-   [ ] 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).
+
+### 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}

.github/workflows/pkgdown.yaml

@@ -1,10 +1,12 @@
-# Workflow derived from https://github.com/r-lib/actions/tree/master/examples
+# 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 use API key.
+# Created with usethis + edited to run on PRs to dev, use API key.
 on:
   push:
-    branches: [main, master]
+    branches: [dev, main]
+  pull_request:
+    branches: [dev, main]
   release:
     types: [published]
   workflow_dispatch:
@@ -13,14 +15,16 @@ 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 }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - uses: r-lib/actions/setup-pandoc@v2
 
@@ -35,13 +39,19 @@ jobs:
 
       - name: Build site
         env:
-          DELPHI_EPIDATA_KEY: ${{ secrets.SECRET_EPIPREDICT_GHACTIONS_DELPHI_EPIDATA_KEY }}
-        run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE)
+          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")
+          } else {
+              mode <- ifelse("${{ github.ref_name }}" == "main", "release", "devel")
+          }
+          pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE, override=list(PKGDOWN_DEV_MODE=mode))
         shell: Rscript {0}
 
       - name: Deploy to GitHub pages 🚀
         if: github.event_name != 'pull_request'
-        uses: JamesIves/[email protected].4
+        uses: JamesIves/github-pages-deploy-action@v4.4.1
         with:
           clean: false
           branch: gh-pages

.github/workflows/version_bump_options.json

@@ -0,0 +1,26 @@
+{
+    "scheme": "semantic",
+    "versionFile": "./DESCRIPTION",
+    "files": [],
+    "rules": [
+      {
+        "trigger": "commit",
+        "branch": "dev",
+        "bump": "build"
+      },
+      {
+        "trigger": "commit",
+        "bump": "minor",
+        "branch": "main",
+        "tag": true,
+        "reset": "build"
+      },
+      {
+        "trigger": "commit",
+        "bump": "major",
+        "branch": "release",
+        "tag": true,
+        "reset": ["minor", "build"]
+      }
+    ]
+  }

DEVELOPMENT.md

@@ -0,0 +1,56 @@
+## Setting up the development environment
+
+```r
+install.packages(c('devtools', 'pkgdown', 'styler', 'lintr')) # install dev dependencies
+devtools::install_deps(dependencies = TRUE) # install package dependencies
+devtools::document() # generate package meta data and man files
+devtools::build() # build package
+```
+
+## Validating the package
+
+```r
+styler::style_pkg() # format code
+lintr::lint_package() # lint code
+
+devtools::test() # test package
+devtools::check() # check package for errors
+```
+
+## Developing the documentation site
+
+The [documentation site](https://cmu-delphi.github.io/epipredict/) is built off of the `main` branch. The `dev` version of the site is available at https://cmu-delphi.github.io/epipredict/dev.
+
+The documentation site can be previewed locally by running in R
+
+```r
+pkgdown::build_site(preview=TRUE)
+```
+
+The `main` version is available at `file:///<local path>/epidatr/epipredict/index.html` and `dev` at `file:///<local path>/epipredict/docs/dev/index.html`.
+
+You can also build the docs manually and launch the site with python. From the terminal, this looks like
+```bash
+R -e 'devtools::document()'
+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 epipredict main reviewers:
+        dajmcdon.
+-   [ ] 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).
+
+## Release process
+
+TBD

NEWS.md

@@ -1,49 +1,33 @@
 # epipredict (development)
 
-# epipredict 0.0.8
+Pre-1.0.0 numbering scheme: 0.x will indicate releases, while 0.0.x will indicate PR's.
+
+# epipredict 0.1
 
 -   add `check_enough_train_data` that will error if training data is too small
 -   added `check_enough_train_data` to `arx_forecaster`
-
-# epipredict 0.0.7
-
 -   simplify `layer_residual_quantiles()` to avoid timesuck in `utils::methods()`
-
-# epipredict 0.0.6
-
 -   rename the `dist_quantiles()` to be more descriptive, breaking change)
 -   removes previous `pivot_quantiles()` (now `*_wider()`, breaking change)
 -   add `pivot_quantiles_wider()` for easier plotting
 -   add complement `pivot_quantiles_longer()`
 -   add `cdc_baseline_forecaster()` and `flusight_hub_formatter()`
-
-# epipredict 0.0.5
-
 -   add `smooth_quantile_reg()`
 -   improved printing of various methods / internals
 -   canned forecasters get a class
 -   fixed quantile bug in `flatline_forecaster()`
 -   add functionality to output the unfit workflow from the canned forecasters
-
-# epipredict 0.0.4
-
 -   add quantile_reg()
 -   clean up documentation bugs
 -   add smooth_quantile_reg()
 -   add classifier
 -   training window step debugged
 -   `min_train_window` argument removed from canned forecasters
-
-# epipredict 0.0.3
-
 -   add forecasters
 -   implement postprocessing
 -   vignettes avaliable
 -   arx_forecaster
 -   pkgdown
-
-# epipredict 0.0.0.9000
-
 -   Publish public for easy navigation
 -   Two simple forecasters as test beds
 -   Working vignette