Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates based on my recent experiences #2368

Merged
merged 3 commits into from
Nov 14, 2023
Merged

Updates based on my recent experiences #2368

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4e81f2e
Updates based on my recent experiences
hadley Nov 3, 2023
1937298
Apply suggestions from code review
hadley Nov 14, 2023
8086864
Feedback from review
hadley Nov 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions DESCRIPTION
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ Suggests:
covr,
diffviewer,
evaluate,
gert,
htmltools,
htmlwidgets,
knitr,
Expand Down
206 changes: 114 additions & 92 deletions vignettes/how-to-update-released-site.Rmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,68 +10,95 @@ vignette: >
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
comment = "#>",
eval = FALSE
)
```

## Checklist
This vignette shows you how to update the released version of your site to match the dev version of the site, so the first step is to ensure that the dev site looks the way that you want it.

If you're already up-to-speed, here's the checklist:
## Process

* Make sure your dev site looks the way you want before embarking on an update
of your released site. Here are good instructions for updating an existing
site for pkgdown 2.0.0, Bootstrap 5, and "tidyverse/tidytemplate" (only
applies to certain packages):
<https://tidytemplate.tidyverse.org>
* Make sure you are using automatic development mode. In `_pkgdown.yml`:
If you're up to speed with the basic idea and just want some code to follow here it us.
Otherwise, read more below.

``` yaml
development:
mode: auto
```
* Push/pull to sync your default branch.
* Create and checkout a branch based on the tag of your most recent GitHub/CRAN
release.

Example for readr, whose latest release is 2.1.1:
`git checkout -b update-pkgdown-2-1-1 v2.1.1`

General pattern:
`git checkout -b NEW-BRANCH-NAME NAME-OF-RELEASE-TAG`
* Backport innovations from the future. Example of a useful opening move:
`git checkout main -- _pkgdown.yml .github/workflows/pkgdown.yaml`

Most likely candidates:
- `_pkgdown.yml`
- `.github/workflows/pkgdown.yaml`
- `Config/Needs/website: tidyverse/tidytemplate` in DESCRIPTION
- Any fixes to `README.Rmd` / `README.md` or released roxygen comments. Don't
forget to `devtools::build_readme()` or `devtools::document()`, in that
case.

These are the two main Git commands you'll need:
```
git checkout REF -- path/to/a/specific/file
git cherry-pick SHA
```
* Monitor your progress locally with `pkgdown::build_site()`.
* Push this branch, maybe using `usethis::pr_push()`. Don't bother opening
a pull request (the branch will still be created and pushed).
* Go to your package's GHA page, maybe using `usethis::browse_github_actions()`.
Select the pkgdown workflow. Click *Run workflow* and select the branch you
just pushed. If there's no dropdown menu for this, that means your pkgdown
workflow config is not current.
* Scrutinize your newly published **released** site and make sure things look
right.
* You can let this branch sit around for a while, in case you need to iterate
on this or if you'd like to backport more niceties before your next CRAN
release. Or you can delete immediately, if you're happy with the released
site.
### Setup

First, make sure you're in the `main` branch, and you have the latest version:

```{r}
gert::git_branch_checkout("main")
gert::git_pull()
```

Next figure out the released version that we're updating:

```{r}
ver <- desc::desc_get_version()[1, 1:3]
```

We'll use this to create and checkout the branch that you'll work in:

```{r}
gert::git_branch_create(paste0("pkgdown-v", ver), paste0("v", ver))
```

### Backport changes

Now you need to backport changes from the dev site into this branch.
Run this R code to generate the git code to pull changes for the most common locations:

```{r}
files <- c(
# overall site config
"_pkgdown.yml",
# the workflow that builds the site
".github/workflows/pkgdown.yaml",
# readme and vignettes
"README.md", "vignettes",
# logo and favicon
"man/figures/", "pkgdown/",
# Author metadata and Config/Needs/Website
"DESCRIPTION"
)

glue::glue("git checkout v{ver} -- {files}")
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feels like you still need to explicitly say to run that git command in the terminal.

I assume you checked/experienced this, but you can just put a whole folder there in git checkout? I think I always do this move with individual files 🤔

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the reader of this doc can be assumed to understand that if I'm generating git code in R, they'll need to copy and paste it.

And yes, you can indeed checkout folders.

```

If you backport `DESCRIPTION`, you'll also need undo the change to the `Version`:

```{r}
desc::desc_set_version(ver)
```

Now build the site locally and check that it looks as you expect:

```{r}
pkgdown::build_site()
```

### Publish

Now you need to publish the site.
First push your branch to GitHub:

```{r}
usethis:::git_push_first()
hadley marked this conversation as resolved.
Show resolved Hide resolved
```

Then trigger the pkgdown workflow:

1. Go to your package's GHA page, e.g. with `usethis::browse_github_actions())`.
2. Select the pkgdown workflow.
3. Click *Run workflow* and select the branch you just pushed.

If there's no dropdown menu for this, that means your pkgdown workflow config is not current.

## Context

Before we talk about **how** to update a released site, we first establish **why** you might need to do this.
What is a released site? What other kind of pkgdown site could you have?
What is a released site?
What other kind of pkgdown site could you have?
Why does updating a released site take special effort?

### Automatic development mode
Expand All @@ -91,7 +118,7 @@ This directs pkgdown to "generate different sites for the development and releas

The readr package demonstrates what happens in automatic development mode:

[readr.tidyverse.org](https://readr.tidyverse.org) documents the released version, i.e. what `install.packages()` would deliver.
[readr.tidyverse.org](https://readr.tidyverse.org) documents the released version, i.e. what `install.packages()` would deliver.\
hadley marked this conversation as resolved.
Show resolved Hide resolved
[readr.tidyverse.org/dev/](https://readr.tidyverse.org/dev/) documents the dev version, i.e. what you'd get by installing from GitHub.

In this mode, `pkgdown::build_site()`, consults DESCRIPTION to learn the package's version number.
Expand All @@ -108,7 +135,7 @@ Now that we've established the meaning of a released (vs dev) site, we have to c
Many people use `usethis::use_pkgdown_github_pages()` to do basic pkgdown setup and configure a GitHub Actions (GHA) workflow to automatically render and publish the site to GitHub Pages.
Here's an overview of what this function does:

```
```
usethis::use_pkgdown_github_pages() =
use_pkgdown() +
use_github_pages() +
Expand Down Expand Up @@ -148,96 +175,92 @@ on:
<snip, snip>
```

We build and deploy for pushes to `main` (or `master`).
We build for pull requests against `main` (or `master`).
We build and deploy for pushes to `main` (or `master`).\
We build for pull requests against `main` (or `master`).\
But we don't deploy for pull requests.

We build and deploy when we publish a GitHub release.
By convention, we assume that a GitHub release coincides with a CRAN release.
**This is the primary mechanism for building the released pkgdown site.**
We build and deploy when we publish a GitHub release.\
By convention, we assume that a GitHub release coincides with a CRAN release.\
**This is the primary mechanism for building the released pkgdown site.**

`pkgdown::build_site_github_pages()` consults the version in DESCRIPTION to detect whether it's building from a released version or a dev version.
That determines the `dest_dir`, e.g. `docs/` for released and `docs/dev/` for dev.
For a package in automatic development mode, this means that almost all of your pushes trigger an update to the dev site.
For a package in automatic development mode, this means that almost all of your pushes trigger an update to the dev site.
The released site is only updated when you push a state with a non-development version number or when you publish a GitHub release.

So how do you tweak things about the released site *in between* releases?

That brings us to `workflow_dispatch:`. (Yes that dangling colon is correct.)
That brings us to `workflow_dispatch:`.
(Yes that dangling colon is correct.)

The inclusion of `workflow_dispatch` as a trigger means the pkgdown workflow can be run on demand, either manually from the browser or via the GitHub REST API.
We're going to show how to update a released site from a GitHub branch or tag, using the browser method.
The inclusion of `workflow_dispatch` as a trigger means the pkgdown workflow can be run on demand, either manually from the browser or via the GitHub REST API. We're going to show how to update a released site from a GitHub branch or tag, using the browser method.
In the future, we might build some tooling around the API method.

Places to learn more about triggering GHA workflows:

* <https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#workflow_dispatch>
* <https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow>
* <https://docs.github.com/en/rest/reference/actions/#create-a-workflow-dispatch-event>
- <https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#workflow_dispatch>
- <https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow>
- <https://docs.github.com/en/rest/reference/actions/#create-a-workflow-dispatch-event>

Before we move on, I repeat:
Before we move on, I repeat:
It is important that your `main` branch have the latest pkgdown workflow.
(Or whatever your default branch is called.)
At the time of writing, this means the `v2` tag in `r-lib/actions`.
(Or whatever your default branch is called.) At the time of writing, this means the `v2` tag in `r-lib/actions`.
The easiest way to get this is to install dev usethis and run `usethis::use_github_action("pkgdown")`.

## Construct a branch for the update

The overall goal is to create a package state from which to update the released site that corresponds to (HEAD of) a Git branch.
This package state should:

* Be based on the most recent GitHub and CRAN release.
* Incorporate all desired updates to your documentation, such as pkgdown config.
- Be based on the most recent GitHub and CRAN release.
- Incorporate all desired updates to your documentation, such as pkgdown config.

Create and checkout a branch based on the tag of the most recent CRAN release.
For example, if readr's latest release is 2.1.1:

```
```
git checkout -b update-pkgdown-2-1-1 v2.1.1
```

And here is the general pattern:

```
```
git checkout -b NEW-BRANCH-NAME NAME-OF-RELEASE-TAG
```

Now you should backport innovations from the future that you would like to retroactively apply to your released site.

Files you must update:

* `.github/workflows/pkgdown.yaml`
* `_pkgdown.yml`
* `Config/Needs/website` field of DESCRIPTION (And, probably, only this field!
In particular, do not mess with the version number.)
- `.github/workflows/pkgdown.yaml`
- `_pkgdown.yml`
- `Config/Needs/website` field of DESCRIPTION (And, probably, only this field! In particular, do not mess with the version number.)

Other likely candidates:
Other likely candidates:

* `README.Rmd` + `README.md`, e.g., if you've updated badges.
* Any documentation fixes that **apply to the released version**. This is the
only reason to touch anything below `R/` and even then it should only affect
roxygen comments. Don't forget to `document()` if you do this!
* Any new vignettes or articles that apply to the released version.
- `README.Rmd` + `README.md`, e.g., if you've updated badges.
- Any documentation fixes that **apply to the released version**. This is the only reason to touch anything below `R/` and even then it should only affect roxygen comments. Don't forget to `document()` if you do this!
- Any new vignettes or articles that apply to the released version.

Here are some tips on backporting specific changes into this branch.
If you are lucky, there are specific commits in your default branch that contain all the necessary changes.
In that case, we can cherry pick such a commit by its SHA:

```
```
git cherry-pick SHA
```

If that doesn't cover everything, for each file you want to update, identify a Git reference (meaning: a SHA, tag, or branch) where the file is in the desired state.
Checkout that specific file path from that specific ref:

```
```
git checkout REF -- path/to/the/file
```

For example, readr recently gained a new vignette that applies to the released version of readr, i.e. it does not document any dev-only features or functions.
Here's how to introduce the new vignette from HEAD of `main` into the current branch:

```
```
git checkout main -- vignettes/column-types.Rmd
```

Expand All @@ -249,14 +272,13 @@ Now we will use the `workflow_dispatch` GHA trigger.
Go to the Actions page of your repo, maybe via `usethis::browse_github_actions()`.
Click on the `pkgdown` workflow.

You should see "This workflow has a workflow_dispatch event trigger."
You should see "This workflow has a workflow_dispatch event trigger."\
(If you don't, that means you didn't do one of the pre-requisites, which is to update to `v2` of the pkgdown workflow.)

See the "Run workflow" button?
CLICK IT.
In the "Use workflow from" dropdown menu, select the branch you've just made and pushed.
CLICK IT. In the "Use workflow from" dropdown menu, select the branch you've just made and pushed.
This should kick off a pkgdown build-and-deploy and, specifically, it should cause updates to the **released** site.

You can keep this branch around for a while, in case you didn't get everything right the first time or if more things crop up that you'd like backport to the released site, before your next CRAN release.

## Problem-solving
Expand Down
Loading