From 666702c81945e6a6c6c90881da84d72aa9d10493 Mon Sep 17 00:00:00 2001 From: Dmitry Shemetov Date: Mon, 22 Jan 2024 15:10:12 -0800 Subject: [PATCH] ci+doc: pull request template, version instructions, pkgdown --- .github/pull_request_template.md | 21 ++++++++++++ .github/workflows/pkgdown.yaml | 24 ++++++++++---- DEVELOPMENT.md | 56 ++++++++++++++++++++++++++++++++ NEWS.md | 22 ++----------- 4 files changed, 97 insertions(+), 26 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 DEVELOPMENT.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..7a7e9ae77 --- /dev/null +++ b/.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} diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 245e43c59..9490acc78 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.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,6 +15,8 @@ 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: @@ -20,7 +24,7 @@ jobs: 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/github-pages-deploy-action@4.1.4 + uses: JamesIves/github-pages-deploy-action@v4.4.1 with: clean: false branch: gh-pages diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 000000000..4bc5733ee --- /dev/null +++ b/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:////epidatr/epipredict/index.html` and `dev` at `file:////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 diff --git a/NEWS.md b/NEWS.md index d2cbc0d29..80eb9f19b 100644 --- a/NEWS.md +++ b/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