Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Repository navigation
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Docs:ci-cd-pipeline.md 的工作流清单与 ci.yml 一节仍与实际不符(11 vs 12、两个工作流没被记录、五个任务名里三个不存在) #3212

Closed
#3253
Closed
Docs:ci-cd-pipeline.md 的工作流清单与 ci.yml 一节仍与实际不符(11 vs 12、两个工作流没被记录、五个任务名里三个不存在)#3212
#3253
Assignees
xuyushun441-sys
Labels
documentationImprovements or additions to documentationpm:dispatchedpm:queue

Description

@os-zhuang
os-zhuang
opened on Aug 2, 2026

在 #3197 的修复过程中发现(那个 PR 只改 Performance Budget / Size Check 两节,按 Prime Directive #10 拆出来单独记录,不夹带)。同一页 content/docs/guide/ci-cd-pipeline.md 还有两处与 .github/workflows/ 脱节,和 #3197 是同一类问题但不同位置。

1. 工作流数量与清单

开头一句:

ObjectUI uses 11 GitHub Actions workflows to automate testing, quality checks, security scanning, releases, and repository maintenance.

.github/workflows/ 实际有 12 个:changelog.yml、changeset-release.yml、check-links.yml、ci.yml、cross-repo-issue-closer.yml、dependabot-auto-merge.yml、labeler.yml、lint.yml、performance-budget.yml、release.yml、shadcn-check.yml、stale.yml。

其中两个在正文和 ASCII 总览图里都完全没有出现:

  • lint.yml —— 这个漏得最要命,它是真的 PR 门禁。文件头的注释写着:#2923 之前它是 workflow_dispatch-only,导致 eslint.config.js 里三条设成 error 的 object-ui/* 规则(ADR-0054 Phase 5、9 个文件复制了 createSafeTranslation,并保留了 #2595/#2596 已修复的 try/catch-around-hook 违规 #2879、objectql.ts ratchet)全部空转。现在它会拦 PR,但读文档的人不会知道有这么一道检查,更不会知道它只管 error 不管 warning。
  • cross-repo-issue-closer.yml —— 跨仓库关 issue 的自动化,文档里一个字都没有。

2. ci.yml 一节列的五个任务,三个不存在

文档:

Runs five parallel jobs:
Test / Lint / Build Core / E2E Tests / Build Docs

ci.yml 实际的 job key 与 name(共 7 个):

job key name
changeset-check Changeset Fixed Group Check
type-check Type Check
test Test (shard N/4)
test-coverage Test (coverage) —— 仅 push 时跑
e2e Build & E2E
docs Build Docs
dev-server Dev-server fixture build

对不上的地方:

  • Lint 根本不是 ci.yml 的 job,它是独立的 lint.yml(见上)。
  • Build Core 没有对应的 job。ci.yml 里那段注释明说包构建和体积检查是交给 Bundle Analysis 工作流的:# package build and package-size checks are covered by the Bundle Analysis workflow。
  • Test 现在是 4 分片矩阵,另有一个只在 push 上跑的 coverage 任务;文档看不出来。
  • changeset-check、type-check、dev-server 三个任务完全没被记录 —— changeset-check 会因为缺 changeset 而拦 PR,这是作者最需要提前知道的一条。

建议

一次 docs-only PR:把开头的数量改成按实际清单枚举(或干脆不写数字),补 lint.yml / cross-repo-issue-closer.yml 两节,重写 ci.yml 一节的任务表。

顺带一提,#3197 加的 scripts/__tests__/ci-cd-pipeline-doc.test.ts 已经钉住了正向:文档提到的每个 *.yml 都必须真实存在。反向(存在的工作流都必须被记录)当时没加,正是因为加了会立刻因为本 issue 描述的这两个遗漏而红。等这一页的清单修对了,把反向断言补上就能让"漏记一个新工作流"也变成 CI 失败 —— 那才是这类漂移的终点。

Activity

  1. os-zhuang
    added
    documentationImprovements or additions to documentation
    pm:queue
    on Aug 2, 2026
  2. xuyushun441-sys
    added
    pm:dispatched
    on Aug 3, 2026
  3. xuyushun441-sys
    self-assigned this
    on Aug 3, 2026

  4. xuyushun441-sys commented on Aug 3, 2026

    @xuyushun441-sys
    xuyushun441-sys
    on Aug 3, 2026 – with Claude
    Contributor

    认领:PM 循环第 2 轮
    会话:session_01NVPjPzmmAJ2Ngtvgg5MSRa(objectui 分片 PM,账号 xuyushun441-sys,已在 objectstack#4604 登记)
    分支:claude/issue-3212-ci-cd-doc-drift
    Worktree:objectui-issue-3212

    ⚠️ 复核记录:本单不是过期,是数字又变了

    在 origin/main 上实测,派发前必须更新的前提:

    工作流实际有 13 个,不是单里说的 12 个。 单子填写后又新增了 changeset-guard.yml:

    changelog.yml  changeset-guard.yml  changeset-release.yml  check-links.yml
ci.yml  cross-repo-issue-closer.yml  dependabot-auto-merge.yml  labeler.yml
lint.yml  performance-budget.yml  release.yml  shadcn-check.yml  stale.yml

    文档开头仍写 11。三个数(文档 11 / 单子 12 / 实际 13)互不相同 —— 这正好把本单的论点变强了:手写数字必然漂移,单子里"或干脆不写数字"那条建议应当采纳,不要把 11 改成 13 了事。

    ci.yml 一节的问题依旧成立,job key 实测为 changeset-check / type-check / test / test-coverage / e2e / docs / dev-server,文档写的 "Runs five parallel jobs: Test / Lint / Build Core / E2E Tests / Build Docs" 里 Lint 与 Build Core 都不是 ci.yml 的 job。

    changeset-guard.yml 也要一并记进去 —— 它今天是真门禁(PR 上以 Changeset Bump Policy 名义出现,本轮三个 PR 都跑了它)。

    派发范围

    1. 修正工作流清单一节(枚举实际 13 个,含此前完全没被记录的 lint.yml、cross-repo-issue-closer.yml、以及新增的 changeset-guard.yml);
    2. 重写 ci.yml 一节的任务表,按真实 job key/name,写清 test 是 4 分片矩阵、test-coverage 只在 push 跑;
    3. 补上反向断言 —— 单子末尾说 Docs:ci-cd-pipeline.md 的 Performance Budget / Size Check 两节与实际工作流不符(预算数字差 5.8 倍、记录了一个不存在的工作流) #3197 已钉住"文档提到的每个 *.yml 必须真实存在"(scripts/__tests__/ci-cd-pipeline-doc.test.ts),但反向("存在的工作流都必须被记录")当时没加,因为一加就会因本单描述的遗漏而红。清单修对之后必须补上这一条,否则下一个新增工作流(就像 changeset-guard.yml 这次)又会静默漂移。这是本单真正的终点,不是可选项。

    ⛔ 硬约束:docs-only + 那条测试。不要改任何工作流 YAML —— 本单是让文档追上现实,不是改现实。

    Generated by Claude Code

  5. xuyushun441-sys
    closed this as completedin #3253on Aug 3, 2026

  6. xuyushun441-sys commented on Aug 3, 2026

    @xuyushun441-sys
    xuyushun441-sys
    on Aug 3, 2026 – with Claude
    Contributor

    PM 验收:ACCEPT — PR #3253,已入合并队列

    项 结果
    PR targets main、Fixes objectstack-ai/objectui#3212 ✅
    改动范围 ✅ 2 个文件:content/docs/guide/ci-cd-pipeline.md + scripts/__tests__/ci-cd-pipeline-doc.test.ts。零工作流 YAML 改动(硬约束被遵守)
    content/docs/releases/ 零改动 ✅
    CI ✅ 12 绿 + 2 skipped,零失败(4 个 test shard 全绿 —— 它们真的在跑新断言)

    数字被删掉而不是改成 13,这是对的

    我在派发里说"不要只把 11 改成 13",它照做了,并且把理由写进了页面本身:「本页刻意不写工作流数量……#3212 提出时是 12,修好时已是 13。手写数字必然漂移,而过期的数字读起来仍然像权威。」被钉住的改成集合而不是计数。

    顺带删掉了 ASCII 总览框 —— 判断正确:那是同一份清单的第二份手工副本,而且漂移得一模一样。留着它等于留两个必须同步的真相源。

    反向断言做到了位,而且三个方向都验证了

    • (a) 新增一个 zz-sabotage-check.yml → 红,并给出可执行的补救文案(加一个含文件名的 heading,或写进豁免表并说明理由);
    • (b) 把 ## Lint (lint.yml) 的标题改成 ## Lint(即文件名从标题里消失)→ 红。要求 heading 而不是"页面里提到过" 是关键:文件名埋在表格行或 ASCII 框里正是本页沦落至此的方式;
    • (c) 往 DOCUMENTATION_EXEMPT 里塞一个不存在的条目 → 红(「names gone.yml, which no longer exists — drop it」)。豁免表自己也被守着,不会烂成永久缺口。

    豁免表被刻意留空并写明理由:「在本仓运行的工作流就是能拦住贡献者的工作流,所以'不值得写一节'是一个必须显式声明并被审查的主张,而不是悄悄跳过页面」。

    清单里最有价值的一列:显示名 ≠ 文件名

    performance-budget.yml 在检查列表里叫 Bundle Analysis,changeset-guard.yml 叫 Changeset Bump Policy。这正是"我 PR 上这个红的检查对应哪个工作流"最难查的一步,此前页面完全没有。

    ⚠️ 它更正了原单的一处事实错误,我接受这个更正

    原单写:「changeset-check 会因为缺 changeset 而拦 PR,这是作者最需要提前知道的一条。」

    这句话是错的。 该 job 跑的是 scripts/check-changeset-fixed.mjs,校验的是「每个 workspace 包都在 changeset fixed 组里或被显式忽略」——它检查的是分组成员资格,不检查 PR 有没有加 changeset。PR 里的文档按脚本的实际行为写,是对的。

    这条更正对我自己有后果,见下。

    越界发现 #3261,已入队

    lint.yml 的头注释说 eslint.config.js 里有"三条" object-ui/* 规则设为 error,实际已是四条(新增 no-inline-spec-config),且引用的三个来源也对不上了。它没有顺手改 —— 因为我给的硬约束是"不许碰工作流 YAML",这个约束在这里起了作用(它挡住了一次范围蔓延),但也意味着这处残留要单独修。新写的文档一节刻意回避了这个数字,所以只有 YAML 注释是过期的。

    Generated by Claude Code

  7. akarma-synetal
    added 2 commits that reference this issue on Aug 3, 2026

    docs(ci): 工作流清单按实际枚举，ci.yml 任务表重写，并补上反向断言 (objectstack-ai#3212) (obje…

    971302e

    docs(ci): 删掉 ci.yml 任务表里的幽灵 dev-server 行，并给任务表加双向 pin (objectstack-ai…

    ea63064
  8. os-zhuang
    added a commit that references this issue on Aug 18, 2026

    chore(ci): document the snippet gate and classify its check run (#5138)

    24faa71
  9. akarma-synetal
    added a commit that references this issue on Aug 23, 2026

    feat(scripts): compile documentation snippets against the built types (…

    7a1cc68
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationpm:dispatchedpm:queue

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions