refactor(ci): split api-reference sync into three focused jobs by decepulis · Pull Request #677 · videojs/v10

decepulis · 2026-03-02T14:42:39Z

Summary

Refines and expands the scope of the API reference sync workflow from #676. Rewritten as three focused, parallel job.

Why

The original single-job workflow (#676) works but has three areas that could use refinement

1. "Drift" was ambiguous

The prompt told Claude to "compare generated API JSON with docs" without clarifying which side drifts. The API JSON is rebuilt fresh every run — it's always correct. What actually goes stale is the hand-written MDX prose. I was a little worried that the original prompt didn't seem to make this explicitly.

2. Demos were explicitly skipped

The prompt said Do not request runnable examples/demos. But, idk. I kinda want demos. So I added that as a separate sub-task

3. Only `/reference/` was checked

Concept pages, how-to guides, and package READMEs that mention specific APIs (prop names, element names, selectors) were not scanned. It's harder to figure out what non-reference content applies to a given change, granted, but, I want to try.

Architecture

analyze (shell — no LLM)
  ├── reference-copy   (Opus, 20 turns — can auto-PR)
  ├── reference-demos  (Sonnet, 14 turns — issues only)
  └── cross-site-refs  (Sonnet, 14 turns — triage issues only)

All three downstream jobs run in parallel after the gate passes.

Job 0: `analyze`

Shell-only gate — no LLM cost. Checks if the PR touched API-relevant paths (packages/core/src/core/ui/, packages/html/src/ui/, packages/react/src/ui/, packages/store/src/, packages/core/src/core/selectors/). For workflow_dispatch, always passes (full scan). Outputs PR context for downstream prompts.

Job 1: `reference-copy` (Opus)

Compares generated API JSON (source of truth) against hand-written MDX in site/src/content/docs/reference/. The prompt is explicit: "drift" = the MDX doesn't match the JSON. Creates canonical issues + PRs per component. Uses the new reference-copy-issue.md template which drops the redundant "API Changes Summary" table and adds sidebar status.

Job 2: `reference-demos` (Sonnet)

Reads demo files in site/src/components/docs/demos/{component}/ and checks for renamed props, removed options, changed signatures, deprecated patterns. Creates issues only — demo fixes need human judgment. Uses the new reference-demos-issue.md template.

Job 3: `cross-site-refs` (Sonnet)

Greps concept pages, how-to guides, and package READMEs for mentions of changed APIs (all naming variants). Classifies hits as high/medium/low confidence. Creates triage issues only. Groups related APIs into one issue when they affect the same files. Uses the new cross-site-refs-issue.md template.

New labels

Three labels differentiate drift types in issues:

reference:copy — MDX prose drift
reference:demos — Demo code drift
cross-ref — Cross-site reference drift

File changes

File	Change
`.github/workflows/api-reference-sync.yml`	Rewritten: 1 job → 4 jobs
`.github/templates/reference-copy-issue.md`	New (replaces `api-reference-update-issue.md`)
`.github/templates/reference-demos-issue.md`	New
`.github/templates/cross-site-refs-issue.md`	New
`.github/templates/api-reference-update-issue.md`	Deleted
`.github/templates/api-reference-update-pr.md`	Kept as-is

Cost tradeoff

Sonnet for Jobs 2 and 3 keeps costs down — these are narrower tasks (code/grep comparison vs. prose writing). Opus is only used for Job 1 which needs to understand prose nuance and potentially write MDX fixes in PRs.

Test plan

Push to branch, manually trigger workflow_dispatch to verify analyze outputs gate correctly
Merge a PR that changes a component's props → verify Job 1 detects MDX drift
Merge a PR that changes an API used in demos → verify Job 2 flags it
Merge a PR that changes an API mentioned in a concept page → verify Job 3 catches it
Verify no duplicate issues on repeated runs
Verify jobs skip cleanly when has_changes is false

🤖 Generated with Claude Code

The monolithic sync job from #676 had three blind spots: 1. The prompt was ambiguous about what "drift" means — the generated API JSON is always fresh, but the hand-written MDX prose can go stale. The prompt didn't make this distinction explicit. 2. It explicitly skipped demos (`Do not request runnable examples/demos`), so stale code examples went undetected. 3. It only checked `site/src/content/docs/reference/` — concept pages, how-to guides, and READMEs that mention changed APIs were ignored. Split into a shell-only `analyze` gate + three parallel downstream Claude jobs, each with a narrow scope and explicit instructions: - `reference-copy` (Opus, 20 turns): MDX prose vs generated JSON - `reference-demos` (Sonnet, 14 turns): demo code drift, issues only - `cross-site-refs` (Sonnet, 14 turns): stale API mentions outside /reference/, triage issues only Also adds three drift-type-specific issue templates and removes the old generic one. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

netlify · 2026-03-02T14:42:47Z

✅ Deploy Preview for vjs10-site ready!

Name	Link
🔨 Latest commit	`c76de73`
🔍 Latest deploy log	https://app.netlify.com/projects/vjs10-site/deploys/69a8462e40640700083747d3
😎 Deploy Preview	https://deploy-preview-677--vjs10-site.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

github-actions · 2026-03-02T14:43:37Z

📦 Bundle Size Report

Package	Size		%
@videojs/core	10.41 kB	`░░░░░░░░`	0%	✅
@videojs/element	1.60 kB	`░░░░░░░░`	0%	✅
@videojs/html	26.98 kB	`░░░░░░░░`	0%	✅
@videojs/icons	7.49 kB	`░░░░░░░░`	0%	✅
@videojs/react	15.08 kB	`░░░░░░░░`	0%	✅
@videojs/store	1.96 kB	`░░░░░░░░`	0%	✅
@videojs/utils	2.81 kB	`░░░░░░░░`	0%	✅

Total: 66.33 kB · 0 B · 0%

Entry Breakdown

Subpath sizes are the additional bytes on top of the root entry point, measured by bundling root + subpath together and subtracting the root-only size.

@videojs/core

Entry	Base	PR	Diff	%
`.`	4.39 kB	4.39 kB	0 B	0%	✅
`./dom`	6.03 kB	6.03 kB	0 B	0%	✅
total	10.41 kB	10.41 kB	0 B	0%

@videojs/element

Entry	Base	PR	Diff	%
`.`	817 B	817 B	0 B	0%	✅
`./context`	823 B	823 B	0 B	0%	✅
total	1.60 kB	1.60 kB	0 B	0%

@videojs/html

Entry	Base	PR	Diff	%
`.`	15.45 kB	15.45 kB	0 B	0%	✅
`./video`	9.44 kB	9.44 kB	0 B	0%	✅
`./audio`	1.06 kB	1.06 kB	0 B	0%	✅
`./background`	1.02 kB	1.02 kB	0 B	0%	✅
total	26.98 kB	26.98 kB	0 B	0%

@videojs/icons

Entry	Base	PR	Diff	%
`./react`	2.27 kB	2.27 kB	0 B	0%	✅
`./html`	1.52 kB	1.52 kB	0 B	0%	✅
`./render`	1.59 kB	1.59 kB	0 B	0%	✅
`./element`	2.11 kB	2.11 kB	0 B	0%	✅
total	7.49 kB	7.49 kB	0 B	0%

@videojs/store

Entry	Base	PR	Diff	%
`.`	1.31 kB	1.31 kB	0 B	0%	✅
`./html`	472 B	472 B	0 B	0%	✅
`./react`	199 B	199 B	0 B	0%	✅
total	1.96 kB	1.96 kB	0 B	0%

@videojs/utils

Entry	Base	PR	Diff	%
`./array`	104 B	104 B	0 B	0%	✅
`./dom`	928 B	928 B	0 B	0%	✅
`./events`	227 B	227 B	0 B	0%	✅
`./function`	261 B	261 B	0 B	0%	✅
`./object`	119 B	119 B	0 B	0%	✅
`./predicate`	265 B	265 B	0 B	0%	✅
`./string`	148 B	148 B	0 B	0%	✅
`./style`	185 B	185 B	0 B	0%	✅
`./time`	478 B	478 B	0 B	0%	✅
`./number`	158 B	158 B	0 B	0%	✅
total	2.81 kB	2.81 kB	0 B	0%

ℹ️ How to interpret

Sizes are minified + brotli, measured with esbuild.
Package totals are computed as root size + marginal subpath costs.
Subpath marginal cost = (root + subpath bundled together) − root alone.

Icon	Meaning
✅	No change
🔺	Increased ≤ 10%
🔴	Increased > 10%
🔽	Decreased
🆕	New (no baseline)

Run pnpm size locally to check current sizes.

mihar-22

Thanks for doing this, awesome! Only some name fix suggestions below

mihar-22 · 2026-03-02T17:58:56Z

-## API Changes Summary
-| Surface | Change Type | Before | After | Source |
-|---|---|---|---|---|
-{{API_CHANGES_TABLE_ROWS}}
-


Would this be nice to keep?

Oh yeah this seems super nice to keep. Good catch.

mihar-22 · 2026-03-02T18:02:23Z

-            - Provide concise usage-guidance scaffolding based on API surface and likely user intent.
-            - Keep issue content human-focused; no hidden agent-only instruction blocks.
+            Labels:
+            - Required: `docs`, `api`, `site`, `reference:copy`.


label suggestion: reference:copy -> docs:api

Easier to filter and manage labels if we keep it readable and namespaced under docs:.

I'm thinking api might be too broad. I'll go with docs:reference-copy

mihar-22 · 2026-03-02T18:02:40Z

+            - Do NOT create an issue if no drift is found.
+
+            Labels (always all of these):
+            - `docs`, `api`, `site`, `reference:demos`, `components`, `triage`.


same as above: reference:demos -> docs:demos

mihar-22 · 2026-03-02T18:03:28Z

+            - Do NOT create an issue if no stale references are found.
+
+            Labels (always all of these):
+            - `docs`, `site`, `cross-ref`, `triage`.


label change suggestion (same as above): cross-ref -> docs:content

Following the convention I made above... how about docs:guide-copy?
Or maybe since this isn't exactly about copy, maybe docs:guide-api or docs:guide-reference or...
Well. Let me think about it. I just like the word "guide", since it's the term we're using to describe non-reference documentation.

mihar-22 · 2026-03-02T18:05:21Z

template name suggestion: docs/api-ref-issue

mihar-22 · 2026-03-02T18:06:44Z

template name suggestion: docs/content-api-issue.md

why: lives in site/src/content and generally speaking it's highlighting API drift in content pages.

mihar-22 · 2026-03-02T18:07:09Z

template name suggestion: docs/demo-api-issue

mihar-22 · 2026-03-02T18:08:04Z

+          fi
+
+  # ─── Job 1: MDX prose drift (Claude Opus) ───────────────────────────
+  reference-copy:


job name suggestion: docs-api (workflow is called api-reference-sync)

mihar-22 · 2026-03-02T18:08:47Z

+            - Do NOT check concept/how-to pages (separate job handles that).
+
+  # ─── Job 2: Demo code drift (Claude Sonnet) ─────────────────────────
+  reference-demos:


job name suggestion: docs-demos (workflow is called api-reference-sync)

mihar-22 · 2026-03-02T18:09:40Z

+            - Do NOT check concept/how-to pages (separate job handles that).
+
+  # ─── Job 3: Cross-site references (Claude Sonnet) ───────────────────
+  cross-site-refs:


job name suggestion: docs-content (workflow is called api-reference-sync)

Consistent `docs:*` naming across labels, job IDs, and template files. Move templates into `docs/` subdirectory and restore API Changes Summary table in reference-copy template. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

decepulis requested a review from mihar-22 March 2, 2026 14:42

mihar-22 reviewed Mar 2, 2026

View reviewed changes

decepulis merged commit 410fc01 into main Mar 4, 2026
7 of 8 checks passed

decepulis deleted the ci/api-reference-sync-split branch March 4, 2026 14:48

Conversation

decepulis commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

1. "Drift" was ambiguous

2. Demos were explicitly skipped

3. Only /reference/ was checked

Architecture

Job 0: analyze

Job 1: reference-copy (Opus)

Job 2: reference-demos (Sonnet)

Job 3: cross-site-refs (Sonnet)

New labels

File changes

Cost tradeoff

Test plan

Uh oh!

netlify Bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vjs10-site ready!

Uh oh!

github-actions Bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📦 Bundle Size Report

Entry Breakdown

Uh oh!

mihar-22 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

decepulis Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mihar-22 Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mihar-22 Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

decepulis commented Mar 2, 2026 •

edited

Loading

3. Only `/reference/` was checked

Job 0: `analyze`

Job 1: `reference-copy` (Opus)

Job 2: `reference-demos` (Sonnet)

Job 3: `cross-site-refs` (Sonnet)

netlify Bot commented Mar 2, 2026 •

edited

Loading

github-actions Bot commented Mar 2, 2026 •

edited

Loading

decepulis Mar 4, 2026 •

edited

Loading

mihar-22 Mar 2, 2026 •

edited

Loading

mihar-22 Mar 2, 2026 •

edited

Loading