Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
docs(release): check the metainfo in the pre-flight, drop the stale claims
Elian Doran7ab1b916e72e
diff --git a/.claude/skills/cutting-a-release/SKILL.md b/.claude/skills/cutting-a-release/SKILL.mdindex a339a0ad8a..fa7534b004 100644--- a/.claude/skills/cutting-a-release/SKILL.md+++ b/.claude/skills/cutting-a-release/SKILL.md@@ -1,6 +1,6 @@---name: cutting-a-release-description: Use when cutting, preparing, or debugging a Trilium release — bumping the monorepo version, tagging, or diagnosing a failed "Release" workflow run. Covers the ordered bump recipe (edit root package.json → chore:update-version → commit → v-prefixed tag → push), which of the TWO divergent version scripts to use (update-version for releases vs update-nightly-version for CI nightlies), why the CI version-consistency gate validates only 5 of the 8 files update-version writes, the exact `docs/Release Notes/Release Notes/<tag>.md` path the publish step hard-requires, the substring-based rc/beta "latest" labeling, and the RELEASE_PAT (not GITHUB_TOKEN) dependency. Also covers dispatching `nightly.yml` on a branch to test packaging on real CI runners (publish is gated on `main`; other refs upload artifacts). Bundles a pre-flight verifier that catches what the CI gate misses before you push the tag.+description: Use when cutting, preparing, or debugging a Trilium release — bumping the monorepo version, tagging, or diagnosing a failed "Release" workflow run. Covers the ordered bump recipe (edit root package.json → chore:update-version → commit → v-prefixed tag → push), which of the TWO divergent version scripts to use (update-version for releases vs update-nightly-version for CI nightlies), why the CI version-consistency gate validates only 5 of the 9 files update-version writes, the exact `docs/Release Notes/Release Notes/<tag>.md` path the publish step hard-requires, the substring-based rc/beta "latest" labeling, and the RELEASE_PAT (not GITHUB_TOKEN) dependency. Also covers dispatching `nightly.yml` on a branch to test packaging on real CI runners (publish is gated on `main`; other refs upload artifacts). Bundles a pre-flight verifier that catches what the CI gate misses before you push the tag.---# Cutting a Trilium release@@ -9,9 +9,9 @@ Releases are a tag push, not a button. Pushing a `v*` tag to `main` triggers `.g## Five traps that bite before you read anything else-1. **Edit the ROOT `package.json` only, then propagate.** Root is the single source of truth. `pnpm chore:update-version` (`scripts/update-version.ts:26-37`) reads root and writes 8 *other* package.jsons. Hand-editing the children desyncs the tree.+1. **Edit the ROOT `package.json` only, then propagate.** Root is the single source of truth. `pnpm chore:update-version` (`scripts/update-version.ts:27-46`) reads root, writes 8 *other* package.jsons and regenerates the Flathub metainfo's `<releases>` from `git for-each-ref`. Hand-editing the children desyncs the tree.2. **There are TWO version scripts — use `update-version`, not `update-nightly-version`.** The nightly one (`scripts/update-nightly-version.ts`) writes a *different* set of files and appends a `-test-YYMMDD-HHMMSS` suffix; it's CI-only. Running it for a release poisons the version. ([§ The two scripts](#the-two-version-scripts--pick-the-right-one))-3. **The CI version gate is a strict SUBSET — don't trust it.** `scripts/check-version-consistency.ts` validates only 5 files; `update-version` writes 8. The 4 gaps (standalone, edit-docs, pdfjs-viewer, trilium-core) can be wrong and still ship. Run the bundled pre-flight, which checks all 9.+3. **The CI version gate is a strict SUBSET — don't trust it.** `scripts/check-version-consistency.ts` validates only 5 files; `update-version` writes 8 package.jsons plus the metainfo. The 4 gaps (standalone, edit-docs, pdfjs-viewer, trilium-core) can be wrong and still ship. Run the bundled pre-flight, which checks all 9 plus the metainfo entry.4. **The release-notes file must exist BEFORE you tag, at a DOUBLED path.** `docs/Release Notes/Release Notes/v<X.Y.Z>.md` — note `Release Notes/Release Notes/` twice, and the `v` prefix in the filename. The publish step `ENOENT`s without it (`release.yml:155`).5. **The tag must be `v`-prefixed.** `release.yml` triggers only on `push: tags: v*` (`release.yml:3-5`). A bare `0.103.0` tag runs nothing, silently.@@ -21,7 +21,7 @@ Don't hand-roll a version checker — run the bundled pre-flight, a superset ofnpx tsx .claude/skills/cutting-a-release/scripts/preflight-release-check.mts v0.103.0```-It asserts all 9 package.jsons match, that the release-notes file exists at the doubled path, and warns on the rc/beta labeling footgun (trap below). Run it right before pushing the tag.+It asserts all 9 package.jsons match, that the metainfo `<release>` is the version being tagged, that the release-notes file exists at the doubled path, and warns on the rc/beta labeling footgun (trap below). Run it right before pushing the tag.## The recipe (order is load-bearing)@@ -29,9 +29,9 @@ It asserts all 9 package.jsons match, that the release-notes file exists at the|---|------|----------------|--------|| 1 | Write release notes | create `docs/Release Notes/Release Notes/v<X.Y.Z>.md` | filename = tag incl. `v`; publish hard-fails without it (`release.yml:155`) || 2 | Bump ROOT only | edit `package.json` `version` | do NOT hand-edit the other package.jsons |-| 3 | Propagate | `pnpm chore:update-version` | rewrites 8 package.jsons from root; never the reverse |-| 4 | Pre-flight | `npx tsx .claude/skills/cutting-a-release/scripts/preflight-release-check.mts v<X.Y.Z>` | catches the 4 files CI never checks + a missing notes file |-| 5 | Commit | `chore(release): prepare for v<X.Y.Z>` | stage every changed package.json + the new release-notes md |+| 3 | Propagate | `pnpm chore:update-version` | rewrites 8 package.jsons from root, and regenerates the metainfo `<releases>` Flathub displays; never the reverse |+| 4 | Pre-flight | `npx tsx .claude/skills/cutting-a-release/scripts/preflight-release-check.mts v<X.Y.Z>` | catches the 4 files CI never checks, a stale metainfo `<release>` + a missing notes file |+| 5 | Commit | `chore(release): prepare for v<X.Y.Z>` | stage every changed package.json, the metainfo + the new release-notes md || 6 | Tag (`v`-prefixed) | `git tag v<X.Y.Z>` | `release.yml` only fires on `v*` || 7 | Push commit + tag | `git push && git push --tags` | || 8 | Watch CI, then download + smoke-test the GitHub release | — | see [references/ci-pipeline.md](references/ci-pipeline.md) to map a red job |@@ -45,14 +45,14 @@ The upstream doc (`docs/Developer Guide/Developer Guide/Building/Releasing a new| npm script | `chore:update-version` (`package.json:38`) | `chore:ci-update-nightly-version` (`package.json:34`) || Use for | **releases — manual, this skill** | CI nightlies only || Invoked by | you | `nightly.yml:75`, `main-docker.yml:163` |-| Reads root version? | yes (`update-version.ts:27`) | yes, then mutates it |+| Reads root version? | yes (`update-version.ts:28`) | yes, then mutates it || Writes root? | **no** | **yes** (`update-nightly-version.ts:47`) |-| Files written | **8**: apps server/client/standalone/desktop/edit-docs + packages commons/pdfjs-viewer/trilium-core (`update-version.ts:30,34`) | **6**: root + apps server/client/standalone/desktop + pdfjs-viewer (`update-nightly-version.ts:50,55`) |+| Files written | **9**: apps server/client/standalone/desktop/edit-docs + packages commons/pdfjs-viewer/trilium-core, + the Flathub metainfo (`update-version.ts:31,35,44`) | **6**: root + apps server/client/standalone/desktop + pdfjs-viewer (`update-nightly-version.ts:50,55`) || Version shape | root version, verbatim | strips `-beta`, appends `-test-YYMMDD-HHMMSS` (`update-nightly-version.ts:19-24`) |The two sets diverge in both directions: `update-version` touches edit-docs/commons/trilium-core (nightly doesn't); nightly touches root (update-version doesn't). Run the wrong one and the tree desyncs — e.g. running nightly during a release stamps `0.103.0-test-260613-...` into root and leaves commons/trilium-core untouched.-## The CI gate checks 5 of 8 — verify all 9 yourself+## The CI gate checks 5 of 9 — verify all 10 yourself`scripts/check-version-consistency.ts:5-11` validates exactly:@@ -60,9 +60,9 @@ The two sets diverge in both directions: `update-version` touches edit-docs/commpackage.json, apps/server, apps/client, apps/desktop, packages/commons```-(stripping a leading `v` from the tag arg, lines 20-22). But `update-version` writes **8**, so **`apps/standalone`, `apps/edit-docs`, `packages/pdfjs-viewer`, and `packages/trilium-core` are written but never validated.** A stale version in any of those passes the `sanity-check` job (`release.yml:30-31`) and ships.+(stripping a leading `v` from the tag arg, lines 20-22). But `update-version` writes **9**, so **`apps/standalone`, `apps/edit-docs`, `packages/pdfjs-viewer`, `packages/trilium-core` and the Flathub metainfo are written but never validated.** A stale version in any of those passes the `sanity-check` job (`release.yml:30-31`) and ships.-This isn't theoretical — real release-prep commits touched *different* file subsets because `update-version` only produces a git diff for files that were previously stale: `v0.103.0` (`44f5be88b7`) changed 7 package.jsons including pdfjs-viewer; `v0.102.1` (`8ac9daa5d3`) changed 6, no pdfjs-viewer. The CI gate would not have caught a wrong value in the un-checked four either time. The bundled pre-flight checks all 9 — use it instead of trusting the gate.+This isn't theoretical — real release-prep commits touched *different* file subsets because `update-version` only produces a git diff for files that were previously stale: `v0.103.0` (`44f5be88b7`) changed 7 package.jsons including pdfjs-viewer; `v0.102.1` (`8ac9daa5d3`) changed 6, no pdfjs-viewer. The CI gate would not have caught a wrong value in the un-checked four either time. The bundled pre-flight checks all 9, and the metainfo `<release>` the gate has never known about — use it instead of trusting the gate.## The publish step — exact strings that hard-fail@@ -84,9 +84,9 @@ This isn't theoretical — real release-prep commits touched *different* file su- **Lockfile is NOT touched by a version-only bump.** Internal deps are `workspace:*` (resolve to `link:`, no version recorded — `grep 0.103.0 pnpm-lock.yaml` = 0 hits), and the release-prep commits above never touched `pnpm-lock.yaml`. CI installs `--frozen-lockfile` *before* any bump (`nightly.yml:71` then bump at `:75`; `release.yml:28`). `--frozen-lockfile` only fails if the release *also* changes a real dependency. The upstream doc's "run `pnpm i`" step is precautionary and misnames the file.- **Tag must be `v`-prefixed** — `release.yml:3-5` triggers only on `v*`. A bare `0.103.0` tag does nothing.- **`RELEASE_PAT`, not `GITHUB_TOKEN`** — `release.yml:161`. Confirmed the only PAT in the release flow; winget (downstream) uses a separate `WINGET_PAT` (`release-winget.yml:19`).-- **Flathub does NOT publish itself.** `release.yml` has no Flathub job; `release-flathub.yml` is `workflow_dispatch`-only, so a release ships to Flathub only once someone runs `gh workflow run "Release to Flathub" -f ref=v<X.Y.Z>` and merges the pull request it opens against `flathub/org.triliumnotes.Trilium`. Needs the `FLATHUB_PAT` secret. See the `packaging-for-flathub` skill.+- **Flathub opens a pull request, it does not publish.** `release.yml` has no Flathub job; `release-flathub.yml` runs on `release: published` (prereleases skipped) and opens a pull request against `flathub/org.triliumnotes.Trilium` that someone still has to merge. `gh workflow run "Release to Flathub" -f ref=v<X.Y.Z>` re-runs it by hand. Needs the `FLATHUB_PAT` secret. See the `packaging-for-flathub` skill.- **Don't hand-edit child package.jsons** — let `update-version` propagate from root, or they desync silently past the 5-file gate.-- **`update-version` is idempotent but partial in the diff** — it rewrites all 8 unconditionally; only the previously-stale ones show up in `git status`. "Only 6 files changed" is normal and not a sign you missed one.+- **`update-version` is idempotent but partial in the diff** — it rewrites all 8 unconditionally; only the previously-stale ones show up in `git status`. "Only 6 files changed" is normal and not a sign you missed one. The metainfo is the exception: its `<releases>` is *derived*, not accumulated — the newest 5 `vX.Y.Z` tags, dated by `creatordate`, with the version being prepared dated today until its own tag supplies the date. A re-run after tagging therefore settles on the tag date, and a checkout without tags fails the script rather than truncating the list.## Testing packaging on CI: dispatching `nightly.yml` on a branchdiff --git a/.claude/skills/cutting-a-release/scripts/preflight-release-check.mts b/.claude/skills/cutting-a-release/scripts/preflight-release-check.mtsindex 978bd607a1..192d0a5ccf 100644--- a/.claude/skills/cutting-a-release/scripts/preflight-release-check.mts+++ b/.claude/skills/cutting-a-release/scripts/preflight-release-check.mts@@ -112,7 +112,21 @@ function main(): void {}}- // 2. The publish step hard-requires the release-notes file at the DOUBLED path.+ // 2. The newest <release> is the version Flathub displays, and the manifest installs+ // the metainfo from the tagged checkout, so a stale entry ships as-is.+ const metainfoRel = join("apps", "desktop", "flatpak", "org.triliumnotes.Trilium.metainfo.xml");+ const metainfo = existsSync(join(root, metainfoRel))+ ? readFileSync(join(root, metainfoRel), "utf-8") : "";+ const newest = /<release version="([^"]+)"/.exec(metainfo)?.[1];+ if (newest === expectedVersion) {+ console.log(`[ OK ] ${metainfoRel} newest <release> = ${newest} (CI gate does NOT check this)`);+ } else {+ failures.push(`${metainfoRel}: newest <release> is ${newest ?? "absent"}, expected ${expectedVersion}`);+ console.log(`[FAIL] ${metainfoRel} newest <release> = ${newest ?? "absent"}, expected `+ + `${expectedVersion} — run pnpm chore:update-version (CI gate does NOT check this)`);+ }++ // 3. The publish step hard-requires the release-notes file at the DOUBLED path.const notesRel = join("docs", "Release Notes", "Release Notes", `${tag}.md`);if (existsSync(join(root, notesRel))) {console.log(`[ OK ] ${notesRel} exists`);@@ -121,7 +135,7 @@ function main(): void {console.log(`[FAIL] ${notesRel} — softprops/action-gh-release will ENOENT (release.yml:155)`);}- // 3. rc/beta labeling — release.yml:159-160 substring-matches the ref.+ // 4. rc/beta labeling — release.yml:159-160 substring-matches the ref.if (tag.includes("rc")) {console.log(`[INFO] tag contains "rc" -> prerelease=true, make_latest=false (intended for a release candidate)`);} else if (/beta|alpha|dev|test/i.test(tag)) {diff --git a/.claude/skills/packaging-for-flathub/SKILL.md b/.claude/skills/packaging-for-flathub/SKILL.mdindex 58466fac8a..c4f080f6af 100644--- a/.claude/skills/packaging-for-flathub/SKILL.md+++ b/.claude/skills/packaging-for-flathub/SKILL.md@@ -78,6 +78,11 @@ that SHA.nothing is left for it to cache-isolate. `trilium.sh` is the one exception, copied intothe packaging repo so a reviewer reads the sandbox behavior without opening thecheckout.++ That is also why the metainfo's `<releases>` — the version Flathub displays — has to be+ right in the commit that gets tagged. `pnpm chore:update-version` regenerates it from+ the newest five `vX.Y.Z` tags, so it is never hand-edited and never accumulates drift;+ the version being prepared is dated today until its own tag supplies the date.- **Sandboxed data dir, narrow filesystem access.** `trilium.sh` sets`TRILIUM_DATA_DIR` to `$XDG_DATA_HOME/trilium-data` (i.e. inside `~/.var/app`), fallingback to host `~/.local/share/trilium-data` when that exists; a `flatpak override` wins.@@ -208,13 +213,9 @@ build adjudicates it).`repo` is needlessly broad, `workflow` is not needed). Fine-grained equivalent: owner`flathub`, Contents + Pull requests read/write — but org policy may require approval.Without it the workflow's clone step fails.-2. **A `<release>` entry in the metainfo at tag time.** The trigger now opens a packaging- PR for every stable release, and the metainfo installs from that tag's checkout — so- whatever `<releases>` holds when the tag is cut is what Flathub shows. Latest-only,- never backfill.-3. **The packaging repo's README**, which still describes staged scripts and the old+2. **The packaging repo's README**, which still describes staged scripts and the oldpnpm/ASAR reasoning.-4. **The data migration for existing users**, which the EOL-rebase does not perform and+3. **The data migration for existing users**, which the EOL-rebase does not perform andwhich no permission can substitute for (see "Sandboxed data dir"). The old Flathub app,the Forge `.flatpak` and every `.deb`/AppImage keep notes at host`~/.local/share/trilium-data`; the new app starts on an empty@@ -223,11 +224,11 @@ build adjudicates it).`flatpak override --filesystem=…` in the release notes, or exposing the legacydatabase read-only for a one-time import. Settle it **before** the rebase — after it,the old app is gone and the surprise is the user's.-5. **EOL-rebase the old app**: PR `flathub.json` with+4. **EOL-rebase the old app**: PR `flathub.json` with`end-of-life-rebase: org.triliumnotes.Trilium` to `flathub/com.github.zadam.trilium`(needs `end-of-life` too, or the linter errors). Old app ships 0.63.7/2024 on EOL23.08 to ~71k installs.-6. Parked polish: carousel-spec screenshots (window ≤1000×700 or 2× at ≤2000×1400, shadow+5. Parked polish: carousel-spec screenshots (window ≤1000×700 or 2× at ≤2000×1400, shadow+ rounded corners), `<branding>` colors (leaf-green `#cfe8c0` light / `#254d18` dark;compare peers via `flathub.org/api/v2/appstream/<id>` → `.branding`), metainfodescription refresh, and the `--no-playwright-browsers` flag worth filing upstream.