Skip to content

Commit 2da3a0d

Browse files
comfyui-wikicomfyui-wiki
committed
Add CMS Strapi changelog sync pipeline for in-app release notes.
Introduces prepare/sync/publish tooling that LLM-simplifies English changelog into gitignored staging, pushes comfyui and cloud drafts to Strapi, auto-refreshes published-versions.json on publish, and adds CI workflows plus agent skills.
1 parent a25978a commit 2da3a0d

39 files changed

Lines changed: 3915 additions & 3 deletions

‎.cursor/skills/cms-changelog-sync/SKILL.md‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
name: cms-changelog-sync
3+
description: >-
4+
Sync ComfyUI release notes to Strapi CMS: LLM-simplify English changelog for
5+
in-app popup, translate to zh/ja/ko/fr/ru/es in staging, push drafts to CMS.
6+
Use when updating changelog/index.mdx for CMS, running cms:prepare/cms:sync,
7+
Strapi release-notes, published-versions.json, CMS staging, simplifying
8+
release notes for the notification popup, or cms:publish to go live.
9+
---
10+
11+
# CMS Changelog Sync
12+
13+
Push **draft** release notes to Strapi (`release-notes` content type). Docs changelog stays full; CMS uses **gitignored staging** with popup-sized copy.
14+
15+
## Architecture
16+
17+
```
18+
changelog/index.mdx ← docs source of truth (do not shorten for CMS)
19+
│
20+
▼ pnpm cms:prepare:en / cms:prepare
21+
.github/scripts/cms/staging/
22+
en/changelog/index.mdx ← LLM-simplified popup EN
23+
{zh,ja,ko,fr,ru,es}/… ← translated from simplified EN
24+
│
25+
▼ pnpm cms:sync
26+
Strapi CMS (draft only) → manual Publish → published-versions.json
27+
```
28+
29+
**Never** edit docs `zh/changelog/` for CMS. **Never** auto-publish in Strapi.
30+
31+
## Environment (`.env.local`)
32+
33+
| Variable | Used by | Notes |
34+
|----------|---------|-------|
35+
| `TRANSLATE_API_KEY` | prepare | Same as `pnpm translate` |
36+
| `TRANSLATE_API_BASE_URL` | prepare | e.g. `https://api.deepseek.com` |
37+
| `TRANSLATE_API_MODEL` | prepare | e.g. `deepseek-v4-pro` |
38+
| `CMS_BASE_URL` | sync, delete-drafts | e.g. `https://cms.comfy.org` |
39+
| `CMS_API_TOKEN` | sync, delete-drafts | Strapi API token |
40+
| `CMS_PROJECT` | optional | Default `comfyui`; also `--project cloud` on CLI |
41+
42+
CI: `CMS_BASE_URL` / `TRANSLATE_API_BASE_URL` → GitHub **Variables**; tokens → **Secrets**.
43+
44+
## Simplification rules (EN popup)
45+
46+
Prompt: `.github/scripts/cms/cms-simplify-prompt.ts`
47+
Config: `.github/scripts/cms/cms-config.json` → `simplify`
48+
49+
| Rule | Value |
50+
|------|-------|
51+
| Total bullets per version | **3–5** (`max_bullets_total: 5`) |
52+
| Section headings max | **2** (`max_sections: 2`) |
53+
| Words per version | ~60–120 |
54+
| Bullet format | `[**Name**](pr_url): 5–12 word function` |
55+
| PR links | **Keep** when source has them; never invent URLs |
56+
| Sections allowed | `**New Open-Source Model Support**`, `**Partner Node Updates**` only |
57+
| Drop | Bug fixes, performance, Load3D, UI, internal refactors |
58+
59+
Example staging output:
60+
61+
```markdown
62+
**New Open-Source Model Support**
63+
* [**Depth Anything 3**](https://github.com/Comfy-Org/ComfyUI/pull/13853): Monocular depth estimation model
64+
65+
**Partner Node Updates**
66+
* [**Kling V3-Turbo**](https://github.com/Comfy-Org/ComfyUI/pull/14528): Text-to-video generation model
67+
```
68+
69+
Sync adds header: `# ComfyUI vX.Y.Z` via `format-cms-content.ts`.
70+
71+
## Projects (comfyui + cloud)
72+
73+
**Default: both projects** on `cms:prepare`, `cms:sync`, and `cms:publish`. Same changelog content; Strapi `project` field and CMS header differ (`# ComfyUI` vs `# Cloud`).
74+
75+
| Project | Staging path | CMS header |
76+
|---------|--------------|------------|
77+
| `comfyui` | `staging/{locale}/…` | `# ComfyUI vX.Y.Z` |
78+
| `cloud` | `staging/cloud/{locale}/…` | `# Cloud vX.Y.Z` |
79+
80+
Prepare runs LLM once on comfyui, then **copies staging to cloud**. Sync/publish push both to Strapi.
81+
82+
Single project only: `--project cloud` or `CMS_PROJECT=cloud`.
83+
84+
Mark a version **high** attention:
85+
86+
```bash
87+
pnpm cms:set-attention -- cloud v0.24.0 high --save
88+
```
89+
90+
## Commands
91+
92+
| Command | Action |
93+
|---------|--------|
94+
| `pnpm cms:prepare:en` | Simplify EN → staging (comfyui + cloud copy) |
95+
| `pnpm cms:prepare` | Simplify EN + translate all locales (both projects) |
96+
| `pnpm cms:preview -- v0.25.1` | Dry-run Strapi push (both projects) |
97+
| `pnpm cms:sync -- v0.25.1` | Push/update **drafts** (both projects) |
98+
| `pnpm cms:publish -- v0.25.1` | Publish + refresh `published-versions.json` (both) |
99+
| `pnpm cms:set-attention -- cloud v0.24.0 high` | Set attention low/high in Strapi |
100+
| `pnpm cms:delete-drafts --preview` | List deletable Strapi drafts |
101+
| `pnpm cms:delete-drafts` | Delete drafts (keeps published) |
102+
103+
Flags (after `--`):
104+
105+
- `--force` — re-simplify/re-translate even if staging has the version
106+
- `--preview` / `--dry-run` — no API writes
107+
- `--project cloud` — single project only (default = both)
108+
- `v0.25.1` — explicit version(s)
109+
110+
Env:
111+
112+
- `CMS_SYNC_ALL=1` — include already-published versions (backfill)
113+
- Without it, local default = **all unpublished EN versions** per `published-versions.json`
114+
115+
Requires **Bun**. Loads `.env.local` automatically.
116+
117+
## Standard workflow
118+
119+
### New release version
120+
121+
1. Add full `<Update>` block to `changelog/index.mdx` (docs quality — unchanged).
122+
2. **English first** — review popup copy before translating:
123+
124+
```bash
125+
pnpm cms:prepare:en -- --force v0.25.1
126+
```
127+
128+
Inspect: `.github/scripts/cms/staging/en/changelog/index.mdx`
129+
130+
3. **Translate** after EN approved:
131+
132+
```bash
133+
pnpm cms:prepare -- v0.25.1
134+
```
135+
136+
4. **Push drafts**:
137+
138+
```bash
139+
pnpm cms:preview -- v0.25.1
140+
pnpm cms:sync -- v0.25.1
141+
```
142+
143+
5. **Publish** after review (CLI or Strapi admin):
144+
145+
```bash
146+
pnpm cms:publish --preview -- v0.25.1
147+
pnpm cms:publish -- v0.25.1
148+
# published-versions.json is refreshed automatically — commit if changed
149+
```
150+
151+
6. Commit `.github/scripts/cms/published-versions.json` after publish (auto-refreshed by `cms:publish`).
152+
153+
### Catch up all unpublished versions locally
154+
155+
```bash
156+
pnpm cms:prepare:en -- --force # all unpublished EN
157+
pnpm cms:prepare -- --force # then all locales
158+
pnpm cms:preview
159+
pnpm cms:sync
160+
```
161+
162+
### After prompt or config changes
163+
164+
Re-run with `--force`. Staging without `--force` **skips** existing `<Update>` blocks.
165+
166+
## Version selection logic
167+
168+
| Context | Versions processed |
169+
|---------|-------------------|
170+
| Local, no args | EN not in `published-versions.json` (≥ `min_version` 0.21.0) |
171+
| Local + `CMS_SYNC_ALL=1` | All ≥ min_version |
172+
| Explicit `v0.25.1` | That version only |
173+
| CI (`CMS_SYNC_BEFORE` / `CMS_SYNC_AFTER`) | New/changed `<Update>` blocks in git diff only |
174+
175+
`cms:sync` skips locales already published per registry. Published EN in CMS is never overwritten.
176+
177+
## Key files
178+
179+
| Path | Role |
180+
|------|------|
181+
| `changelog/index.mdx` | Full docs EN changelog |
182+
| `.github/scripts/cms/staging/` | CMS content (gitignored) |
183+
| `.github/scripts/cms/cms-config.json` | Locales, min version, simplify limits |
184+
| `.github/scripts/cms/published-versions.json` | Published registry (commit after Strapi publish) |
185+
| `.github/scripts/cms/prepare-cms-changelog.ts` | Prepare pipeline |
186+
| `.github/scripts/cms/sync-to-strapi.ts` | Strapi draft sync |
187+
| `.github/scripts/cms/publish-cms-drafts.ts` | Draft → published |
188+
| `.github/scripts/cms/delete-cms-drafts.ts` | Clean bad drafts |
189+
| `.github/workflows/cms-changelog-sync.yml` | CI: prepare → preview → sync on main |
190+
191+
## Agent checklist
192+
193+
When user asks to update CMS release notes:
194+
195+
- [ ] Confirm `changelog/index.mdx` has the new `<Update>` block
196+
- [ ] Run `pnpm cms:prepare:en` (with `--force` if redoing); show staging EN for review
197+
- [ ] Wait for user approval before `pnpm cms:prepare` (translations)
198+
- [ ] Run `pnpm cms:preview` then `pnpm cms:sync`
199+
- [ ] Remind: Strapi publish is manual; then `--write` on published-versions
200+
- [ ] Do **not** commit staging/ (gitignored)
201+
- [ ] Do **not** shorten docs changelog for CMS — staging is separate
202+
- [ ] Do **not** run bulk `CMS_SYNC_ALL` prepare/sync without user consent (many API calls)
203+
204+
## Troubleshooting
205+
206+
| Issue | Fix |
207+
|-------|-----|
208+
| Only one version simplified | Old behavior was latest-only; now defaults to unpublished. Use `CMS_SYNC_ALL=1` for all. |
209+
| Staging skipped | Version already exists — add `--force` |
210+
| Strapi VERSION shows `-` | Bulk sync bug: `version` field null; delete drafts and re-sync |
211+
| Delete draft 500 | Use `pnpm cms:delete-drafts` (locale-only DELETE, not `status=draft`) |
212+
| `English base draft missing` on locale sync | Ensure EN draft exists first; sync creates EN before other locales |
213+
| Background prepare still running | `pkill -f prepare-cms-changelog.ts` |
214+
215+
## Related skills
216+
217+
- **`docs-i18n-translate`** — Mintlify docs ja/zh/ko (`pnpm translate`)
218+
- **`docs-i18n-review`** — translation quality review (`pnpm translate:review`)
219+
220+
## Docs vs CMS (do not confuse)
221+
222+
| | Docs site | CMS popup |
223+
|--|-----------|-----------|
224+
| Source | `changelog/index.mdx` | `staging/en/…` |
225+
| Length | Full detail | 3–5 bullets |
226+
| i18n | `zh/changelog/` etc. | `staging/zh/` etc. |
227+
| Deploy | Mintlify | Strapi draft → publish |

‎.cursor/skills/docs-i18n-review/SKILL.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
name: docs-i18n-review
3+
description: >-
4+
Review ComfyUI docs translation quality with LLM-as-a-judge (review-i18n.ts).
5+
Scores accuracy, completeness, terminology, fluency. Use when reviewing zh/ja/ko
6+
translations, running translate:review, quality-report, reviewSourceHash, or
7+
checking translation quality after pnpm translate.
8+
---
9+
10+
# Docs i18n Quality Review
11+
12+
Advisory LLM-as-a-judge for **existing** ja/zh/ko translations. Separate from translation (`pnpm translate`) and from the model's self-reported `=== MISMATCHES ===` during translate.
13+
14+
**Not for CMS staging** — reviews committed docs under `{lang}/`.
15+
16+
## When to use
17+
18+
- After `pnpm translate` on important pages
19+
- Before merging large i18n PRs
20+
- When user asks to review translation quality
21+
- Spot-check with `--sample N`
22+
23+
## Environment (`.env.local`)
24+
25+
Prefer a **cheap/fast** judge model (lighter than translation):
26+
27+
| Variable | Purpose |
28+
|----------|---------|
29+
| `REVIEW_API_KEY` | Judge API key (falls back to `TRANSLATE_API_KEY`) |
30+
| `REVIEW_API_BASE_URL` | Endpoint (falls back to `TRANSLATE_*`) |
31+
| `REVIEW_API_MODEL` | e.g. `deepseek-v4-flash` |
32+
| `REVIEW_CONCURRENCY` | Default 5; lower if socket errors |
33+
34+
Requires **Bun**.
35+
36+
## Commands
37+
38+
| Command | Action |
39+
|---------|--------|
40+
| `pnpm translate:review` | Pending reviews, all languages |
41+
| `pnpm translate:review -- --lang ko` | One language |
42+
| `pnpm translate:review -- installation/x.mdx` | Specific file(s) |
43+
| `pnpm translate:review -- --all` | Re-review everything |
44+
| `pnpm translate:review -- --sample 20` | N random pending per language |
45+
| `pnpm translate:review -- --min-score 4` | Report files scoring below 4/5 |
46+
| `pnpm translate:review -- --snippets` | Review snippets instead of pages |
47+
48+
## Output
49+
50+
Reports (gitignored): `.github/i18n-logs/review/`
51+
52+
- `quality-report.json` / `.txt` — scores + issues
53+
- **Advisory only** — never written into MDX
54+
55+
Per-file state in git: `reviewSourceHash` in translated frontmatter (mirrors `translationSourceHash`). Commit hash updates; detailed scores stay in logs.
56+
57+
## Scoring axes
58+
59+
1. **Accuracy** — meaning matches English
60+
2. **Completeness** — nothing missing or added
61+
3. **Terminology** — glossary / preserve_terms consistency
62+
4. **Fluency** — natural target language
63+
64+
## Standard workflow
65+
66+
```bash
67+
pnpm translate -- changelog/index.mdx --lang ko # translate first
68+
pnpm translate:review -- changelog/index.mdx --lang ko
69+
# Read .github/i18n-logs/review/quality-report.txt
70+
# Fix issues → re-translate affected sections → re-review
71+
```
72+
73+
Incremental: skips files already reviewed at current English hash unless `--all`.
74+
75+
## Agent checklist
76+
77+
- [ ] Ensure translation is up to date (`translationSourceHash` matches EN) before review
78+
- [ ] Run review after translate, not instead of translate
79+
- [ ] Read report from `.github/i18n-logs/review/` — do not commit logs
80+
- [ ] Fix via re-translate or glossary overrides, not manual score edits
81+
- [ ] For systematic term issues → `glossary/overrides/{lang}.json` (see `docs-i18n-translate` skill)
82+
83+
## Key files
84+
85+
| Path | Role |
86+
|------|------|
87+
| `.github/scripts/i18n/review-i18n.ts` | Review entry point |
88+
| `.github/scripts/i18n/glossary.mjs` | Terminology check hints |
89+
| `.github/scripts/i18n/README.md` | Full review section |
90+
91+
## Troubleshooting
92+
93+
| Issue | Fix |
94+
|-------|-----|
95+
| Nothing to review | Translation stale or already reviewed — run translate or `--all` |
96+
| Socket / timeout errors | Lower `REVIEW_CONCURRENCY`; use faster model |
97+
| Low terminology score | Update glossary overrides, re-translate, re-review |
98+
99+
## Related skills
100+
101+
- **`docs-i18n-translate`** — generate/update translations
102+
- **`cms-changelog-sync`** — CMS popup staging (different pipeline)

0 commit comments

Comments
 (0)