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.

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  (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)

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)

Key points:

• cms:prepare:locales does not re-simplify English — it reads existing staging/en/ only
• 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)

Environment (.env.local)

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

Style: principle-only prompt in cms-simplify-prompt.ts (no concrete version examples — avoids LLM contamination).

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 — they are dependency/content syncs, not core release features:

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 Open-Source Model Support**
* [**Model Name**](source_url): Short description with 1–2 traits from the release data

**New Node Updates**
* [**Node Name**](source_url): What the node does and why it matters

**Partner Node Updates**
* [**Partner Node**](source_url): Partner scope and capability from the release data

Sync adds header: # ComfyUI vX.Y.Z via format-cms-content.ts.

Projects (comfyui + cloud)

cms:prepare may generate both projects so staging stays mirrored. For cms:sync and cms:publish, agents must treat comfyui as the default project and pass --project comfyui. Only sync or publish cloud after the user explicitly confirms cloud, using --project cloud.

Same changelog content; Strapi project field and CMS header differ (# ComfyUI vs # Cloud).

Prepare runs LLM once on comfyui, then copies staging to cloud. Sync/publish must be project-scoped by agents: --project comfyui first, then --project cloud only after explicit cloud approval.

Single project: --project comfyui, --project cloud, or CMS_PROJECT=<project>.

Mark a version high attention:

pnpm cms:set-attention -- cloud v0.24.0 high --save

Commands

Flags (after --):

• --force — re-simplify/re-translate even if staging has the version; on sync, update already-published CMS entries (default skips published)
• --preview / --dry-run — no API writes
• --project cloud — single project only (default = both)
• v0.25.1 — explicit version(s)

Env:

• CMS_SYNC_ALL=1 — include already-published versions (backfill)
• Without it, local default = all unpublished EN versions per published-versions.json

Requires Bun. Loads .env.local automatically.

Standard workflow

New release version

1. Add full <Update> block to changelog/index.mdx (docs quality — unchanged).

2. Step 1 — Simplify EN — review before translating:

   pnpm cms:prepare:en -- --force v0.25.1
   

   Inspect: .github/scripts/cms/staging/en/changelog/index.mdx → stop until approved

3. Step 2 — Translate — from approved staging EN only:

   pnpm cms:prepare:locales -- v0.25.1          # first translate
   pnpm cms:prepare:locales -- --force v0.25.1 # re-translate after EN edits
   

   Inspect: .github/scripts/cms/staging/zh/changelog/index.mdx (and other locales) → stop until approved

4. Step 3 — Push ComfyUI drafts (only after user confirms staging):

   pnpm cms:preview -- --project comfyui v0.25.1
   pnpm cms:sync -- --project comfyui v0.25.1
   

5. Publish ComfyUI after Strapi review:

   pnpm cms:publish --preview -- --project comfyui v0.25.1
   pnpm cms:publish -- --project comfyui v0.25.1
   

6. Cloud is separate: run cloud preview/sync/publish only after the user explicitly confirms cloud, using --project cloud.

7. Commit .github/scripts/cms/staging/ and .github/scripts/cms/published-versions.json after publish.

Catch up all unpublished versions locally

pnpm cms:prepare:en -- --force              # Step 1: all unpublished EN
pnpm cms:prepare:locales -- --force         # Step 2: all locales
pnpm cms:preview
pnpm cms:sync                               # Step 3: after review

After prompt or config changes

Re-run with --force. Staging without --force skips existing <Update> blocks.

Version selection logic

cms:sync skips locales already published per registry. Published EN in CMS is never overwritten.

Key files

Agent checklist

When user asks to update CMS release notes:

• Confirm changelog/index.mdx has the new <Update> block
• Omit ComfyUI-WIKI items (embedded docs, workflow templates, model blueprints) unless user explicitly asks
• Run pnpm cms:prepare:en; show staging EN → wait for user approval
• Run pnpm cms:prepare:locales (not cms:prepare:en) → wait for user approval
• Run pnpm cms:preview -- --project comfyui ... then pnpm cms:sync -- --project comfyui ... only after user confirms staging
• Run cloud cms:sync / cms:publish only after separate explicit cloud confirmation
• Remind: Strapi publish is manual; then --write on published-versions
• Commit .github/scripts/cms/staging/ together with published-versions.json after publish
• Do not shorten docs changelog for CMS — staging is separate
• Do not run bulk CMS_SYNC_ALL prepare/sync without user consent (many API calls)

Troubleshooting

Related skills

• docs-i18n-translate — Mintlify docs ja/zh/ko (pnpm translate)
• docs-i18n-review — translation quality review (pnpm translate:review)

Docs vs CMS (do not confuse)