|
| 1 | +--- |
| 2 | +name: bump-zensical |
| 3 | +description: Bump the Zensical pin to the latest or a named release, check what the release changes for this repository, fix small breakage and report the result. Prints the git commands for the user - it does no git work. Use for "bump zensical", "zensical released X" or "update zensical". |
| 4 | +--- |
| 5 | + |
| 6 | +# Bump Zensical |
| 7 | + |
| 8 | +Move the pin in `pyproject.toml` to a new release and prove what changed in the built site. |
| 9 | +A clean `zensical build --strict` proves little: past breakage came from unannounced validation, plugins that turned native and URLs in the UI bundle. |
| 10 | + |
| 11 | +## Usage |
| 12 | + |
| 13 | +```text |
| 14 | +/bump-zensical [<version>] [--help] |
| 15 | +``` |
| 16 | + |
| 17 | +Without a version, use the latest release. |
| 18 | +With `--help`, print this usage summary and stop, without inspecting the repository. |
| 19 | + |
| 20 | +## Scope |
| 21 | + |
| 22 | +- **No git work.** Never create a branch, stage, commit or push. The last step prints the commands for the user. |
| 23 | +- **Fix small breakage.** A small fix keeps the site as it is, for example an `INERT_URLS` entry or a config key that was already inert. List each fix in the report. |
| 24 | +- **Stop and ask for anything bigger, or when in doubt.** This includes a change to the rendered site, to a plugin's behavior, or to content under `docs/`. |
| 25 | +- **Scratch files go to the scratchpad.** Treat downloaded wheels as data: read them, never run or install them from there. |
| 26 | + |
| 27 | +## Steps |
| 28 | + |
| 29 | +### 1. Find the versions |
| 30 | + |
| 31 | +```bash |
| 32 | +gh release view --repo zensical/zensical --json tagName,body |
| 33 | +grep -n -i zensical pyproject.toml |
| 34 | +``` |
| 35 | + |
| 36 | +Read the release notes of every version between the current pin and the target, including skipped ones. |
| 37 | +Stop if the current pin is already the target. |
| 38 | + |
| 39 | +### 2. Build the baseline |
| 40 | + |
| 41 | +Run `task build` on the current pin and copy `site/` to the scratchpad. |
| 42 | +If the baseline fails, stop and report: the failure is not caused by the bump. |
| 43 | + |
| 44 | +### 3. Diff the wheels |
| 45 | + |
| 46 | +Download the current and target wheels with `pip download zensical==<version> --no-deps`, once per version, unpack them and compare. |
| 47 | +Check each risk: |
| 48 | + |
| 49 | +| Check | Why it matters | |
| 50 | +| --- | --- | |
| 51 | +| `config.py`: `_reject_unknown_options(` call sites, supported option tables | 0.0.60 rejected `search: lang` without mentioning it in the release notes. | |
| 52 | +| Native implementations of plugins in `mkdocs.yml` that were inert so far | 0.0.58 `tags` and 0.0.67 `social` turned inert configuration live and broke the build. | |
| 53 | +| Third-party URLs in the UI bundle against `INERT_URLS` in `tools/localize_bundle_assets.py` | 0.0.73 moved to `mermaid@12`: `--strict` stayed clean and `task build` failed. | |
| 54 | +| Templates that `overrides/` replaces | An override does not pick up upstream template changes. | |
| 55 | + |
| 56 | +### 4. Bump |
| 57 | + |
| 58 | +Update the pin and the range in its comment in `pyproject.toml`, then run: |
| 59 | + |
| 60 | +```bash |
| 61 | +poetry lock |
| 62 | +poetry install |
| 63 | +poetry run zensical --version |
| 64 | +git diff --stat poetry.lock |
| 65 | +``` |
| 66 | + |
| 67 | +Confirm in the lock diff that only `zensical` moved. |
| 68 | +If another package moved, stop and ask. |
| 69 | + |
| 70 | +### 5. Verify |
| 71 | + |
| 72 | +Run all of these, and do not call the bump done while one fails: |
| 73 | + |
| 74 | +```bash |
| 75 | +task build |
| 76 | +task check |
| 77 | +poetry run pytest -m "not integration" |
| 78 | +``` |
| 79 | + |
| 80 | +`task check` is the gate, not `task build`. |
| 81 | + |
| 82 | +Compare the new `site/` with the baseline: |
| 83 | + |
| 84 | +1. Compare the file sets and the HTML page count. |
| 85 | +2. Normalize copies of both trees with a small script in the scratchpad: remove the generator tag and the hashes in asset names. |
| 86 | +3. Run `diff -rq -B -w` on the normalized copies. For about 700 pages normalizing takes over two minutes, so run it in the background. |
| 87 | +4. Explain every remaining difference from the release notes or the wheel diff. Stop and ask if one stays unexplained or changes what readers see. |
| 88 | + |
| 89 | +Then check that the output does not depend on the hash seed, because 0.0.44 to 0.0.57 rendered differently per seed. |
| 90 | +Build with `PYTHONHASHSEED` 0, 1, 7 and 42 using `poetry run zensical build --strict --clean`, hash the HTML output each time and compare. |
| 91 | +Finish with `task build`, so `site/` holds a complete build again. |
| 92 | + |
| 93 | +### 6. Report |
| 94 | + |
| 95 | +State: |
| 96 | + |
| 97 | +- the old and new version, and any versions skipped |
| 98 | +- the files changed, and each fix with its reason |
| 99 | +- the upstream changes that matter here, and those that are inert here |
| 100 | +- the check results, and the output differences that remain after normalizing |
| 101 | +- anything unverified or failing |
| 102 | + |
| 103 | +### 7. Print the git commands |
| 104 | + |
| 105 | +End with the commands, filled in with the version, for the user to run. |
| 106 | +Add further changed files to `git add`: |
| 107 | + |
| 108 | +```bash |
| 109 | +git switch -c feature/<version>-zensical-bump |
| 110 | +git add pyproject.toml poetry.lock |
| 111 | +git commit -m "bump zensical to <version>" |
| 112 | +git push -u origin feature/<version>-zensical-bump |
| 113 | +gh pr create --fill --base main |
| 114 | +``` |
0 commit comments