diff --git a/.github/workflows/maintenance.yml b/.github/workflows/maintenance.yml new file mode 100644 index 0000000..60fbb7f --- /dev/null +++ b/.github/workflows/maintenance.yml @@ -0,0 +1,48 @@ +name: "🚧 Maintenance" + +# Put up a maintenance page at https://neotokyorebuild.github.io/ntre-wiki/, or take it down. +# Check the box to put the page up: every address into the wiki then shows it, and the +# wiki moves to offline/ on the gh-pages branch, untouched. Run it again unchecked to bring +# the wiki back as it was. While the page is up, 🚀 Deploy and ⏪ Rollback still work: they +# publish to the hidden wiki under offline/, so a fix can be checked there before the page +# comes down. +on: + workflow_dispatch: + inputs: + maintenance: + description: "Show the maintenance page and hide the wiki. Leave unchecked to take the page down and bring the wiki back." + type: boolean + default: false + +permissions: + contents: write # push the gh-pages branch + pages: read # check that GitHub Pages is set up + deployments: read # wait for GitHub Pages to publish + +# Shares the deploy's queue, so it never runs at the same time as a deploy or a rollback. +concurrency: + group: deploy + cancel-in-progress: false + +jobs: + maintenance: + name: Maintenance + if: github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + steps: + # The page is a single file, and ./deploy maintenance needs neither the game's + # repositories nor the Python environment, so the setup action is skipped. + - uses: actions/checkout@v7 + with: + path: ntre-wiki + fetch-depth: 0 + + - name: ./deploy maintenance ${{ inputs.maintenance && 'on' || 'off' }} + working-directory: ntre-wiki + env: + GH_TOKEN: ${{ github.token }} + STATE: ${{ inputs.maintenance && 'on' || 'off' }} + run: | + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + ./deploy maintenance "$STATE" diff --git a/AGENTS.md b/AGENTS.md index bd4fd0e..39cd99c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,8 +10,8 @@ A monorepo for the NEOTOKYO Rebuild (NT;RE) wiki. `wiki/` is the wiki, built wit - `setup`, `serve`: set up a checkout once, and preview the wiki - `check`: the checks every change must pass, the strict build and `tools/check_data.py`. CI runs it on every pull request, and `deploy` runs it first. -- `deploy`: publishes a new version of the wiki (the 🚀 Deploy workflow runs it); `deploy rollback VERSION` points `latest` at an earlier version (the ⏪ Rollback workflow runs it); `deploy list` and `deploy delete VERSION...` manage deployed versions, locally only -- `.github/workflows/`: `ci.yml` (🏗 CI, every pull request into `main`), `deploy.yml` (🚀 Deploy, run by hand) and `rollback.yml` (⏪ Rollback, run by hand with the target version as its input; it shares the deploy's queue). `.github/actions/setup/` checks out `neo` and `neoAssets` next to the repository and runs `./setup`, for both. +- `deploy`: publishes a new version of the wiki (the 🚀 Deploy workflow runs it); `deploy rollback VERSION` points `latest` at an earlier version (the ⏪ Rollback workflow runs it); `deploy maintenance on|off` puts up the maintenance page `wiki/maintenance.html` and hides the wiki under `offline/` on `gh-pages`, or brings it back (the 🚧 Maintenance workflow runs it, with a checkbox for on); `deploy list` and `deploy delete VERSION...` manage deployed versions, locally only +- `.github/workflows/`: `ci.yml` (🏗 CI, every pull request into `main`), `deploy.yml` (🚀 Deploy, run by hand), `rollback.yml` (⏪ Rollback, run by hand with the target version as its input) and `maintenance.yml` (🚧 Maintenance, run by hand with a checkbox). Rollback and Maintenance share the deploy's queue. `.github/actions/setup/` checks out `neo` and `neoAssets` next to the repository and runs `./setup`, for every workflow but Maintenance, which needs neither. - `wiki/mkdocs.yml`: site config, including the sidebar menu (`nav`). A new page needs a nav entry. - `wiki/docs/**/*.md`: pages. Folders follow the menu (`weapons/rifles/zr68-s.md`); a folder's `index.md` is its section page. - `wiki/data/*.json`: gameplay data extracted from the NT;RE source, one record per value with a `source` citation @@ -26,7 +26,7 @@ Set up with `./setup`: it creates `wiki/.venv` and records the `neo` and `neoAss ## Deploying -The wiki is published at https://neotokyorebuild.github.io/ntre-wiki/, from the `gh-pages` branch of `NeotokyoRebuild/ntre-wiki`. The 🚀 Deploy workflow runs `./deploy`, which has `mike` build `main` into a new version folder (by default the next minor version after the one `latest` points at, skipping versions that already exist; the next major when chosen; or an exact version, which must be M.m), points `latest` and the site's root at it, and pushes. It refuses a dirty tree, a commit that isn't on `main` in `NeotokyoRebuild/ntre-wiki`, a failing `./check`, symlinks, and changes outside the new version, `latest/` and mike's root files. The published address is set only in `deploy`: don't hard-code it in `mkdocs.yml` or in pages. Old versions are removed only by hand, locally: `./deploy delete` lists what goes and what stays, asks before deleting, and refuses the version `latest` points at. Never delete versions without the maintainer's say-so. Never use `mkdocs gh-deploy`: it replaces the whole branch, and every earlier version with it. GitHub Pages rejects symlinks, which is why `mkdocs.yml` sets mike's `alias_type: copy`. Deploying publishes to a public site: do it only when asked. +The wiki is published at https://neotokyorebuild.github.io/ntre-wiki/, from the `gh-pages` branch of `NeotokyoRebuild/ntre-wiki`. The 🚀 Deploy workflow runs `./deploy`, which has `mike` build `main` into a new version folder (by default the next minor version after the one `latest` points at, skipping versions that already exist; the next major when chosen; or an exact version, which must be M.m), points `latest` and the site's root at it, and pushes. It refuses a dirty tree, a commit that isn't on `main` in `NeotokyoRebuild/ntre-wiki`, a failing `./check`, symlinks, and changes outside the new version, `latest/` and mike's root files. The published address is set only in `deploy`: don't hard-code it in `mkdocs.yml` or in pages. Old versions are removed only by hand, locally: `./deploy delete` lists what goes and what stays, asks before deleting, and refuses the version `latest` points at. Never delete versions without the maintainer's say-so. While the maintenance page is up, deploy, rollback, list and delete pass mike `--deploy-prefix offline` and work on the hidden wiki, and `deploy maintenance off` moves the tree under `offline/` back to the root unchanged. Never use `mkdocs gh-deploy`: it replaces the whole branch, and every earlier version with it. GitHub Pages rejects symlinks, which is why `mkdocs.yml` sets mike's `alias_type: copy`. Deploying publishes to a public site: do it only when asked. A ruleset on `main` requires a pull request that passes 🏗 CI, and blocks force pushes and deletion. No approval is needed, except that `.github/CODEOWNERS` makes the maintainer's approval required for changes to `.github/`, `deploy`, `check` and `setup`; add any new file the workflows run to it. A ruleset on `gh-pages` blocks force pushes. Contributors merge their own PRs once CI passes. The maintainer, and agents working with them, push to `main` directly through the admin bypass. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da21493..878db46 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -161,5 +161,5 @@ Contributions reach `main` through pull requests: commit on a branch, push it, a ## What not to touch -- `deploy` and `.github/workflows/` publish the site. Maintainers deploy with the 🚀 Deploy workflow. +- `deploy`, `wiki/maintenance.html` and `.github/workflows/` publish the site. Maintainers deploy with the 🚀 Deploy workflow, and take the wiki offline with the 🚧 Maintenance workflow. - Don't modify the `neo` or `neoAssets` checkouts. diff --git a/README.md b/README.md index 253d362..691c975 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,8 @@ cd ntre-wiki - `setup`: sets up a checkout once: asks where your checkouts of the game's repositories are, and creates the Python environment - `serve`: previews the wiki at http://127.0.0.1:8000/ - `check`: the checks every change must pass: the strict build, and the data checked against the game's code -- `deploy`: publishes the wiki and rolls it back (the 🚀 Deploy and ⏪ Rollback workflows run it), and lists and deletes deployed versions -- `.github/workflows/`: the 🏗 CI, 🚀 Deploy and ⏪ Rollback workflows +- `deploy`: publishes the wiki, rolls it back and puts up the maintenance page (the 🚀 Deploy, ⏪ Rollback and 🚧 Maintenance workflows run it), and lists and deletes deployed versions +- `.github/workflows/`: the 🏗 CI, 🚀 Deploy, ⏪ Rollback and 🚧 Maintenance workflows ## Contributing @@ -40,6 +40,8 @@ The wiki is published at https://neotokyorebuild.github.io/ntre-wiki/. Maintaine To undo a bad deploy, run the ⏪ Rollback workflow with the version to go back to (such as `0.2`). It points `latest` at that version without rebuilding anything. It doesn't change `main`, so fix or revert the change there before the next deploy, which publishes `main` again. +To take the wiki offline, run the 🚧 Maintenance workflow with its box checked. Every address into the wiki then shows a maintenance page, `wiki/maintenance.html`. The wiki itself moves, untouched, to `offline/` on the `gh-pages` branch, where it still works at https://neotokyorebuild.github.io/ntre-wiki/offline/latest/ for anyone who has the address. While the page is up, 🚀 Deploy and ⏪ Rollback still work, on the hidden wiki, so you can check a fix at that address first. Run the workflow again with the box unchecked to take the page down and bring the wiki back, with any deploys made in the meantime. + To remove old versions, run these locally. `delete` shows what it will delete and keep, asks first, and never deletes the version `latest` points at: ```sh diff --git a/deploy b/deploy index 401cfcf..bcbe37d 100755 --- a/deploy +++ b/deploy @@ -8,7 +8,9 @@ # ./deploy rollback VERSION point `latest` at a deployed version, without a build # ./deploy list list the deployed versions # ./deploy delete VERSION... delete versions from the site, after asking -# ./deploy --dry-run ... a deploy, rollback or delete, without the push +# ./deploy maintenance on put up the maintenance page and hide the wiki +# ./deploy maintenance off take the maintenance page down and bring the wiki back +# ./deploy --dry-run ... any of these but list, without the push # # minor and major count from the version `latest` points at (the first deploy is 0.1, or # 1.0 for major), and skip versions that already exist by applying the same step again: @@ -20,6 +22,13 @@ # deployed. The ⏪ Rollback workflow runs rollback. Delete never touches # the version `latest` points at. The published address is set here and nowhere else # (override with NTRE_WIKI_URL). +# +# The 🚧 Maintenance workflow runs maintenance. `on` moves the whole site into offline/ and +# puts wiki/maintenance.html at the root, as index.html and as 404.html, so every address +# into the wiki shows the page. The wiki still works at offline/latest/ for anyone who +# knows the address: it is out of the way, not secret. `off` moves the site back exactly as +# it was. While the page is up, deploy, rollback, list and delete work on the wiki under +# offline/, and the page stays up. set -euo pipefail cd "$(dirname "$0")" @@ -28,13 +37,15 @@ if [[ ${1:-} == --dry-run ]]; then DRY_RUN=1; shift; fi REPO_SLUG=NeotokyoRebuild/ntre-wiki BRANCH=gh-pages +HIDDEN=offline export NTRE_WIKI_URL=${NTRE_WIKI_URL:-https://neotokyorebuild.github.io/ntre-wiki/} export NO_MKDOCS_2_WARNING=1 say() { printf '\033[1m==> %s\033[0m\n' "$*"; } die() { printf '\033[31merror:\033[0m %s\n' "$*" >&2; exit 1; } -[[ -x wiki/.venv/bin/mike ]] || die "no Python environment yet: run ./setup" +# Only maintenance runs without mike, so its workflow can skip the setup. +[[ ${1:-} == maintenance || -x wiki/.venv/bin/mike ]] || die "no Python environment yet: run ./setup" export PATH="$PWD/wiki/.venv/bin:$PATH" # The remote for NeotokyoRebuild/ntre-wiki, found by URL: origin in CI, often upstream locally. @@ -47,8 +58,10 @@ find_remote() { } # Bring the local gh-pages up to date; fails rather than overwrite a local branch that -# differs. Sets BASE (the remote tip, empty before the first deploy) and RESET (how to -# undo a local commit on top of it). +# differs. Sets BASE (the remote tip, empty before the first deploy), RESET (how to +# undo a local commit on top of it), SITE (where the wiki is on the branch: the root, or +# $HIDDEN/ while the maintenance page is up) and MIKE (the options every mike command takes, +# which point it at SITE). fetch_pages() { say "Fetching $REMOTE/$BRANCH" if git ls-remote --exit-code --heads "$REMOTE" "$BRANCH" >/dev/null; then @@ -62,9 +75,16 @@ fetch_pages() { BASE= RESET="git branch -D $BRANCH" fi + SITE= + MIKE=(--remote "$REMOTE" --branch "$BRANCH") + if [[ -n $BASE ]] && git rev-parse -q --verify "$BASE:$HIDDEN" >/dev/null; then + SITE=$HIDDEN/ + MIKE+=(--deploy-prefix "$HIDDEN") + say "The maintenance page is up: working on the wiki under $SITE" + fi } -versions_json() { if [[ -n $BASE ]]; then git show "$BRANCH:versions.json"; else echo '[]'; fi; } +versions_json() { if [[ -n $BASE ]]; then git show "$BRANCH:${SITE}versions.json"; else echo '[]'; fi; } # A version is M.m: two whole numbers without leading zeros (0.4, 1.10; not 01.2 or 1.2.3). is_version() { [[ $1 =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; } @@ -73,7 +93,7 @@ is_version() { [[ $1 =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; } versions_re() { local out= v; for v in "$@"; do out+=${out:+|}${v//./\\.}; done; printf '%s' "$out"; } # Guard rails for the local commit: no symlinks (GitHub Pages rejects them), a fast-forward -# of the remote, and every changed path matching $1. +# of the remote, and every changed path matching $1, if given. check_result() { say "Checking the result" local links outside @@ -81,6 +101,7 @@ check_result() { [[ -z $links ]] || die "symlinks on $BRANCH, which GitHub Pages rejects: $links (undo with: $RESET)" [[ -n $BASE ]] || return 0 git merge-base --is-ancestor "$BASE" "$BRANCH" || die "$BRANCH isn't a fast-forward of $REMOTE/$BRANCH (undo with: $RESET)" + [[ -n $1 ]] || return 0 outside=$(git diff --name-only "$BASE" "$BRANCH" | grep -v -E "$1" || true) [[ -z $outside ]] || die "$2: $outside (undo with: $RESET)" } @@ -112,6 +133,14 @@ publish() { fi } +# Only a clean tree whose HEAD is on main gets published. +check_source() { + say "Checking the source" + [[ -z $(git status --porcelain) ]] || die "uncommitted changes: commit and merge them first" + git fetch -q "$REMOTE" main + git merge-base --is-ancestor HEAD FETCH_HEAD || die "HEAD $(git rev-parse --short HEAD) isn't on $REMOTE/main" +} + # ./deploy [minor|major|M.m] [TITLE] deploy_version() { local sha kind version title @@ -121,10 +150,7 @@ deploy_version() { *) is_version "$kind" || die "not a version: $kind (use minor, major, or M.m, such as 0.4)" ;; esac - say "Checking the source" - [[ -z $(git status --porcelain) ]] || die "uncommitted changes: commit and merge them first" - git fetch -q "$REMOTE" main - git merge-base --is-ancestor HEAD FETCH_HEAD || die "HEAD $(git rev-parse --short HEAD) isn't on $REMOTE/main" + check_source sha=$(git rev-parse --short HEAD) ./check fetch_pages @@ -154,15 +180,15 @@ print("%d.%d" % target)' "$kind") say "Deploying $version ($title) from $sha to $BRANCH" ( cd wiki - mike deploy --remote "$REMOTE" --branch "$BRANCH" --update-aliases --title "$title" \ + mike deploy "${MIKE[@]}" --update-aliases --title "$title" \ -m "Deploy the wiki $version from $sha" "$version" latest ) # A new version identical to what latest/ already serves would only add a duplicate to # the version menu: stop instead, and discard the local commit. The sitemaps don't # count: they carry the build date. if [[ $kind == minor || $kind == major ]] && [[ -n $BASE ]] \ - && git rev-parse -q --verify "$BASE:latest" >/dev/null \ - && git diff --quiet "$BASE:latest" "$BRANCH:$version" -- . ':(exclude)sitemap.xml' ':(exclude)sitemap.xml.gz'; then + && git rev-parse -q --verify "$BASE:${SITE}latest" >/dev/null \ + && git diff --quiet "$BASE:${SITE}latest" "$BRANCH:$SITE$version" -- . ':(exclude)sitemap.xml' ':(exclude)sitemap.xml.gz'; then git branch -f "$BRANCH" "$BASE" local current current=$(versions_json | python3 -c 'import json, sys; print(next((v["version"] for v in json.load(sys.stdin) if "latest" in v["aliases"]), "latest"))') @@ -172,13 +198,13 @@ print("%d.%d" % target)' "$kind") fi ( cd wiki - mike set-default --remote "$REMOTE" --branch "$BRANCH" --template redirect.html \ + mike set-default "${MIKE[@]}" --template redirect.html \ -m "Point the wiki at $version" latest ) - check_result "^($(versions_re "$version")|latest)/|^(versions\.json|index\.html|\.nojekyll)$" \ - "the deploy changed files outside $version/ and latest/" + check_result "^$SITE($(versions_re "$version")|latest)/|^$SITE(versions\.json|index\.html|\.nojekyll)$" \ + "the deploy changed files outside $SITE$version/ and ${SITE}latest/" publish - say "Published ${NTRE_WIKI_URL}latest/ ($version from $sha)" + say "Published ${NTRE_WIKI_URL}${SITE}latest/ ($version from $sha)" } # ./deploy rollback VERSION: moves `latest` (a copy of a version's folder) to another @@ -204,12 +230,12 @@ print(current)' "$target") say "Moving latest from ${current:-nothing} to $target" ( cd wiki - mike alias --remote "$REMOTE" --branch "$BRANCH" --update-aliases \ + mike alias "${MIKE[@]}" --update-aliases \ -m "Roll the wiki back to $target (latest was ${current:-unset})" "$target" latest ) - check_result "^latest/|^versions\.json$" "the rollback changed files outside latest/" + check_result "^${SITE}latest/|^${SITE}versions\.json$" "the rollback changed files outside ${SITE}latest/" publish - say "Published ${NTRE_WIKI_URL}latest/ ($target)" + say "Published ${NTRE_WIKI_URL}${SITE}latest/ ($target)" } # ./deploy list: each version with its aliases, and when and from which commit it was @@ -260,13 +286,68 @@ print("Keep: ", ", ".join(v + (" (" + ", ".join(d["aliases"]) + ")" if d["alias fi ( cd wiki - mike delete --remote "$REMOTE" --branch "$BRANCH" -m "Delete the wiki $* from the site" "$@" + mike delete "${MIKE[@]}" -m "Delete the wiki $* from the site" "$@" ) - check_result "^($(versions_re "$@"))/|^versions\.json$" "the delete changed files outside the deleted versions" - [[ -z $(git diff --diff-filter=AM --name-only "$BASE" "$BRANCH" | grep -v '^versions\.json$' || true) ]] \ + check_result "^$SITE($(versions_re "$@"))/|^${SITE}versions\.json$" "the delete changed files outside the deleted versions" + [[ -z $(git diff --diff-filter=AM --name-only "$BASE" "$BRANCH" | grep -v "^${SITE}versions\\.json$" || true) ]] \ || die "the delete added or changed files instead of only removing them (undo with: $RESET)" publish - say "Deleted $* from ${NTRE_WIKI_URL}" + say "Deleted $* from ${NTRE_WIKI_URL}$SITE" +} + +# Commit tree $1 on top of the remote tip as the local gh-pages, unless it is already the +# tree there. Returns 1 when there is nothing to commit. +commit_pages() { + local tree=$1 message=$2 commit + [[ $tree != $(git rev-parse "$BASE^{tree}") ]] || return 1 + commit=$(git commit-tree -p "$BASE" -m "$message" "$tree") + git update-ref "refs/heads/$BRANCH" "$commit" "$BASE" +} + +# Report a run that changed nothing, in the workflow's summary too. +nothing_to_do() { + [[ -z ${GITHUB_ACTIONS:-} ]] || echo "::notice title=Nothing to do::$1" + say "Nothing to do: $1" +} + +# ./deploy maintenance on|off: the gh-pages tree is rebuilt by hand, with no checkout. `on` +# also refreshes the page while it is up, after a change to wiki/maintenance.html. +maintenance() { + [[ $# -eq 1 && ( $1 == on || $1 == off ) ]] || die "use ./deploy maintenance on, or ./deploy maintenance off" + [[ $1 == off ]] || check_source + fetch_pages + [[ -n $BASE ]] || die "nothing is deployed yet" + local site page empty tree + site=$(git rev-parse "$BASE:$SITE") + + if [[ $1 == off ]]; then + [[ -n $SITE ]] || { nothing_to_do "the maintenance page isn't up"; return 0; } + say "Taking down the maintenance page and bringing the wiki back from $SITE" + commit_pages "$site" "Take down the maintenance page and bring the wiki back" + check_result "" "" + [[ $(git rev-parse "$BRANCH^{tree}") == "$site" ]] \ + || die "the wiki at the root isn't what was under $SITE (undo with: $RESET)" + publish + say "Published ${NTRE_WIKI_URL}: the wiki is back" + return 0 + fi + + page=$(git hash-object -w wiki/maintenance.html) + empty=$(git hash-object -w /dev/null) + tree=$(printf '100644 blob %s %s +' "$empty" .nojekyll "$page" 404.html "$page" index.html \ + | { cat; printf '040000 tree %s %s +' "$site" "$HIDDEN"; } | git mktree) + if ! commit_pages "$tree" "Put up the maintenance page and hide the wiki under $HIDDEN/"; then + nothing_to_do "the maintenance page is already up, and unchanged" + return 0 + fi + say "Putting up the maintenance page and hiding the wiki under $HIDDEN/" + check_result "" "" + [[ $(git rev-parse "$BRANCH:$HIDDEN") == "$site" ]] \ + || die "the wiki under $HIDDEN/ isn't what was deployed (undo with: $RESET)" + publish + say "Published the maintenance page at ${NTRE_WIKI_URL}. The wiki is at ${NTRE_WIKI_URL}$HIDDEN/latest/" } find_remote @@ -274,5 +355,6 @@ case ${1:-} in list) list_versions ;; rollback) shift; rollback_to "$@" ;; delete) shift; delete_versions "$@" ;; + maintenance) shift; maintenance "$@" ;; *) deploy_version "$@" ;; esac diff --git a/wiki/maintenance.html b/wiki/maintenance.html new file mode 100644 index 0000000..34d8dcf --- /dev/null +++ b/wiki/maintenance.html @@ -0,0 +1,71 @@ + + + + + + + + NT;RE Wiki: down for maintenance + + + +
+ + + + + +

The wiki is down for maintenance

+

The NT;RE Wiki is being updated and will be back soon.

+
+

The game's code is on GitHub at NeotokyoRebuild/neo.

+
+ +