From 8022dcc2df49fec144dcfe51c6ca278f169c16c3 Mon Sep 17 00:00:00 2001 From: Artokun Date: Sat, 8 Aug 2026 17:00:14 -0700 Subject: [PATCH 1/2] spec: surface CHANGELOG.md where the panel user actually is MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #758 — seanmcmagic, Discord: "What's new and fixed in 0.50.14 and will there be a 'bug fixes' or 'patch notes' in the panel somewhere to reference what has changed?" The panel updates from the Registry and the orchestrator runs @latest, so the version moves with no deliberate user action — the first signal something changed is often unexpected behavior read as a bug. #810 (this repo, merged) sends the version's CHANGELOG.md section to the Comfy Registry on publish — the Registry's Updates surface is no longer blank. That's a precursor, not a replacement: a user still has to go find the Registry page, same problem #758 describes for GitHub. Checked comfyui-mcp-mobile's existing "what's new" modal before assuming it was the template. It's hand-curated per release (changelog.dart, a Map with marketing-toned bullets written by hand) — a SEPARATE source of truth from any changelog file, not something that reads CHANGELOG.md. That contradicts #758's original framing ("this is a rendering problem not a content problem") in a way worth surfacing rather than quietly resolving: read CHANGELOG.md directly (single source of truth, technical tone) vs. hand-curate a second list (reader-facing tone, one more thing to remember on every release — CHANGELOG.md itself went three versions without an entry this week) vs. a hybrid default-with-override. Left as the one open decision this spec doesn't make. Checked: no "shown once, remember in storage" UI pattern exists in the panel today — its one-shot mechanisms are session/turn-scoped, not version-dismissal state. That storage-and-dismiss layer is new work here, not a port of something already in this repo. Draft ask, not scoped for build — for handoff to whoever picks this up. Co-Authored-By: Claude Opus 5 (1M context) --- docs/design/in-panel-changelog.md | 40 +++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/design/in-panel-changelog.md diff --git a/docs/design/in-panel-changelog.md b/docs/design/in-panel-changelog.md new file mode 100644 index 00000000..8a836101 --- /dev/null +++ b/docs/design/in-panel-changelog.md @@ -0,0 +1,40 @@ +# In-panel "what's new" — surfacing CHANGELOG.md where the user actually is + +**Status:** draft ask, not scoped for build. One design decision below is the crux of the whole spec. +**Origin:** `#758` — filed from seanmcmagic in Discord `#help`: *"What's new and fixed in 0.50.14 and will there be a 'bug fixes' or 'patch notes' in the panel somewhere to reference what has changed?"* +**Precursor, now built:** `#810` (this repo) sends the version's `CHANGELOG.md` section to the Comfy Registry on publish — so the Registry's own "Updates" surface is no longer blank. This spec is about a **second**, panel-native surface; #810 doesn't replace it, since a user has to go find the Registry page, same problem #758 describes for GitHub. + +## Why it matters (from the original filing) + +The panel updates from the Comfy Registry and the orchestrator runs `npx comfyui-mcp@latest` — **the version can move with no deliberate action by the user.** The first signal something changed is often behavior they didn't expect, which reads as a bug rather than a release. 0.50.x sharpened this: the tool surface consolidated (154→37) and the default tool mode flipped, so a user noticing different behavior has no in-product way to learn it was intentional. + +## A working precedent exists — but it's the wrong shape to copy directly + +`comfyui-mcp-mobile` already has exactly this UX: a one-shot "what's new" modal shown once per update (`lib/features/whats_new/`). Worth knowing precisely how it works before assuming it's the template: + +**It is hand-curated, not CHANGELOG.md-driven.** `changelog.dart` is a `Map` keyed by pubspec build number, with marketing-toned bullets written by hand for each release — a second, separate source of truth from any changelog file, deliberately punchier ("One-tap Diagnose on a failed render: when a queued render fails, tap Diagnose and the agent root-causes it") than a terse commit-derived line would be. + +That's a genuinely different design decision than #758's original framing assumed: *"CHANGELOG.md is already structured... this is a rendering problem not a content problem."* The mobile precedent says otherwise — it treats the *marketing framing* of a changelog entry as real content work, not just a rendering pass over existing data. + +## The actual open question — pick one, they're materially different builds + +1. **Read `CHANGELOG.md` directly** (the original #758 framing). Single source of truth, zero duplicate maintenance, but entries are commit-derived and technical — closer to what a maintainer writes than what a user wants read to them. Fine for "Fixed" items; awkward for framing something like the 154→37 consolidation as a positive change rather than a wall of PR links. +2. **Hand-curate a second list**, mirroring the mobile app exactly. Lets every entry be written for the reader, but is a second thing to remember to update on every release — and this project has already hit "shipped without updating X" more than once tonight alone (`CHANGELOG.md` itself went three versions without an entry, per `#810`'s own commit). +3. **Something hybrid** — e.g. `CHANGELOG.md` sections auto-populate a default, with an optional hand-written override for genuinely user-facing releases (a consolidation, a default flip) — deliberate work only where it earns its keep, silence otherwise. + +This is the decision that determines almost everything else about the build, so it's the one thing this spec leaves for the owner rather than guessing. + +## What else the spec (from #758) already establishes, regardless of which option above + +- **Delta, not the whole file.** Show what changed since the version the user was previously on, not the full history. +- **Prominent for major changes** (a consolidation, a default flip), quiet for a routine patch. +- **Distinguish Fixed from Changed** — *"this used to work differently on purpose"* is the specific message that stops a misfiled bug report, which is the whole reason this exists. + +## What's genuinely new infrastructure for this repo + +Checked: **no existing "shown once per version, remember in storage" UI pattern exists in the panel today.** The panel's one-shot mechanisms are session/turn-scoped (a provider-switch transcript replay, an armed context for the next message) — nothing persists "has this browser/user seen release X's notes" the way the mobile app's build-number tracking does. That storage-and-dismiss layer is new work here, not a port of something that already exists in this repo. + +## Explicitly not decided here + +- Whether this shares plumbing with the Registry changelog from `#810` (option 1/3 above would let it), or is fully independent (option 2). +- Where in the panel it surfaces — a toast, a settings-panel readout, a dismissible card in chat. Not scoped; depends partly on the sourcing decision above (a hand-curated marketing entry probably wants a more prominent presentation than an auto-pulled `CHANGELOG.md` diff). From 932a8369c84ec9b4a2cdbd42f7da559e6de29340 Mon Sep 17 00:00:00 2001 From: Artokun Date: Fri, 14 Aug 2026 16:57:25 -0700 Subject: [PATCH 2/2] docs(design): the in-panel changelog spec describes work that has SHIPPED MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This file was written as a draft ask with one open design decision left for the owner. Merging 325 commits of main into it makes that framing wrong: the decision was made and the feature is on main, so a document still presenting it as an unanswered question sends the next reader to design something that exists. Rewritten as the record of which option was taken and why. What is now on main: scripts/gen-changelog-json.mjs CHANGELOG.md -> web/changelog.json, run from scripts/set-version.mjs on the version bump web/js/lib/changelog-delta.js releasesSince / updateAnnouncement / summarizeReleases web/js/comfyui-mcp-panel.js fetches the JSON, renders [data-testid="panel-whats-new"], watermarks localStorage comfyui-mcp.panel.lastSeenVersion browser_tests/whats-new.spec.ts asserts it renders and announces once changelog-{base,delta,integrity} unit coverage That is option 1 (generate from CHANGELOG.md), and all three of #758's sourcing-independent requirements are met: delta not whole file, loud for a minor bump and quiet for a patch, Fixed distinguished from Changed. The "shown once per version" storage layer the old text called out as genuinely new work is the lastSeenVersion watermark. Every claim above was checked against the merged tree rather than carried over from the draft. Two corrections from the Copilot review, both of which were right: - The old text said #810 was "now built" and the Registry's Updates surface therefore no longer blank. #810 has not merged, so that surface is still blank. Described as open, and as a separate surface rather than a precursor. - "more than once tonight alone" was time-relative and unresolvable later. Replaced with the durable version of the same evidence: 0.11.42, 0.11.43 and 0.11.44 each shipped with no CHANGELOG.md section — the file jumps from 0.11.41 straight to 0.11.45. Verified in the merged tree, and it is a stronger argument than it was in the draft, because the gap propagates into the generated web/changelog.json, so those three versions are silent in the shipped panel surface too. Copilot cited "CHANGELOG.md:11-12" for that evidence. Those line numbers were correct when the review was written and now point at 0.14.40's Fixed section, so the claim is cited by version rather than by line. Refs artokun/comfyui-mcp#758 --- docs/design/in-panel-changelog.md | 142 ++++++++++++++++++++++-------- 1 file changed, 107 insertions(+), 35 deletions(-) diff --git a/docs/design/in-panel-changelog.md b/docs/design/in-panel-changelog.md index 8a836101..d0966d71 100644 --- a/docs/design/in-panel-changelog.md +++ b/docs/design/in-panel-changelog.md @@ -1,40 +1,112 @@ # In-panel "what's new" — surfacing CHANGELOG.md where the user actually is -**Status:** draft ask, not scoped for build. One design decision below is the crux of the whole spec. -**Origin:** `#758` — filed from seanmcmagic in Discord `#help`: *"What's new and fixed in 0.50.14 and will there be a 'bug fixes' or 'patch notes' in the panel somewhere to reference what has changed?"* -**Precursor, now built:** `#810` (this repo) sends the version's `CHANGELOG.md` section to the Comfy Registry on publish — so the Registry's own "Updates" surface is no longer blank. This spec is about a **second**, panel-native surface; #810 doesn't replace it, since a user has to go find the Registry page, same problem #758 describes for GitHub. +**Status:** shipped. This started as a draft ask with one open design decision; that decision +has since been made and built, so this file is now the record of *which* option was taken and +why — not a proposal awaiting an answer. +**Origin:** `#758` — filed from seanmcmagic in Discord `#help`: *"What's new and fixed in +0.50.14 and will there be a 'bug fixes' or 'patch notes' in the panel somewhere to reference +what has changed?"* +**Related, and still open:** `#810` (this repo) proposes sending each version's `CHANGELOG.md` +section to the Comfy Registry on publish, so the Registry's own "Updates" surface stops being +blank. It has not merged, so that surface is still blank today. It is a *different* surface +from this one and does not replace it: a user has to go and find the Registry page, which is +the same problem `#758` describes for GitHub. ## Why it matters (from the original filing) -The panel updates from the Comfy Registry and the orchestrator runs `npx comfyui-mcp@latest` — **the version can move with no deliberate action by the user.** The first signal something changed is often behavior they didn't expect, which reads as a bug rather than a release. 0.50.x sharpened this: the tool surface consolidated (154→37) and the default tool mode flipped, so a user noticing different behavior has no in-product way to learn it was intentional. - -## A working precedent exists — but it's the wrong shape to copy directly - -`comfyui-mcp-mobile` already has exactly this UX: a one-shot "what's new" modal shown once per update (`lib/features/whats_new/`). Worth knowing precisely how it works before assuming it's the template: - -**It is hand-curated, not CHANGELOG.md-driven.** `changelog.dart` is a `Map` keyed by pubspec build number, with marketing-toned bullets written by hand for each release — a second, separate source of truth from any changelog file, deliberately punchier ("One-tap Diagnose on a failed render: when a queued render fails, tap Diagnose and the agent root-causes it") than a terse commit-derived line would be. - -That's a genuinely different design decision than #758's original framing assumed: *"CHANGELOG.md is already structured... this is a rendering problem not a content problem."* The mobile precedent says otherwise — it treats the *marketing framing* of a changelog entry as real content work, not just a rendering pass over existing data. - -## The actual open question — pick one, they're materially different builds - -1. **Read `CHANGELOG.md` directly** (the original #758 framing). Single source of truth, zero duplicate maintenance, but entries are commit-derived and technical — closer to what a maintainer writes than what a user wants read to them. Fine for "Fixed" items; awkward for framing something like the 154→37 consolidation as a positive change rather than a wall of PR links. -2. **Hand-curate a second list**, mirroring the mobile app exactly. Lets every entry be written for the reader, but is a second thing to remember to update on every release — and this project has already hit "shipped without updating X" more than once tonight alone (`CHANGELOG.md` itself went three versions without an entry, per `#810`'s own commit). -3. **Something hybrid** — e.g. `CHANGELOG.md` sections auto-populate a default, with an optional hand-written override for genuinely user-facing releases (a consolidation, a default flip) — deliberate work only where it earns its keep, silence otherwise. - -This is the decision that determines almost everything else about the build, so it's the one thing this spec leaves for the owner rather than guessing. - -## What else the spec (from #758) already establishes, regardless of which option above - -- **Delta, not the whole file.** Show what changed since the version the user was previously on, not the full history. -- **Prominent for major changes** (a consolidation, a default flip), quiet for a routine patch. -- **Distinguish Fixed from Changed** — *"this used to work differently on purpose"* is the specific message that stops a misfiled bug report, which is the whole reason this exists. - -## What's genuinely new infrastructure for this repo - -Checked: **no existing "shown once per version, remember in storage" UI pattern exists in the panel today.** The panel's one-shot mechanisms are session/turn-scoped (a provider-switch transcript replay, an armed context for the next message) — nothing persists "has this browser/user seen release X's notes" the way the mobile app's build-number tracking does. That storage-and-dismiss layer is new work here, not a port of something that already exists in this repo. - -## Explicitly not decided here - -- Whether this shares plumbing with the Registry changelog from `#810` (option 1/3 above would let it), or is fully independent (option 2). -- Where in the panel it surfaces — a toast, a settings-panel readout, a dismissible card in chat. Not scoped; depends partly on the sourcing decision above (a hand-curated marketing entry probably wants a more prominent presentation than an auto-pulled `CHANGELOG.md` diff). +The panel updates from the Comfy Registry and the orchestrator runs `npx comfyui-mcp@latest` — +**the version can move with no deliberate action by the user.** The first signal something +changed is often behavior they didn't expect, which reads as a bug rather than a release. +0.50.x sharpened this: the tool surface consolidated (154→37) and the default tool mode +flipped, so a user noticing different behavior had no in-product way to learn it was +intentional. + +## A working precedent existed — but it was the wrong shape to copy directly + +`comfyui-mcp-mobile` already has this UX: a one-shot "what's new" modal shown once per update +(`lib/features/whats_new/`). It is worth knowing precisely how it works before assuming it is +the template: + +**It is hand-curated, not CHANGELOG.md-driven.** `changelog.dart` is a +`Map` keyed by pubspec build number, with marketing-toned bullets written +by hand for each release — a second, separate source of truth from any changelog file, +deliberately punchier ("One-tap Diagnose on a failed render: when a queued render fails, tap +Diagnose and the agent root-causes it") than a terse commit-derived line would be. + +That is a genuinely different design decision than `#758`'s original framing assumed: +*"CHANGELOG.md is already structured... this is a rendering problem not a content problem."* +The mobile precedent says otherwise — it treats the *marketing framing* of a changelog entry +as real content work, not just a rendering pass over existing data. + +## The decision: generate from CHANGELOG.md (option 1) + +Three options were on the table, and they were materially different builds: + +1. **Read `CHANGELOG.md` directly.** Single source of truth, zero duplicate maintenance, but + entries are commit-derived and technical — closer to what a maintainer writes than what a + user wants read to them. +2. **Hand-curate a second list**, mirroring the mobile app exactly. Lets every entry be + written for the reader, but is a second thing to remember to update on every release. +3. **Something hybrid** — `CHANGELOG.md` auto-populates a default, with an optional + hand-written override for genuinely user-facing releases. + +**Option 1 was taken**, and the deciding argument was maintenance realism rather than polish: +a second hand-maintained list is only as good as the discipline to update it, and this repo +has measurably missed that bar on the *first* list. **0.11.42, 0.11.43 and 0.11.44 each shipped +with no `CHANGELOG.md` section at all** — the file jumps straight from `0.11.41` to `0.11.45`. +That gap is still visible today, and it propagates: those three versions are absent from the +generated `web/changelog.json` too, so the panel has nothing to say about them either. A +surface that silently says nothing is worse than a terse one, because it is indistinguishable +from "nothing changed". + +Option 3 remains available on top of what shipped — the generator already produces a default +per release, so an override layer would be additive rather than a rewrite. + +## What shipped + +- **`scripts/gen-changelog-json.mjs`** parses `CHANGELOG.md` into `web/changelog.json`. + ComfyUI serves a custom node's `web/` directory at `/extensions//` while `CHANGELOG.md` + sits at the repo root, so the panel cannot fetch the markdown directly. Generated, never + hand-edited. It keeps only each entry's first sentence, which is written as the summary in + every entry — the full text stays in `CHANGELOG.md`. It runs from `scripts/set-version.mjs`, + so the shipped copy is refreshed as part of the version bump rather than by memory. +- **`web/js/lib/changelog-delta.js`** decides what to show and how loudly: + - `releasesSince()` — the delta, bounded above by the running `PANEL_VERSION` so a dev + running from a checkout is never told about versions their install does not contain. + - `updateAnnouncement()` — `"major"` when the minor component moved or several releases + landed at once, `"patch"` otherwise, and `"none"` on a first run or a downgrade. A browser + with no recorded version is greeted silently and told about the *next* change, which is the + first one that can honestly be called a change. + - `summarizeReleases()` — keeps each entry's section, so `Fixed` stays distinguishable from + `Changed`. +- **The surface itself** is wired in `web/js/comfyui-mcp-panel.js` (fetches + `/extensions/comfyui-mcp-panel/changelog.json`, renders `[data-testid="panel-whats-new"]`), + with the seen-version watermark in `localStorage` under + `comfyui-mcp.panel.lastSeenVersion`. +- **Tests:** `browser_tests/whats-new.spec.ts` asserts the notice actually renders in the + transcript and is announced only once; `changelog-delta`, `changelog-base` and + `changelog-integrity` cover the delta logic and the shape of `CHANGELOG.md` itself. + +This closes the three requirements `#758` established regardless of sourcing: **delta, not the +whole file**; **prominent for major changes, quiet for a routine patch**; and **`Fixed` +distinguished from `Changed`** — the last of which is the specific message that stops a misfiled +bug report, and the whole reason the feature exists. + +The "shown once per version, remember in storage" layer was genuinely new to this repo — the +panel's other one-shot mechanisms are session- or turn-scoped and none of them persist "has this +browser seen release X". That layer is the `lastSeenVersion` watermark above. + +## Still open + +- **Option 3's override layer** — a hand-written entry for the rare release that deserves + framing (a consolidation, a default flip), falling back to the generated text otherwise. + Deliberate work only where it earns its keep, silence otherwise. +- **Whether this shares plumbing with the Registry changelog in `#810`.** Both read the same + `CHANGELOG.md`, but by different paths: `#810` extracts one version's raw markdown section at + publish time for the Registry, while this parses every release into JSON at version-bump time + for the panel. Neither depends on the other, and merging them has not been attempted. +- **The empty-section problem is upstream of both.** Nothing here can surface notes for a + version that was never written down — 0.11.42–0.11.44 stay blank in every surface until + `CHANGELOG.md` itself gains those entries. + +Refs artokun/comfyui-mcp#758