diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b8d9f18b..67b4e6bf 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -33,7 +33,19 @@ on: - '.github/workflows/docs.yml' release: types: [published] + # Publish a version by hand — for backfilling a release that predates this site, or re-cutting + # one. Leave `version` empty to refresh `latest` exactly as a push to main does. workflow_dispatch: + inputs: + version: + description: 'Version to publish (e.g. 0.6.2). Empty refreshes `latest`.' + required: false + default: '' + set_latest: + description: 'Also point the `latest` alias at it' + type: boolean + required: false + default: false # Least privilege at the top: read-only. Each job widens ONLY what it needs. permissions: @@ -107,12 +119,26 @@ jobs: env: EVENT: ${{ github.event_name }} TAG: ${{ github.event.release.tag_name }} + INPUT_VERSION: ${{ inputs.version }} + INPUT_SET_LATEST: ${{ inputs.set_latest }} run: | set -euo pipefail if [ "$EVENT" = "release" ]; then version="${TAG#v}" [ -n "$version" ] || { echo "::error::release event with an empty tag_name"; exit 1; } mike deploy --push "$version" + elif [ "$EVENT" = "workflow_dispatch" ] && [ -n "${INPUT_VERSION}" ]; then + # A hand-published version: same immutable directory a release would create, so a + # release that predates this site can be backfilled without re-tagging it. + case "$INPUT_VERSION" in + [0-9]*.[0-9]*.[0-9]*) : ;; + *) echo "::error::version must look like 1.2.3 (no leading v); got '$INPUT_VERSION'"; exit 1 ;; + esac + if [ "$INPUT_SET_LATEST" = "true" ]; then + mike deploy --push --update-aliases "$INPUT_VERSION" latest + else + mike deploy --push "$INPUT_VERSION" + fi else mike deploy --push --update-aliases latest mike set-default --push latest diff --git a/docs/index.md b/docs/index.md index c66c6803..fe7a119f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -31,3 +31,13 @@ keep an organisation's repositories gated. The package also ships an unrelated uptime monitor, `stayawake-health-check` — see [configuration](reference/configuration.md#the-uptime-monitor-configurlsyml). + +## Which version you are reading + +Each release keeps its own copy of these pages, and the version selector at the top switches +between them. `latest` follows the current documentation. + +Documented versions begin at **0.6.2**. Earlier releases were published before this site existed, +so there are no pages describing them — rather than reprinting today's documentation under an older +number, which would describe behaviour those versions do not have. If you are running something +earlier, `saw --version` and `saw -h` describe the copy you actually have.