Document nightly catch-up; stop rendering version footer

Two related cleanups noticed during the v2026.513.0 release run:

1. Release ceremony was missing the nightly catch-up step. After the
   release PR merges, main is ahead of nightly by the release commits
   and nightly's .sync-state.json still says branch_mode "nightly"
   with the old base_release_tag. The merge-down + branch_mode flip is
   manual the first time and must be done by hand. Added as the 4th
   post-merge follow-up, plus a troubleshooting row for the symptom
   "nightly run reports release mode unexpectedly".

2. paperclip_version frontmatter was being rendered as a visible
   "Documenting Paperclip vX.Y.Z" footer on every release-stamped
   page. Treat the field as internal metadata only: build-release.mjs
   still parses and surfaces it into content.json (queryable for
   tooling), but the SPA no longer prints it on-page. Updated the
   skill's builder note to match.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
This commit is contained in:
Aron PrinsandClaude Opus 4.7 committed 2026-05-14 10:07:29 +02:00
1 parent 32b755400e
commit fc74da5f6b
3 files changed
+15 -13

No files matched your search

+14 -2
View File
@@ -125,7 +125,7 @@ When a new parent release tag drops (`v2026.X.Y`):
- Voice quality of any newly-authored pages — these go live on `docs.paperclip.ing` the moment you merge.
- Frontmatter `paperclip_version` correctly stamped on changed pages.
4. Merge to `main` when satisfied.
5. **After merge — three follow-ups:**
5. **After merge — four follow-ups:**
- Tag the merge commit:
```sh
git checkout main && git pull
@@ -133,7 +133,18 @@ When a new parent release tag drops (`v2026.X.Y`):
git push --tags
```
- Verify `.sync-state.json` on `main` now shows `base_release_tag: v2026.X.Y` and `base_release_sha` matches.
- Cloudflare Pages auto-deploys on push to `main`. Confirm `docs.paperclip.ing` renders the new "Documenting Paperclip v2026.X.Y" footer.
- Cloudflare Pages auto-deploys on push to `main`. Confirm `docs.paperclip.ing` is rebuilt successfully.
- **Catch `nightly` back up.** After the release PR merges, `main` is ahead of `nightly` by the release commits and `nightly`'s `.sync-state.json` still reads `branch_mode: "nightly"` with the old `base_release_tag`. Merge `main` down and flip `branch_mode` back, otherwise the next `/sync-docs` run sees a stale state file:
```sh
git checkout nightly && git pull
git merge main
# Edit .sync-state.json on nightly:
# "branch_mode": "nightly" (the merge inherited "release" from main)
# Leave base_release_tag at v2026.X.Y — that's now the correct cumulative-diff base.
git commit -am "nightly: catch up to v2026.X.Y release"
git push
```
The skill's "merge main → nightly at start of each nightly run" rule (see [Daily operation](#daily-operation)) is what keeps subsequent runs aligned, but the **first** post-release merge-down has to be done by hand because the `branch_mode` flip is manual.
**Large gaps (8+ release tags behind)**
@@ -247,4 +258,5 @@ Read it weekly. Items get moved out as they're addressed.
| Skill won't auto-detect mode | `.sync-state.json` missing or malformed | Seed from `scripts/sync/state.example.json`, set `base_release_tag` to current parent state |
| Verify-edit reports false-positive `env-var-missing` | Env var defined in CLI / plugin source not in watcher's source list | Add to FOLLOW-UPS, or (preferred) extend `verify-edit.mjs`'s env-var source list |
| First nightly run after release produces empty manifest | Cumulative diff is empty because nightly's base bumped | Verify `.sync-state.json` `base_release_tag` matches parent's latest release tag |
| Nightly run reports `release` mode unexpectedly | `branch_mode` wasn't flipped back to `nightly` after the last release merge-down | Edit `.sync-state.json` on `nightly`: set `branch_mode` to `"nightly"`, commit, push. See [Release ceremony](#release-ceremony) step 5 follow-up #4 |
| `wrangler pages deploy` fails | Cloudflare auth | `wrangler login` |
-10
View File
@@ -798,16 +798,6 @@ function appendPageFeedback(article, page, file) {
</span>
`;
article.appendChild(block);
// If the build pipeline parsed a `paperclip_version` from the page's YAML
// frontmatter, surface it as a small sibling line under the feedback row.
const version = page.frontmatter?.paperclip_version;
if (version) {
const versionBlock = document.createElement('div');
versionBlock.className = 'page-version';
versionBlock.textContent = `Documenting Paperclip ${version}`;
article.appendChild(versionBlock);
}
}
function insertMetaRow(article, page) {
+1 -1
View File
@@ -217,7 +217,7 @@ If all pass: make the mechanical edit directly. Examples: append a row to `envir
**Batched-release mode is exhaustive.** In `--batched` release mode, every doc-relevant manifest entry in EACH window must be processed — no subsampling. This is the equivalent of how nightly mode handles every entry of its cumulative manifest. Wet-run subsampling (e.g. "pick 2 representative entries") was scope-control for testing, not skill design. Skipping entries in real catchup runs leaves docs incomplete. Per-window tier classification still applies — auto-merge and PR entries both get processed; the only thing that varies is how many entries each window contains (some releases are small).
> **Builder note.** `site/build-release.mjs` strips and surfaces YAML frontmatter into `content.json` (the SPA renders `paperclip_version` as a "Documenting Paperclip <version>" footer). Authored pages SHOULD include `paperclip_version` in release mode — the voice rule below is live, not aspirational.
> **Builder note.** `site/build-release.mjs` strips YAML frontmatter from the rendered markdown body and surfaces parsed fields into `content.json`. `paperclip_version` is **internal metadata only** — the SPA does NOT render it on-page. Authored pages SHOULD still include `paperclip_version` in release mode so the field is queryable from `content.json` (e.g., to drive future per-page version badges or release-PR diff tooling) and so the source of truth for "which release does this page document" lives next to the prose.
**PR tier** (judgment calls):
- Spawn a subagent per entry, in parallel where possible. Give each: