What if it's an awkward time to release?

[jennybc]

I'm just opening this issue to document an alternative workflow that might be relevant to a sub-population of maintainers. We could leave it open if it might help folks or just close it, knowing we've written it down somewhere.

Problem: CRAN's given you a deadline to fix X. But since you last released, you've done a lot of work on features Y and Z and you're still sort of in the middle of it. Now what?

I think if you can speed things along and do an authentic release, that's always best. But sometimes you can't.

Solution: You could make the minimal changes necessary to your most recent CRAN version and do a patch release. This keeps your package safely on CRAN, but allows your "real" release to unfold on a schedule compatible with the rest of your life.

---

Sketch of how I would do this:

• Pre-reqs: I always create Git tag for each CRAN release. This is part of what usethis::use_github_release() does. You will also want to make sure you have the latest version of roxygen2 installed locally.
• Determine your patch release's version number by incrementing the patch component of your most recent CRAN release. For example, if v2.0.1 is currently on CRAN, your patch release will be v2.0.2.
• Create a new branch for your patch release, based on your previous release. In R, you could use gert and do something like:

  gert::git_branch_create("v2.0.2", ref = "v2.0.1")
  

  The command line equivalent is:

  git checkout -b v2.0.2 v2.0.1
  

• Increment the version in DESCRIPTION and NEWS:

  usethis::use_version("patch")
  

  Push this branch. It doesn't really matter whether you initiate a pull request or not, because you probably will never merge this into the default branch.

  usethis::pr_push()
  

• Bring the workflow from this repo into that branch:

  usethis::use_github_action(url = "https://github.com/DavisVaughan/extrachecks-html5/blob/main/R-CMD-check-HTML5.yaml")
  

  Note: I think it makes sense to explicitly set the env var NOT_CRAN = FALSE. Meaning: explicitly check as if you were CRAN. This is because otherwise, you are likely to see snapshot test failures that will confuse matters and that are not relevant for keeping your package safely on CRAN. So I modified the check-r-package step of the workflow like so:

  - uses: r-lib/actions/check-r-package@v2
    env:
      NOT_CRAN: false
    with:
      args: '"--as-cran"'
      build_args: 'character()'
      error-on: '"note"'
  

  You will also need to add the name of your patch branch in the on: section. For example:

  on:
    push:
      branches: [v2.0.2, main, master]
  

  This is because your patch branch will almost certainly have merge conflicts with your default branch, so the pull_request trigger won't actually fire for this branch.
• Commit .github/workflows/R-CMD-check-HTML5.yaml and push. You should expect the R-CMD-check-HTML5.yaml workflow to fail, replicating CRAN's NOTE about invalid HTML5. That should be the ONLY reason it's failing.
• Re-generate your .Rd files:

  devtools::document()
  

• Commit the changes in DESCRIPTION and below man/ and push. You should expect the R-CMD-check-HTML5.yaml workflow to pass, indicating you have fixed the problem and it's safe to submit this version to CRAN.

You probably want to increment the patch component in your default (dev) branch at this point, to reflect the insertion of this unplanned patch release.

[jennybc]

This reprex PR basically implements what's described above:

https://github.com/tidyverse/reprex/pull/423

[DavisVaughan]

Note that if you don't have a Git tag that you can refer to, you can find the commit SHA that matches the commit that you sent to CRAN and use that as the ref in gert::git_branch_create("v2.0.2", ref = "YOUR-SHA-HERE")

[DavisVaughan]

You probably want to increment the patch component in your default (dev) branch at this point, to reflect the insertion of this unplanned patch release.

Concretely, it sounds like after CRAN accepts your patch release, you'd need to:

• Bump the DESCRIPTION version in main from, say, 2.0.1.9000 to 2.0.2.9000 (assuming you were at 2.0.1 and did a patch release for 2.0.2)
• Do nothing to the top most header in NEWS because it should say # mypkg (development version)
• Insert a header in the NEWS for # mypkg 2.0.2 with a single bullet about the fact that this was an ad hoc patch release. This might also be a nice place to link back to the PR on GitHub that was never merged

[hadley]

I made this checklist for myself, and I'm going to try it shortly:

Create hot patch:

• [ ] Create hot patch branch, (e.g.) gert::git_branch_create(paste0("v", new_ver), ref = paste0("v", old_ver))
• [ ] usethis::use_version("patch") and update news with Hot patch release to resolve R CMD check failures.
• [ ] Fix the motivating R CMD check problems.
• [ ] gert::git_push(set_upstream = TRUE)

Prepare for release:

• [ ] urlchecker::url_check()
• [ ] devtools::check_win_devel()
• [ ] Update cran-comments.md

Submit to CRAN:

• [ ] devtools::submit_cran()
• [ ] Approve email

Wait for CRAN...

• [ ] Accepted :tada:
• [ ] git push
• [ ] usethis::use_github_release()
• [ ] Copy news section
• [ ] gert::git_branch_checkout("main")
• [ ] Increment minor version number in DESCRIPTION and NEWS, paste news section
• [ ] git push

[jennybc]

OK, so you're relying on win-builder+r-devel to confirm the HTML5 is fixed (as opposed to GHA).

It feels like you could still use usethis::use_version("patch"), but that's neither here nor there.

[hadley]

@jennybc oh yeah, you're right, I confused myself.

[jennybc]

Propose to add the text of the bullet point, as detail for this checklist item: "usethis::use_version("patch") and update news".

Here's what I've been using:

Help files below man/ have been re-generated, so that they give rise to valid HTML5. (This is the impetus for this release, to keep the package safely on CRAN.)

[hadley]

@jennybc I counter propose this as more generic text that we could use in a future usethis workflow:

• Hot patch release to resolve R CMD check failures

[hadley]

Examples in flight at https://github.com/tidyverse/dtplyr/issues/389, https://github.com/tidyverse/stringr/issues/453.