Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
48 changes: 48 additions & 0 deletions .github/workflows/maintenance.yml
Original file line number Diff line number Diff line change
@@ -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"
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand Down
Loading
Loading