From 9183b23a57d586a8b2d58aa4fae2b723a086ce3d Mon Sep 17 00:00:00 2001 From: CJ Yetman Date: Wed, 11 Sep 2024 15:04:43 +0200 Subject: [PATCH] allow manual deploy-with-clean pkgdown deployment This seems like a lot, but [see here](https://7tonshark.com/posts/github-actions-ternary-operator/#dealing-with-null-inputs) why it is difficult to safely achieve. I discovered that when `JamesIves/github-pages-deploy-action` runs with `clean: false` (which is default in the recommended [r-lib pkgdown action](https://github.com/r-lib/actions/blob/e6be4b3706e0f39bc7a4cf4496a5f2c4cb840040/examples/pkgdown.yaml#L48)), old pages on the pkgdown site that are no longer needed are not removed, e.g. if there was a vignette/article but it has since been removed. This creates a situation where out-of-date, potentially misleading, information may still be accessible at its old URL even if it is not shown in the menu. As a specific example, I found that the pactaverse pkgdown site was pointing to the TDM article on the pacta.portfolio.allocate pkgdown site and it was still accessible, even though the vignette had been removed and it was not directly accessible from the Articles menu on the pacta.portfolio.allocate pkgdown site. The `clean: false` option was [added to r-lib's example pkgdown.yml](https://github.com/r-lib/actions/commit/dabdc15316de2c2ca1837e1df08d5feb1b55607a) to facilitate pkgdown setups that build separate prod and dev pkgdown sites (like our r2dii/P4B pkgs). This makes sense, because if you're only building the sub dev version of the site, you don't want to wipe out the prod top-level site while you're at it. But it does prevent you from clearing out old site files that should no longer be there. With the r2dii packages, the "release" version of the pkgdown website shows the menu text in black instead of white, and it appears it cannot be fixed until some of those old files are wiped out, which cannot be achieved without using the `clean: true` option. A tedious solution to this is to temporarily change `clean: false` to `clean: true` in the pkgdown.yml workflow, merge it so it will run on main, let the pkgdwon site build and deploy (with the `clean: true` option in place), and then presumably change it back (?). However, this would affect only the "dev" version of pkgdown website, if/until a new release was made. A somewhat more complicated solution, but one that can remain in place is to allow a manual triggering of the pkdown site build and deploy with an optional `clean: true` specification. This way, if you notice that a clean needs to be done, you can trigger it manually and specify `clean: true`, but otherwise (on merge or manual trigger with default options) the build/deploy will run as normal. That's what I've done here. Additionally, and importantly, when triggering the pkgdown workflow manually, you can specify a branch or a *tag* (release) to run it on. In order to make this work for our current problem (updating the release version of the pkgdown site with the new pkgdown config), we will need to make a new branch based on the v0.2.1 tag, commit the new pkgdown config to to that new branch, manually trigger the pkgdown action on that new branch with the `clean: true` option, and then we can delete that new branch (without ever having to make a PR much less merging it). --- .github/workflows/pkgdown.yaml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml index 88099b30..9fc04138 100644 --- a/.github/workflows/pkgdown.yaml +++ b/.github/workflows/pkgdown.yaml @@ -8,6 +8,11 @@ on: release: types: [published] workflow_dispatch: + inputs: + clean: + type: boolean + description: 'Clean all files from old site.' + default: false name: pkgdown @@ -43,6 +48,6 @@ jobs: if: github.event_name != 'pull_request' uses: JamesIves/github-pages-deploy-action@v4.6.4 with: - clean: false + clean: ${{ github.event_name == 'workflow_dispatch' && inputs.clean || false }} branch: gh-pages folder: docs