spec: surface CHANGELOG.md where the panel user actually is (#758) - #815
Draft
artokun wants to merge 3 commits into
Draft
spec: surface CHANGELOG.md where the panel user actually is (#758)#815artokun wants to merge 3 commits into
artokun wants to merge 3 commits into
Conversation
#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<buildNumber, entry> 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) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Documents options for surfacing release notes within the panel and identifies required version-dismissal infrastructure.
Changes:
- Compares changelog sourcing strategies.
- Defines established requirements and open UX decisions.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| ## 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). |
|
|
||
| **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. |
11 tasks
artokun
added a commit
that referenced
this pull request
Aug 14, 2026
… own diagnosis The CHANGELOG is a shipped artefact — #815 surfaces it inside the panel and changelog-delta reads it to tell a user what changed under them after an unattended update — so its shape is testable and was not tested. This is the fourth pass over this area (#1197, #1202, #1203) and every prior defect was found by a human reading the file afterwards. WHAT THE GUARD FOUND, beyond the duplicate sections I went looking for: 1. The 0.2.0/0.3.0/0.4.0/0.4.1 pairs are NOT duplicates. They are version-number COLLISIONS holding genuinely different content: `0.4.1 - 06-26` announces graph_set_node_mode, while `0.4.1 - 06-17` announces the Connect button that replaced auto-spawn after the Registry scanner flagged 0.4.0. Two real releases reused one number. Merging them would assert a release that shipped both — the same fabrication #1203 had to undo. They are recorded as fact, with the exemption list asserted EXHAUSTIVE so it cannot rot into a blanket hole. 2. The single ordering break is where that older history block begins. Same treatment. 3. 0.11.84 was a FALSE POSITIVE in my first draft of this guard: its body is the deliberate `_No user-facing changes._`. A release that truthfully reports having nothing to report is correct; the guard demanding a list item was the defect. AND A CORRECTION TO MY OWN CLAIM ON THE PR. I wrote that the generator emits two bodies per release. It cannot: buildEntry produces exactly one `## [ver] - today()` section, and line 375 aborts when the version already exists. The two-section mechanism is upstream in the release PROCESS and I have not located it — recorded as unknown rather than left as a plausible-sounding guess, which is the failure this session has already produced four times in one changelog note. What IS real in the generator: the highlights dedupe is /\(#(\d+)\)/g, which cannot match (comfyui-mcp#1478). So work described upstream-first is never recognised as covered and gets re-listed by its panel PR number. The guard is RED on the three recent pairs by design. It stays red until the cause is found, which is the point of committing it first. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
artokun
added a commit
that referenced
this pull request
Aug 14, 2026
…ne version (#1219) * chore: claim — every release since 0.14.31 writes TWO changelog sections Claiming the duplicate-section regression. Diagnosis in the PR body: the release commit emits both an auto-generated section and a promoted-highlights section for the same version, with two different date sources (local vs UTC). * test(changelog): assert the shipped CHANGELOG's shape, and correct my own diagnosis The CHANGELOG is a shipped artefact — #815 surfaces it inside the panel and changelog-delta reads it to tell a user what changed under them after an unattended update — so its shape is testable and was not tested. This is the fourth pass over this area (#1197, #1202, #1203) and every prior defect was found by a human reading the file afterwards. WHAT THE GUARD FOUND, beyond the duplicate sections I went looking for: 1. The 0.2.0/0.3.0/0.4.0/0.4.1 pairs are NOT duplicates. They are version-number COLLISIONS holding genuinely different content: `0.4.1 - 06-26` announces graph_set_node_mode, while `0.4.1 - 06-17` announces the Connect button that replaced auto-spawn after the Registry scanner flagged 0.4.0. Two real releases reused one number. Merging them would assert a release that shipped both — the same fabrication #1203 had to undo. They are recorded as fact, with the exemption list asserted EXHAUSTIVE so it cannot rot into a blanket hole. 2. The single ordering break is where that older history block begins. Same treatment. 3. 0.11.84 was a FALSE POSITIVE in my first draft of this guard: its body is the deliberate `_No user-facing changes._`. A release that truthfully reports having nothing to report is correct; the guard demanding a list item was the defect. AND A CORRECTION TO MY OWN CLAIM ON THE PR. I wrote that the generator emits two bodies per release. It cannot: buildEntry produces exactly one `## [ver] - today()` section, and line 375 aborts when the version already exists. The two-section mechanism is upstream in the release PROCESS and I have not located it — recorded as unknown rather than left as a plausible-sounding guess, which is the failure this session has already produced four times in one changelog note. What IS real in the generator: the highlights dedupe is /\(#(\d+)\)/g, which cannot match (comfyui-mcp#1478). So work described upstream-first is never recognised as covered and gets re-listed by its panel PR number. The guard is RED on the three recent pairs by design. It stays red until the cause is found, which is the point of committing it first. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * fix(changelog): merge the three duplicated releases, and stop guarding in the wrong place DATA. 0.14.31, 0.14.32 and 0.14.33 each carried two headings whose bodies described the SAME work through different identifiers — the panel PR (#1206/#1208/#1211) and the upstream mcp issue (comfyui-mcp#1448/#1467/#1478). Merged into one section per version, citing both ids, keeping the more specific wording. Safe precisely because the two bodies were the same change; the 0.2.0-0.4.1 pairs are NOT and are left alone. web/changelog.json regenerated, since the panel reads that rather than the markdown. DATE. today() read LOCAL calendar fields while hand-written notes used UTC, which is why the pairs sat a day apart: the release commits were authored near 23:00-0600. Now one source, UTC, via toISOString — a changelog is read across timezones and by changelog-delta, so "the day it shipped" has to mean one thing. AND I REMOVED MY OWN FIX, because it could not fire. I had added a post-write duplicate-heading assertion here. Testing it showed the pre-write check returns first in the only ordering where a duplicate exists at write time — and in the ordering that actually caused this, the hand-written section was added AFTER the script exited, so at write time there was exactly one heading. It was dead code shaped like a guard, which this session has already established reads as coverage and is worse than nothing. The reasoning is left in place so it does not get re-added. A script cannot defend against an edit made after it exits. The check that DOES catch this is browser_tests/unit/changelog-integrity.test.mjs (5f66e35), which asserts the committed file's shape and so runs on the release PR regardless of which step wrote the second heading. The pre-write "nothing to do" message now also explains the failure mode it can mask: notes under a pre-numbered heading ship WITHOUT the auto-generated commit body, because that branch returns before writing it. Also widened then REVERTED the highlights dedupe: matching (comfyui-mcp#N) as well as (#N) cannot work, because the two are different numbers in different namespaces, and it would let an upstream issue number silently suppress an unrelated panel PR's commit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(changelog): the dedupe comment pointed at a guard I had deleted Codex P2. The comment explaining why cross-namespace dedupe was reverted said the duplication was "prevented by the post-write assertion at the bottom of this file" — and that assertion was removed in the same change, as unreachable. So the comment claimed a protection that does not exist, in the file whose entire subject is a guard that could not see what it claimed to. Stated accurately now: a highlight citing comfyui-mcp#1478 and a commit carrying panel PR #1211 for the same change will BOTH be listed, as two bullets in one section. changelog-integrity.test.mjs catches duplicate version HEADINGS; it does not compare bullet text, so that redundancy is unguarded and only a human reading the notes will catch it. Smaller than the duplicate sections this issue was about — one release saying a thing twice, rather than two releases — and closing it needs an identifier map the repo does not have. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
…PPED
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft ask for handoff — not scoped for build. Full spec:
docs/design/in-panel-changelog.md. Closes/refs #758.Why
The panel updates from the Registry, the orchestrator runs
@latest— the version moves with no deliberate user action, so unexpected behavior reads as a bug rather than a release note nobody saw.Precursor, already built
#810(merged) sends the version'sCHANGELOG.mdsection to the Comfy Registry on publish — the Registry's own Updates surface is no longer blank. Doesn't replace this: the user still has to go find that page.Checked the mobile app's existing precedent — it's the wrong shape to copy blindly
comfyui-mcp-mobile's "what's new" modal is hand-curated per release, a separateMap<buildNumber, entry>with marketing-toned bullets — not something that reads a changelog file. That contradicts #758's original framing ("this is a rendering problem not a content problem") in a way worth surfacing rather than quietly resolving.The one open decision (owner's call, determines the whole build)
CHANGELOG.mddirectly — single source of truth, but technical/commit-derived tone.#810's commit).What's genuinely new here
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. New infrastructure, not a port of something already in this repo.
Not decided
Where it surfaces (toast / settings readout / dismissible chat card), and whether it shares plumbing with #810.