Skip to content

docs(design-system): record the SemVer policy and the #14790 brand-layer verdict - #16796

Merged
ryan-di merged 4 commits into
mainfrom
fleet/srx-35-design-system-semver-doc
Oct 1, 2026
Merged

ryan-di merged 4 commits into
mainfrom
fleet/srx-35-design-system-semver-doc

Conversation

@christian-byrne

@christian-byrne christian-byrne commented Sep 3, 2026 •

Copy link
Copy Markdown
Contributor

Docs-only follow-up answering the SemVer question raised on #14790.

Verdict: the brand-layer move is breaking, and the first release carrying it must be 2.0.0. Key facts:

  • The change removes brand tokens from _palette.css and stops base.css from loading Inter, changing the package's public styling surface.
  • @comfyorg/design-system@1.1.0 was published from main on 2026-09-05 without the brand-layer move.
  • refactor(design-system): move the brand layer into the package #14790 remains outside main, so its old in-tree 1.1.0 version does not establish a published precedent for the move.
  • When the brand-layer stack lands, the release carrying that breaking change must be a major bump from the shipped 1.x line.

This PR records the policy (exports are part of the public SemVer surface; removing tokens, @font-face rules, or exported files is breaking) and the current release precedent in the README's Releasing section. It does not change package code or the package version.

Verification

  • npm view @comfyorg/design-system version reports 1.1.0.
  • main currently declares 1.1.0 in packages/design-system/package.json.
  • The PR diff is limited to packages/design-system/README.md.

…yer precedent

The review on #14790 asked whether the brand-layer move should have been a
major bump. Nothing was ever published at 1.1.0 (npm has 1.0.0/1.0.1), the
PR body itself declares the change breaking, so the next release carrying
it must be 2.0.0. Document both the policy and the verdict where the
package documents versioning.
@christian-byrne
christian-byrne requested a review from a team September 3, 2026 16:58
@christian-byrne christian-byrne added the risk:R1 PR risk grade (advisory shadow check; grader-owned) label Sep 3, 2026
@coderabbitai

coderabbitai Bot commented Sep 3, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Important

Review skipped

Review was skipped as selected files did not have any reviewable changes.

⚙️ Run configuration

Configuration used: Repository: Comfy-Org/ComfyUI_frontend/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 393ef368-ebe6-4bcd-a4e1-bac5a9f97875

📥 Commits

Reviewing files that changed from the base of the PR and between d7c5e36 and bb3324b.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository: Comfy-Org/ComfyUI_frontend/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 3d142556-4e67-47d8-8415-c8eb357c59a2

📥 Commits

Reviewing files that changed from the base of the PR and between 8fc88b4 and d7c5e36.

📒 Files selected for processing (1)
  • packages/design-system/README.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review. Your free on-demand review promotion remains active until October 9, 2026 at 6:00 PM UTC.


📝 Walkthrough

Walkthrough

The design-system README adds SemVer guidance for exported CSS and icon assets. It also states that the brand-layer move must first ship in version 2.0.0.

Changes

Design system release policy

Layer / File(s) Summary
Exported asset versioning policy
packages/design-system/README.md
The README states that removing or repurposing exported tokens, font-face declarations, or files requires a major version bump. It records 2.0.0 as the first release for the brand-layer move.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to d7c5e

The README records that 1.1.0 shipped without the brand-layer move and specifies 2.0.0 for the release carrying it. No actionable merge risk remains in this documentation-only change.

🚥 Pre-merge checks | ✅ 7
✅ Passed checks (7 passed)
Check name Status Explanation
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
End-To-End Regression Coverage For Fixes ✅ Passed The PR title and all commit subjects use documentation language, not bug-fix language. The PR changes only packages/design-system/README.md, and the check explicitly excludes documentation-only chan…
Website End-To-End Regression Coverage ✅ Passed The PR changes only packages/design-system/README.md. It does not change files under apps/website/src/ or apps/website/public/, so this website-specific check does not apply.
Adr Compliance For Entity/Litegraph Changes ✅ Passed The pull request changes only packages/design-system/README.md. It does not modify src/lib/litegraph/, src/ecs/, or graph-entity files. The ADR compliance check is not applicable.
Title check ✅ Passed The title clearly identifies the documentation change, the SemVer policy, and the related brand-layer verdict.
Description check ✅ Passed The description explains the purpose, changes, breaking-change decision, dependencies, verification steps, and affected file. It does not use every template heading, but it provides the required infor…
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

Comment @coderabbitai help to get the list of available commands.

@github-actions

github-actions Bot commented Sep 3, 2026 •

Copy link
Copy Markdown
Contributor

🌐 Website E2E

Tip

All tests passed.

Status ✅ Passed
Report View Report

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 10/01/2026, 02:54:40 AM UTC

Links

🔗 Website Preview

Website Preview: https://comfy-website-preview-pr-16796.vercel.app

Models is built and gated by PostHog (workshop-enabled), using staging Cloud.

This commit: https://website-frontend-eq7afajkn-comfyui.vercel.app

Last updated: 2026-10-01T02:54:40Z for bb3324b

🧩 Custom Nodes Ecosystem Matrix: 🟡 Withheld — could not measure

Executes the frontend JS of every registry pack that ships any, against this change, in both renderers. The eight ecosystem-matrix shard checks are a harness self-test; the pack verdict is matrix-verdict.

This candidate changes nothing the matrix measures, so every expensive stage was skipped.

Reproduce locally
# build one shard's fixture, then run it
python3 scripts/registry-census/build_matrix.py --shard 1/4
MATRIX_RENDERER=vue MATRIX_VUE=1 \
  npx vitest run --config vitest.matrix.config.mts

Full docs: scripts/registry-census/README.md

🌾 Fallow: ✅ Passed

Fallow audits the diff for duplication, complexity and dead code. It gates on new findings only, so when the audit completes, a red is something this PR introduced or moved — never inherited backlog. A red can also mean the audit itself did not finish; the details below say which happened.

No new findings in the changed files.

Reproduce locally
# the base the gate compared against
npx fallow audit --root . --quiet --format json \
  --changed-since 2595efcd93b007997d4adafbbdbf288108a86680

Full docs: ADR-DEVEX-LINT-0015

@codecov

codecov Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@            Coverage Diff             @@
##             main   #16796      +/-   ##
==========================================
- Coverage   84.51%   82.33%   -2.19%     
==========================================
  Files        3367     3041     -326     
  Lines      162316   145218   -17098     
  Branches    42308    39358    -2950     
==========================================
- Hits       137188   119562   -17626     
- Misses      23208    23920     +712     
+ Partials     1920     1736     -184     
Flag Coverage Δ
billing-web-unit 92.06% <ø> (ø)
website-unit 79.68% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1276 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@CodeJuggernaut CodeJuggernaut left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The precedent paragraph is already out of date.

Comment thread packages/design-system/README.md Outdated
loading Inter. That PR was merged into a feature-branch stack with an
in-tree version of `1.1.0`, and the review raised whether it should have been
`2.0.0`. The verdict: the change **is breaking** — the PR's own body says so,
and nothing was ever published to npm at `1.1.0` (the published versions are

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Severity: Major

What: lines 65-68 record that nothing was published at 1.1.0 (published versions 1.0.0 and 1.0.1) and instruct "do not let the in-tree 1.1.0 from that stack reach npm", but the registry lists 1.1.0 as latest, published 2026-09-05T08:05Z from main's own bump ca54f4bd2e (#17063), while #14790's merge ac4dd382b9 is still not on main and that tarball carries no brand-layer file.

Why this is an issue: the recorded evidence is false on merge day and the instruction can no longer be followed, so a reader who checks the registry finds the precedent wrong in one command and gets no guidance for the real situation, where the stack's in-tree 1.1.0 now collides with a published minor and the release carrying the move must be 2.0.0 because it is breaking against the shipped 1.1.0.

Proposed Fix: rewrite lines 65-68 to today's facts (1.1.0 shipped 2026-09-05 without the brand-layer move; the stack rebases over it and the release carrying the move is 2.0.0), deleting the "never published" sentence and the "do not let 1.1.0 reach npm" instruction.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in commit d7c5e36.

@github-actions github-actions Bot added the risk:high PR risk grade (advisory shadow check; grader-owned) label Sep 28, 2026
@ryan-di
ryan-di added this pull request to the merge queue Oct 1, 2026
Merged via the queue into main with commit 858129a Oct 1, 2026
90 checks passed
@ryan-di
ryan-di deleted the fleet/srx-35-design-system-semver-doc branch October 1, 2026 03:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:high PR risk grade (advisory shadow check; grader-owned) risk:R1 PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants