diff --git a/.cursor/skills/cms-changelog-sync/SKILL.md b/.cursor/skills/cms-changelog-sync/SKILL.md index 4b0e205acf..fbd8639005 100644 --- a/.cursor/skills/cms-changelog-sync/SKILL.md +++ b/.cursor/skills/cms-changelog-sync/SKILL.md @@ -7,7 +7,8 @@ description: >- index.json, Cloud ?template=, user UTM, GitHub PRs). HARD GATE: before any cms:sync/cms:publish for Cloud, always ask the user to manually confirm Cloud; default push is comfyui only. Use when updating changelog/index.mdx for CMS, - running cms:prepare/cms:sync, Strapi release-notes, published-versions.json, + partner node deprecation/removal/replacement/EOL bullets, running + cms:prepare/cms:sync, Strapi release-notes, published-versions.json, CMS staging, simplifying release notes for the notification popup, or cms:publish to go live. --- @@ -108,14 +109,15 @@ Config: `.github/scripts/cms/cms-config.json` → `simplify` | Rule | Value | |------|-------| -| Total bullets per version | **up to 10** (`max_bullets_total: 10`) | +| Total bullets per version | **up to 10** (`max_bullets_total: 10`), a target for optional items. Lifecycle bullets are mandatory and may take the version over it | | Section headings max | **3** (`max_sections: 3`) | | Section order | **New Open-Source Model Support** → **Partner Node Updates** → **New Node Updates** (optional) | | Words per version | ~60–120 | | Bullet format | `[**Name**](pr_url): 6–12 words with one key trait` | | PR links | **Keep** when source has them; never invent URLs | -| New Node Updates | **Optional by default.** Omit from CMS popup even if docs has **New Nodes**; add only when a human explicitly asks | -| Drop | Bug fixes, performance, pure Load3D plumbing, internal refactors, **ComfyUI-WIKI dependency bumps** (see below), and New Nodes unless requested. **Do not drop** partner removals, deprecations, or EOL | +| New Node Updates | **Optional by default** for ordinary new built-in nodes. Omit from CMS popup even if docs has **New Nodes**, unless a human asks **or** the version has a core-node lifecycle change (deprecation, removal, replacement, EOL) | +| Node lifecycle | **Never drop** partner removals, deprecations, replacements, or EOL. Deprecation, removal, replacement, and EOL belong in **Partner Node Updates** (partner/API) or **New Node Updates** (core/built-in). See **Node lifecycle (deprecation, removal, replacement, EOL)** | +| Drop | Bug fixes, performance, pure Load3D plumbing, internal refactors, **ComfyUI-WIKI dependency bumps** (see below), and ordinary New Nodes unless requested. Do **not** drop lifecycle items | Style: principle-only prompt in `cms-simplify-prompt.ts` (no concrete version examples — avoids LLM contamination). @@ -123,7 +125,7 @@ Style: principle-only prompt in `cms-simplify-prompt.ts` (no concrete version ex **Copy length (local vs Cloud):** Cloud popup users skim. After merge, shorten Cloud bullets so they do not list every node, mode, or task type. One short clause is enough: added the model, or one capability. Local CMS (`staging/en/`) and docs `changelog/index.mdx` can keep the fuller scope (which nodes, which modes). Do not shorten local to match Cloud. -Example: docs/local may say H3 Max landed on text-to-video, first-last-frame, and reference nodes. Cloud: `Added H3 Max model support`. +Example: docs/local may say H3 Max landed on text-to-video, first-last-frame, and reference nodes. Cloud: `Added H3 Max model support`. Lifecycle bullets stay on Cloud; only shorten the wording, do not omit the deprecation, removal, replacement, or EOL. **OSS bullets name the model, not the plumbing.** After `prepare:en`, rewrite open-source bullets to match names users already see in `tutorials/` (checkpoint family, `fl2va` / `ref2va`, ControlNet Union, and similar). If a tutorial page already documents the model, the popup should say we added support for that model. Do not describe loader internals: optional VAE, keyframe wiring, skipped LoRA keys, unless that is the only user-facing change. @@ -163,7 +165,33 @@ When curating `changelog/index.mdx` from ComfyUI git history, **do not add bulle Also omit standalone **frontend package semver bumps** unless tied to a user-visible fix worth its own bullet. CMS simplify must never promote WIKI-only items into popup copy even if they appear in the full docs block. -Example staging shape (placeholders only). **New Node Updates** is optional and usually omitted: +## Node lifecycle (deprecation, removal, replacement, EOL) + +When curating `changelog/index.mdx` or simplifying CMS staging, **do not skip** user-facing node lifecycle changes. These are not "minor cleanup." Users need to know a node or model option is going away, already gone, or swapped for a successor. + +| Change | What to write | Where | +|--------|---------------|--------| +| **Deprecated** | Mark the node or model as deprecated. Include the date or version if the source has one | Partner or node section below | +| **Removed** | Say what was removed (node, model option, or API). Prefer "removed" over vague "updated" | Same | +| **Replaced** | Name **both** the old node/model and the replacement. One bullet can cover the swap | Same | +| **EOL / retired** | State EOL or retirement, plus what users should use instead when a successor exists | Same | + +**Section placement:** + +- **Partner / API nodes** (including a partner model option dropped from an existing node): put the bullet under **Partner Node Updates**. Partner removals, deprecations, replacements, and EOL are first-class partner updates, not an optional extra. +- **Core / built-in nodes** (non-partner): put the bullet under **New Node Updates** (or **New Nodes** if that is the heading already in the docs block). For CMS, emit **New Node Updates** when the only reason to include that section is a lifecycle change, even if nobody asked to list ordinary new nodes. + +**Writing rules:** + +- Prefer a title that states the event: `Kling EOL`, `Reve deprecated`, `Google Veo` with "Removed …" in the body. Do not bury a removal inside an unrelated "added X" bullet. +- If the same PR both adds a successor and removes the old node, you may use one bullet that names both. If they are separate products, use two bullets (add under the usual new-item style; lifecycle under this rule). +- Keep Cloud copy short, but still mention the event: `Removed retiring Veo 2 and Veo 3.0`. Do not drop lifecycle bullets when shortening Cloud. +- CMS simplify must **keep** these items. They are not in the Drop list. Do not treat "removed" or "deprecated" as internal refactors. +- **Overflow:** lifecycle bullets outrank the bullet limit. If a version has more items than `max_bullets_total`, keep every lifecycle bullet and drop optional items first (ordinary new-node additions, then minor partner tweaks). Never omit a deprecation, removal, replacement, or EOL to stay under the limit. + +## Example staging shape + +Placeholders only. **New Node Updates** is optional for ordinary new nodes, and required when a core/built-in lifecycle change is in the source: ```markdown **New Open-Source Model Support** @@ -171,13 +199,15 @@ Example staging shape (placeholders only). **New Node Updates** is optional and **Partner Node Updates** * [**Partner Node**](source_url): Partner scope and capability from the release data +* [**Partner Node EOL**](source_url): Removed or retired partner nodes, and the replacement when one exists ``` -Only when a human asks to include nodes: +Only when a human asks to include ordinary new nodes, **or** when a core/built-in node is deprecated, removed, replaced, or EOL: ```markdown **New Node Updates** * [**Node Name**](source_url): What the node does and why it matters +* [**Node Name deprecated**](source_url): Deprecated or removed; name the replacement when one exists ``` Sync adds header: `# ComfyUI vX.Y.Z` via `format-cms-content.ts`. @@ -237,7 +267,7 @@ Requires **Bun**. Loads `.env.local` automatically. ### New release version -1. Add full `` block to `changelog/index.mdx` (docs quality — unchanged). Set each bullet URL using **Bullet links** (blog → PR → repo for docs). +1. Add full `` block to `changelog/index.mdx` (docs quality, unchanged). Set each bullet URL using **Bullet links** (blog → PR → repo for docs). If the release deprecates, removes, replaces, or EOLs a node (especially a Partner Node), add that under **Partner Node Updates** or **New Node Updates** per **Node lifecycle**. 2. **Step 1 — Simplify EN** — review before translating: @@ -328,6 +358,7 @@ When user asks to update CMS release notes: - [ ] Align OSS popup names with existing `tutorials/` model names (added support for X). Not loader plumbing - [ ] Shorten Cloud EN bullets (added model support, skip node lists). Keep local/docs more detailed. Exception: Cloud removal/EOL bullets still list what was retired - [ ] LoRA format bullets: support that trainer/format, not the previous skip-keys bug +- [ ] Record node lifecycle in the matching section: partner deprecation / removal / replacement / EOL under **Partner Node Updates**; core/built-in lifecycle under **New Node Updates**. Name the replacement node when one exists. Do not drop these from docs or CMS - [ ] Omit ComfyUI-WIKI items (embedded docs, workflow templates, model blueprints) unless user explicitly asks - [ ] Run `pnpm cms:prepare:en`; rewrite Cloud EN links; show staging EN → **wait for user approval** - [ ] Run `pnpm cms:prepare:locales` (not `cms:prepare:en`) → **wait for user approval** @@ -360,6 +391,6 @@ When user asks to update CMS release notes: |--|-----------|-----------| | Source | `changelog/index.mdx` | `staging/en/…` | | Length | Full detail | 3–5 bullets | -| New Nodes | Keep in full changelog | **Optional**; omit by default unless a human asks | +| New Nodes | Keep in full changelog | **Optional** for ordinary new nodes; **keep** deprecation / removal / replacement / EOL | | i18n | `zh/changelog/` etc. | `staging/zh/` etc. | | Deploy | Mintlify | Strapi draft → publish | diff --git a/.cursor/skills/docs-i18n-translate/SKILL.md b/.cursor/skills/docs-i18n-translate/SKILL.md index 0d37c929cd..6a4ba8fbb5 100644 --- a/.cursor/skills/docs-i18n-translate/SKILL.md +++ b/.cursor/skills/docs-i18n-translate/SKILL.md @@ -170,7 +170,7 @@ only re-translate changed `##` sections when `auto_chunk` applies). | Workflow templates | `update workflow templates to v…`, `comfyui-workflow-templates` bump | | Model blueprints | `Add new model blueprints`, template-library starter workflows | -Do not add bullets for dependency-only version bumps. See also **`cms-changelog-sync`** for CMS popup rules. +Do not add bullets for dependency-only version bumps. See also **`cms-changelog-sync`** for CMS popup rules, including **node lifecycle**: partner deprecation, removal, replacement, and EOL go under **Partner Node Updates**; core/built-in lifecycle goes under **New Nodes** / **New Node Updates**. **Docs changelog bullet URLs** (same as local CMS): matching [blog.comfy.org](https://blog.comfy.org/) post first, then the GitHub PR, then the ComfyUI repo commit/tag/compare. Do not use Cloud `?template=` links on the docs changelog. Cloud popup URLs are a separate rule in **cms-changelog-sync**. diff --git a/.github/scripts/cms/README.md b/.github/scripts/cms/README.md index c7da1034c5..cc924bbc3b 100644 --- a/.github/scripts/cms/README.md +++ b/.github/scripts/cms/README.md @@ -103,14 +103,15 @@ Configured in `cms-config.json` → `simplify`: | Key | Default | Meaning | |-----|---------|---------| -| `max_bullets_total` | **10** | Bullets for the **entire version** (not per section) | +| `max_bullets_total` | **10** | Bullets for the **entire version** (not per section). A target for optional items: lifecycle bullets are mandatory and may take the version over it | | `max_sections` | **3** | `**New Open-Source Model Support**` → `**Partner Node Updates**` → optional `**New Node Updates**` (bold labels, not `##`) | - Section order is **fixed** when present: open-source models first, partner nodes second, node updates last -- **New Node Updates is optional by default.** Omit from the CMS popup even if docs has New Nodes; include only when a human explicitly asks +- **New Node Updates is optional by default** for ordinary new nodes. Omit those from the CMS popup even if docs has New Nodes, unless a human asks +- **Never drop** node deprecation, removal, replacement, or EOL. Partner/API lifecycle goes under **Partner Node Updates**. Core/built-in lifecycle goes under **New Node Updates** (emit that section for those items even if nobody asked for new-node listings). Name the replacement when one exists. Lifecycle bullets outrank `max_bullets_total`: if they do not fit, keep them and drop ordinary new-node additions and minor partner tweaks first - Each bullet: **[**Name**](pr_url): 12–25 word description** — preserve model/node traits from source - **Keep PR links** when the source has them -- **Drop** performance tweaks, minor fixes, Load3D/UI housekeeping, and New Nodes unless requested +- **Drop** performance tweaks, minor fixes, Load3D/UI housekeeping, and ordinary New Nodes unless requested. Do not drop lifecycle items; they outrank the bullet limit - English only (Step 1): `pnpm cms:prepare:en -- --force v0.25.0` - Translate only (Step 2): `pnpm cms:prepare:locales -- --force v0.25.0` — reads existing `staging/en/`, never re-simplifies diff --git a/.github/scripts/cms/cms-simplify-prompt.ts b/.github/scripts/cms/cms-simplify-prompt.ts index c4d89f41d3..bf4936dabf 100644 --- a/.github/scripts/cms/cms-simplify-prompt.ts +++ b/.github/scripts/cms/cms-simplify-prompt.ts @@ -21,11 +21,12 @@ export const CMS_SIMPLIFY_SYSTEM_PROMPT = `You are an expert technical writer cr - Stay within the bullet and section limits given in the user message - Use fewer bullets for small releases; use the full allowance only when the source has enough substantive items - Do NOT add Bug Fixes, Performance, or internal refactor sections — drop those items +- **Overflow policy:** lifecycle bullets (deprecation, removal, replacement, EOL) are mandatory. When a version has more items than the bullet limit, keep every lifecycle bullet and drop optional items first: ordinary new-node additions, then minor partner tweaks. Going over the limit is better than omitting a lifecycle event **Section order (mandatory — never reorder):** 1. \`**New Open-Source Model Support**\` — when the source lists new open-source models 2. \`**Partner Node Updates**\` — when the source lists partner or API node updates; when open-source models are also present, place this immediately after them -3. \`**New Node Updates**\` — **optional**; omit by default even if the source has a **New Nodes** section +3. \`**New Node Updates**\` — **optional** for ordinary new nodes; **required** when the source has a core/built-in deprecation, removal, replacement, or EOL Emit only sections that have source items, in the order above. When open-source models are absent, Partner Node Updates may lead. Never place Partner Node Updates before New Open-Source Model Support when both are present. Never place New Node Updates before Partner Node Updates when both are present. Never merge categories into a flat list. Omit a section entirely if the source has no items for it. @@ -38,14 +39,16 @@ Emit only sections that have source items, in the order above. When open-source **Partner Node Updates:** - Include partner/API node additions or updates from the source -- Keep removals, deprecations, and EOL from the source. List the retired models or nodes. Do not drop them as housekeeping +- **Also include** partner/API node deprecation, removal, replacement, and EOL / retirement. These are first-class partner updates, not optional extras. List the retired models or nodes. Never drop them as housekeeping, and never drop them to make room for new-feature bullets +- When a successor exists, name both the old node or model and the replacement in the same bullet - Preserve scope or capability details when stated (e.g. number of new nodes, supported modality) - Always the second section when open-source models are also present (right after Open-Source Model Support) -**New Node Updates (optional — default omit):** -- **Default: do not emit this section.** Docs changelog may list New Nodes; the CMS popup does not need them. -- Only include \`**New Node Updates**\` when the user message explicitly asks to include new nodes (or equivalent). Otherwise skip the whole section even if the source has **New Nodes**. -- When explicitly requested: include meaningful user-facing entries (within the bullet limit); last among the three sections; skip minor plumbing with no workflow impact +**New Node Updates (optional — default omit ordinary new nodes):** +- **Default: do not emit this section for ordinary new built-in nodes.** Docs changelog may list New Nodes; the CMS popup does not need those additions. +- **Exception: emit this section** when the source deprecates, removes, replaces, or EOLs a core / built-in (non-partner) node. Those lifecycle bullets are required even if nobody asked to list new nodes +- Only include ordinary new-node additions when the user message explicitly asks to include new nodes (or equivalent) +- When the section is emitted: last among the three sections; skip minor plumbing with no workflow impact; keep lifecycle bullets **Bullet format:** - Linked: * [**Name**](url_from_source): Description @@ -58,11 +61,12 @@ Emit only sections that have source items, in the order above. When open-source **What to include (priority — matches section order):** 1. All open-source models from the source -2. Partner/API node updates -3. **New Nodes only if the user message explicitly requests them** (otherwise omit) +2. Partner/API node updates, **including** deprecation, removal, replacement, and EOL +3. Core/built-in node deprecation, removal, replacement, and EOL (emit **New Node Updates** for these) +4. **Ordinary New Nodes only if the user message explicitly requests them** (otherwise omit additions, but still keep lifecycle items from rule 3) **What to drop:** -- **New Node Updates / New Nodes** by default (unless explicitly requested in the user message) +- Ordinary **New Node Updates / New Nodes** additions by default (unless explicitly requested in the user message). Never drop deprecation, removal, replacement, or EOL - Minor fixes, refactors, dtype cleanups, internal tooling - Pure loader/plumbing changes with no workflow impact - Performance, stability, API housekeeping, console logging @@ -85,7 +89,9 @@ export function buildSimplifyUserPrompt( "", `Hard limits: **${limits.maxBulletsTotal} bullets total**, **${limits.maxSections} section headings max**.`, "Section order: New Open-Source Model Support → Partner Node Updates → (optional) New Node Updates.", - "Omit **New Node Updates** by default even if the source has New Nodes, unless this message explicitly asks to include them.", + "Omit ordinary **New Node Updates** additions by default even if the source has New Nodes, unless this message explicitly asks to include them.", + "Never drop deprecation, removal, replacement, or EOL. Partner lifecycle goes under **Partner Node Updates**. Core/built-in lifecycle goes under **New Node Updates** (emit that section for those items).", + "If the source has more items than the bullet limit, keep every lifecycle bullet and drop optional items first: ordinary new-node additions, then minor partner tweaks.", "Section labels: **bold** (e.g. **Partner Node Updates**), not ## headings.", "Use only facts and links from the release data. Each bullet: **6–12 words** — one key trait, no filler.", "",