cran-automation.Rmd

---
title: "Automate CRAN releases"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{cran-automation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Workflow

{fledge} is able to automate a CRAN release, both locally and via continuous integration (CI).
The only difference between the local and the CI approach is that the user has to call `fledge::unleash()` (or its child functions) manually after each step.

In the following we describe the workflow via the CI approach.
If a CI build is triggered by a tag (i.e. a release was made), a specific runner in the build matrix is being run which calls `fledge::unleash()`.
This runner is run every 2h (?) on the branch and calls `fledge::unleash()` every time.

## Execution Conditions

The following list describes the conditions which need to be fulfilled for each state:

- `pre_release()`: 
  - No `CRAN-SUBMISSION` file exists.
  - The package version number has a four component scheme.
  - There is no `cran-comments.md` file.
- `release()`:
  - Three component package version.
  - A `cran-comments.md` file exists.
  - The local package version is smaller than the one on CRAN.
- `post_release()`: 
  - The local version is equal to the CRAN version.
  - All boxes in `cran-comments.md` are checked.

Possible improvements: 
- Let the user forward specific CRAN mails so fledge can check the required boxes itself.
  Currently users needs to check the boxes in `cran-comments.md` themselves.
- Make strict NEWS checking optional
- The branch creation should be optional (TRUE by default).

`unleash()` wraps 

- `fledge::pre_release()`
- `fledge::release()`
- `fledge::post_release()`

## Execution Actions

The following list describes the actions of each state function:

- `pre_release()`
  - Creates `cran-comments.md` from template.
  - Creates a branch named `r-release<version>`.
  - Check recent changes to CRAN policies via `eddelbuettel/crp@master`.
  - Calls `devtools::check_win_devel()`.
  - Calls `rhub::check_for_cran()`.
  - Calls `foghorn::cran_details()`.
  
- `release()`
  - Calls `devtools::submit_cran()`.
  - Calls `fledge:::confirm_submission()`.
  
- `post_release()`
  - Calls `fledge::tag_version()`.
  - Calls `git push --tags`.
  - Calls `usethis::use_github_release()`.
  - Calls `fledge::bump_version()` to switch to dev version again.

After `post_release()`, the Pull Request should be merged and the branch deleted.