How to update the site for released version of a package

[jennybc]

I'm using

development:
  mode: auto

more often these days, which means there's two version of the site, e.g. one for the released version of the package https://gmailr.r-lib.org and another for the development version of the package https://gmailr.r-lib.org/dev/.

But sometimes you need to update the released site, even though the package version in current source has already advanced to a development version. My most recent example was needing to backport some documentation changes and pkgdown config fixes to gmailr's released site.

This issue is a reminder to us to document how to do this.

UPDATE: I gradually realized that our existing pkgdown GHA workflow is capable of doing this. You just need to create a branch that reflects the source state you want to pkgdown-render from and push a tag pointing to that ref. I'm going to delete or hide the notes about my journey to this realization. Update: read on for what to do with this branch.

[jennybc]

As I refined my process, I realized it would be best to build the updated site on GHA. As I thought about what such an action needed to do, I realized the existing pkgdown.yaml workflow is already equipped for exactly this scenario 🙈

So THAT is what we need to document!

on:
  push:
    branches: [main, master]
    tags: ['*']

The tags part of of the workflow trigger is why this already works. However, it also means that anyone who doesn't already appreciate this could overwrite their released or dev site unintentionally, just by pushing a tag other than the most recent release.

It's possible we should make the triggering tags a bit less general and adopt some sort of naming convention for other tags meant to tickle pkgdown. I think we want it to match actual release tags, e.g. vX.Y.Z, and maybe another tag we agree on, for the goal we're talking about here.

Workflow syntax for on.<push|pull_request>.<branches|tags>

---

Create a branch based on the most recent CRAN release. This example is from vroom.

git checkout -b update-pkgdown-1-5-7 v1.5.7
git cherry-pick bd5e87f92006ab0932e0fc7aeb91d011665ceb4d

Substitute the tag of the most recent released version and change the branch name accordingly.
The git cherry-pick stands for any and all fixups you want to apply.

Push this branch to GitHub.

git push --set-upstream origin update-pkgdown-1-5-7

Create a tag at HEAD of this branch and push it too.

git tag pkgdown-update-released-site
git push origin pkgdown-update-released-site

This will trigger our pkgdown GHA workflow and, since the version in DESCRIPTION will be recognized as a release, it will rebuild and deploy the released site.

[hadley]

I'm not sure we want to encourage people to use tags in this way; it feels like using a side-effect of making a tag. Maybe we can add some other trigger?

We definitely should restrict the default tag building: r-lib/actions#450

[jennybc]

This discussion unfolded further in r-lib/actions#450 and r-lib/actions#451.

The end result is that our pkgdown GHA workflow now looks more like this:

on:
  push:
    branches: [main, master]
  release:
    types: [published]
  workflow_dispatch:

The release section handles "normal" releases (assuming they happen in chronological order).

workflow_dispatch gives us a very flexible manual trigger. As described in r-lib/actions#450 (comment), you can trigger a released site rebuild from a branch from the browser. With an API call, you can trigger a released site rebuild from a branch or a tag. We could build workflow_dispatch out a bit more with a wrapper function and/or formal inputs.

[hadley]

Given the changes to the action, does pkgdown need to do anything?

[jennybc]

I think this has become a documentation problem. I still think we should record that, if you're using our GHA workflow, you can trigger an update of the released site via the workflow_dispatch trigger, in the browser or with an API call.

[hadley]

Hmmm maybe we need a "publishing" vignette that could cover this (and more). I won't work on it for the next patch release, but we should do at some point in the future.

[jennybc]

Sounds good. I feel like vignettes are basically decoupled from the release cycle anyway, esp. for a web-oriented package.