cms-changelog-sync

# CMS Changelog Sync Push **draft** release notes to Strapi (`release-notes` content type). Docs changelog stays full; CMS uses committed staging with popup-sized copy. ## Hard gate: Cloud push / publish (ask every time) Whenever the user asks to **push**, **sync**, or **publish** to CMS (in any language), agents **must**: 1. Default to **`--project comfyui` only**. Do **not** run `cms:sync` / `cms:publish` / `cms:preview` for cloud in the same turn as the request. 2. **Stop and ask a second confirmation about Cloud**, even if the user already mentioned Cloud links, templates, or “push both”. Ask in plain language, for example: > Should Cloud go to CMS this time as well? Please check Cloud staging (links and copy) yourself, then confirm. Until you confirm, I will only handle comfyui. 3. Run **`--project cloud`** for preview/sync/publish **only after** the user replies with an explicit yes for Cloud in **this** conversation turn chain (e.g. “yes, push Cloud”, “cloud too”). Linking shortlinks earlier, preparing staging, or saying “push to CMS” alone is **not** Cloud approval. 4. If unsure, ask again. Never infer Cloud approval from prior releases, PR text, or that Cloud staging already exists. `cms:prepare:en` / `cms:prepare:locales` may still prepare both projects’ staging files. The gate applies to **Strapi preview, push, and publish** (`cms:preview`, `cms:sync`, `cms:publish`), not to local staging generation. Write this skill and related CMS agent docs in **English**. Match the user’s language only when asking the confirmation question in chat. ## Architecture Three **separate** steps — stop for human review between each: ``` changelog/index.mdx ← docs source of truth (full EN) │ ▼ Step 1: pnpm cms:prepare:en staging/en/changelog/index.mdx ← simplified popup EN → **review & approve** │ ▼ Step 2: pnpm cms:prepare:locales staging/{zh,ja,ko,fr,ru,es}/… ← translated from staging EN → **review & approve** │ ▼ Step 3: pnpm cms:preview / cms:sync -- --project comfyui (only after user confirms) Strapi CMS (draft) → manual Publish → published-versions.json ``` **Never** edit docs `zh/changelog/` for CMS. **Never** auto-publish in Strapi. **Never** use `pnpm translate` for CMS — that pipeline is for Mintlify docs only. ## Three-step workflow (local) | Step | Command | What it does | Gate | |------|---------|--------------|------| | **1. Simplify EN** | `pnpm cms:prepare:en -- --force v0.26.0` | docs → LLM → `staging/en/` | Review EN staging | | **2. Translate** | `pnpm cms:prepare:locales -- --force v0.26.0` | `staging/en/` → `staging/{zh,ja,ko,fr,ru,es}/` | Review locale staging | | **3. Push CMS** | `pnpm cms:preview` then `pnpm cms:sync` | staging → Strapi **drafts** | Strapi review → `cms:publish` | `pnpm cms:prepare` without `--en-only` / `--translate-only` prints help and exits — use the step-specific scripts above. ## Translation workflow (CMS staging) Step 2 only. **Input = simplified EN staging**, not docs changelog. ``` staging/en/changelog/index.mdx ← input (Step 1 output, human-approved) │ ▼ pnpm cms:prepare:locales -- v0.26.0 staging/zh|ja|ko|fr|ru|es/changelog/… ← output (popup copy per locale, ready to sync) │ ▼ pnpm cms:sync (Step 3, after user confirms) Strapi release-notes (draft) ``` | | Mintlify docs (`pnpm translate`) | CMS popup (`pnpm cms:prepare:locales`) | |--|----------------------------------|----------------------------------------| | English source | `changelog/index.mdx` (full docs) | `staging/en/changelog/index.mdx` (simplified popup) | | Output path | `zh/changelog/index.mdx`, etc. | `staging/zh/changelog/index.mdx`, etc. | | Purpose | Docs site | Strapi in-app notification | | Mix pipelines? | **No** | **No** | **Key points:** - `cms:prepare:locales` does **not** re-simplify English — it reads each project's own staging EN (`staging/en/` and `staging/cloud/en/`) - If staging EN is missing the version, translate fails — run `cms:prepare:en` first - Target locales: **zh, ja, ko, fr, ru, es** (see `cms-config.json`) - `--force` re-translates existing locale blocks (common after manual EN edits) - Never copy comfyui locale files onto cloud; cloud campaign shortlinks live on cloud EN ## Environment (`.env.local`) | Variable | Used by | Notes | |----------|---------|-------| | `TRANSLATE_API_KEY` | prepare | Same as `pnpm translate` | | `TRANSLATE_API_BASE_URL` | prepare | e.g. `https://api.deepseek.com` | | `TRANSLATE_API_MODEL` | prepare | e.g. `deepseek-v4-pro` | | `CMS_BASE_URL` | sync, delete-drafts | e.g. `https://cms.comfy.org` | | `CMS_API_TOKEN` | sync, delete-drafts | Strapi API token | | `CMS_PROJECT` | optional | Default `comfyui`; also `--project cloud` on CLI | CI: `CMS_BASE_URL` / `TRANSLATE_API_BASE_URL` → GitHub **Variables**; tokens → **Secrets**. ## Simplification rules (EN popup) Prompt: `.github/scripts/cms/cms-simplify-prompt.ts` Config: `.github/scripts/cms/cms-config.json` → `simplify` | Rule | Value | |------|-------| | 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** 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). `prepare:en` copies docs URLs and local-length copy into Cloud. After it runs, rewrite **Cloud EN** (links and wording) before translating. Never invent URLs. **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`. 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. **LoRA / trainer format:** say we support LoRAs trained in that format (or by that trainer). Do not mention the previous load bug. **Removals, deprecations, EOL:** keep them on the popup (do not drop as housekeeping). On Cloud, still list the retired node or model names so users know which graphs break. The "one short clause" Cloud rule does not apply to removal bullets. ## Bullet links (docs, local CMS, Cloud CMS) Resolve each feature bullet **before** `cms:prepare:locales`. Search these sources every time a new version lands: | Source | Where | |--------|--------| | Template index | [templates/index.json](https://github.com/Comfy-Org/workflow_templates/blob/main/templates/index.json) (raw: `https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/templates/index.json`) | | Blog | [blog.comfy.org](https://blog.comfy.org/) ([archive](https://blog.comfy.org/archive)) | Match a template by `name`, `title`, or `models` to the changelog item. Search the **whole** index: partner `api_*` and OSS `video_*`, `image_*`, `3d_*` (and any other prefix). Do not grep `api_` only. Match a blog post only if it covers **this** product or version (MiniMax H3 day-0 is not MiniMax H3 Max). **Video templates:** when several templates exist, pick one by suffix on `name`, in this order: **r2v → i2v → t2v**. Example: `api_minimax_h3_max_r2v` over `_i2v` / `_t2v`. If none of those suffixes exist, use the remaining matching template (`flf2v`, `edit`, `fun_controlnet_union`, and similar). Cloud URL shape: `https://cloud.comfy.org/?template=<name>` (no UTM unless the user supplied one). | Surface | Link priority (first match wins) | |---------|----------------------------------| | **Cloud** CMS (`staging/cloud/`) | 1. UTM / `links.comfy.org` URL **the user provided** 2. Cloud template URL from the index 3. GitHub PR 4. ComfyUI repo commit/tag/compare | | **Docs** `changelog/index.mdx` and **local** CMS (`staging/en/` etc.) | 1. Matching [blog.comfy.org](https://blog.comfy.org/) post 2. GitHub PR 3. ComfyUI repo commit/tag/compare | Do **not** put Cloud `?template=` URLs on docs or local popup. Do **not** copy local blog/PR links onto Cloud when a template (or user UTM) exists. After `prepare:en` merges comfyui → cloud, replace Cloud bullets that still point at PRs if the index has a template. ## ComfyUI-WIKI commits (omit from changelog) When curating `changelog/index.mdx` from ComfyUI git history, **do not add bullets** for commits routinely opened by **[ComfyUI-WIKI](https://github.com/Comfy-Org/ComfyUI-WIKI)** — they are dependency/content syncs, not core release features: | Skip | Typical commit / PR pattern | |------|----------------------------| | **Embedded docs** | `chore: update embedded docs to v…`, `comfyui-embedded-docs` in `requirements.txt` | | **Workflow templates** | `chore: update workflow templates to v…`, `comfyui-workflow-templates` in `requirements.txt` | | **Model blueprints** | `Add new model blueprints`, blueprint starter workflows in template library | 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. ## 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.