Backstage 仓库贡献者指南深度解析从 .claude/CLAUDE.md 读懂 Monorepo 开发规范与 Changeset 流程【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage本文以 Backstage 仓库中的贡献者指南文件 CLAUDE.md 为核心结合仓库根配置、示例包与 Changeset 实例系统讲解 Backstage 这个 Yarn workspaces TypeScript Monorepo 的目录组织、三大前端/后端系统命名规则、本地开发命令、Changeset 版本规则以及 PR 提交约束。读完本文后你可以按照官方规范独立完成从yarn install到提交 Changeset 的完整贡献流程。一、这份文档的定位Backstage 的贡献者“操作手册”CLAUDE.md 位于仓库根目录的.claude/目录下是一份标注了alwaysApply: true的指南文件其作用是让任何进入仓库的协作者包括人类贡献者与 AI 编程 Agent第一时间掌握 Backstage 的仓库结构与硬性规范。它开宗明义地给出了项目定义Backstage is an open platform for building developer portals. This is a TypeScript monorepo using Yarn workspaces.这一表述与仓库根 package.json 中的实际配置完全吻合workspaces字段声明了packages/*与plugins/*两个工作区packageManager锁定为yarn4.8.1engines要求 Node22 || 24。可以说这份文档是仓库贡献规范的“索引层”而具体细节散落在 CONTRIBUTING.md、STYLE.md、REVIEWING.md、SECURITY.md 与 docs/architecture-decisions/ 等文件中——CLAUDE.md 的职责就是把这些文件串成一条可执行的操作链。二、仓库关键目录与包命名体系2.1 关键目录速览CLAUDE.md 的 Key Directories 一节列出了六个核心位置目录内容packages/核心框架包包名以backstage/为前缀plugins/插件包包名以backstage/plugin-*为前缀packages/app使用新前端系统的主示例应用example-app私有包packages/app-legacy使用旧前端系统的示例应用example-app-legacy私有包packages/backend本地开发用的示例后端example-backend私有包docs/全部文档文件从各包 package.json 可以验证这套描述packages/app声明backstage: { role: frontend }且private: truepackages/backend声明backstage: { role: backend }。而 docs/contribute/project-structure.md 则进一步解释了每个包的职责如config/负责配置合并、config-loader/只负责读取、cli/封装了构建/测试/脚手架等工具链CLAUDE.md 末尾的 Repository Structure 一节正是指向该文档作为权威参考。2.2 三大系统的包前缀规则文档中一条极其实用的命名约定值得重点记住core-前缀如backstage/core-plugin-api→ 旧前端系统legacy frontend systemfrontend-前缀如backstage/frontend-plugin-api→ 新前端系统new frontend systembackend-前缀如backstage/backend-plugin-api→ 后端系统。对照仓库实际版本即可印证两套前端系统的代际差异backstage/core-plugin-api当前版本为1.12.10-next.1已越过 1.0而backstage/frontend-plugin-api仍为0.18.1-next.1尚处于 0.x 快速演进期两者并存于仓库中正是 Backstage 新前端系统迁移期的典型特征。backstage/backend-plugin-api1.10.1-next.1则对应后端插件与模块体系。因此在packages/app-legacy与packages/app之间选择示例、或在新旧插件 API 之间选择依赖时包名前缀是最快的判别依据。三、代码规范Code StandardsCLAUDE.md 的 Code Standards 一节浓缩了四类硬性规则每一条都能在仓库中找到对应落地物。3.1 Apache 2.0 版权头所有新源文件.ts、.tsx、.js、.jsx必须包含带当前年份的 Apache 2.0 版权头但不适用于生成文件、配置文件JSON、YAML和文档文件同时明确禁止更新已有文件的版权年份保留原始年份。仓库中的实际文件均遵循此格式例如 packages/config/src/index.ts 开头即为/* * Copyright 2020 The Backstage Authors * * Licensed under the Apache License, Version 2.0 (the License); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 */根 package.json 中还通过eslint-plugin-notice与spotify/eslint-plugin将版权头检查纳入了 lint 链路与 STYLE.md 中“通过 ESLint Prettier 保证风格一致”的说明相互呼应。3.2 跟随所在包的既有风格文档强调写代码时必须匹配每个包、每个文件既有的编码风格Monorepo 内不同包可能采用不同约定“包内一致性优先于全仓库一致性”。具体的 TypeScript 风格基线如类型名用 PascalCase、接口不加I前缀、使用undefined而非null、index.ts只做 re-export、错误统一依赖backstage/errors等则收录在 STYLE.md 中。3.3 测试编写倾向文档给出两条可操作的测试规范宁少而全优先编写少量断言密集的测试而非大量碎片化小测试React Testing Library 用法优先使用screen与.findBy*异步查询代替waitFor并且不要为可测性在业务实现中加 test ID。根 package.json 的jest配置中rejectFrontendNetworkRequests: true也体现了仓库对测试确定性的严格态度——前端测试中一旦发起真实网络请求即判失败。四、开发流程Development Flow命令全解这是 CLAUDE.md 中最具实战价值的部分所有命令都必须在项目根目录执行且执行前必须先运行yarn install。下表在原文档基础上结合根 package.json 的 scripts 实际定义补充了底层实现场景命令底层实现package.json scripts要点安装依赖yarn installpostinstall触发 husky其余命令的前提构建开发期间无需构建build:all为backstage-cli repo build --allCI 流水线自动校验严禁手动yarn build测试CI1 yarn test pathNODE_OPTIONS--experimental-vm-modules backstage-cli repo test必须提供单文件/目录路径避免跑全量测试类型检查yarn tscNODE_OPTIONS--max-old-space-size8192 tsc只能在根目录执行不得附加任何选项格式化yarn prettier --write paths配置引用backstage/cli/config/prettier只格式化明确改动的文件路径勿整目录执行Lintyarn lint --fixbackstage-cli repo lint --since origin/master增量 lintAPI 报告yarn build:api-reports底层为backstage-repo-tools api-reports含--tsc与 SQL 报告参数提交涉及工作区包改动的 PR 前必须执行本地启动yarn startbackstage-cli repo start前端 :3000后端 :7007脚手架yarn newbackstage-cli new新建插件/包/模块create-plugin、dev脚本已废弃并提示改用新命令需要特别强调的两条“红线”禁止执行yarn build、yarn changesets version、yarn release——构建与发版由独立的发布工作流完成PR 中不得触发根 package.json 中release脚本确实串联了prepare-release.js → changeset version → create-release-changelog.js等步骤说明发版链路是自动化、集中式的个人贡献者无需也无法在本地参与。五、Changeset 规则版本策略与书写要求5.1 何时必须写 ChangesetCLAUDE.md 给出的边界非常明确对packages/与plugins/目录下已发布非 private包产生影响的改动必须附带 changeset这些目录之外的改动如.patches/、.github/、docs/、根配置文件不需要changesetChangeset 文件直接手写存入/.changeset目录禁止使用 changesets CLI与 CONTRIBUTING.md 中yarn changeset的传统流程相比这是当前仓库对 AI 协作场景的新约定实际.changeset/目录中也确有大量手写命名的文件如 calm-tasks-rest.md。真实示例——.changeset/calm-tasks-rest.md 的结构是标准三段式YAML frontmatter 声明包名与 bump 级别正文一句面向用户的变更描述--- backstage/plugin-scaffolder-backend: patch backstage/plugin-scaffolder-common: patch --- Exclude internal task data from task responses.5.2 版本 bump 决策矩阵文档给出的版本策略与 CONTRIBUTING.md#creating-changesets 及 SemVer 对齐改动类型包版本 1.0.0包版本 ≥ 1.0.0Breaking changeminormajor新增 API/功能非破坏patchminor修复、文档等patchpatch5.3 消息书写规范每个 changeset 消息必须只针对其所属包、以 Backstage 使用者为读者用通俗语言描述用户可感知的行为变化永远不要引用函数名、类名、变量名等不属于公共 API 的内部符号跨多个包的改动通常要拆成多个 changeset分别定制措辞CONTRIBUTING.md 中补充了正反例差的写法是笼统的 “Fixed table layout”好的写法是 “Fixed bug in EntityTable component where table layout did not readjust properly below 1080x768 pixels”类型检查器无法捕获的破坏性变更须以BREAKING加粗标注并附上需要用户修改的diff示例。六、文档更新与 Pull Request 规范6.1 文档必须随功能变更任何引入新特性或修改既有行为的改动都必须同步更新文档落点按适用性三选一TSDoc 注释、包 README或 docs/ 目录行文风格遵循 docs/contribute/doc-style-guide.md美式英语、语气专业而友好、尊重读者时间等。根 package.json 的lint-staged配置中*.md会触发node ./scripts/check-docs-quality说明文档质量检查已嵌入提交钩子。6.2 PR 流程约束开 PR 前先检索是否已存在相同改动的 PR避免重复劳动使用 .github/PULL_REQUEST_TEMPLATE.md 模板不得清空或替换模板只勾选确实完成的项目changeset、文档、测试、截图、Signed-off-by 等PR 描述保持简短设计动机、迁移背景等长内容建议开 issue 并从 PR 中链接而不是塞进 PR 正文与已有 issue 相关的 PR 必须在描述中链接该 issue。6.3 明确禁止项CLAUDE.md 还列出了三条“不可触碰”清单对自动化协作尤其重要不得更新ESLint、Prettier、TypeScript 配置文件除非被明确要求不得修改docs/releases 下的发布说明——它们记录的是历史版本不应被新改动波及结合第四节的yarn build/yarn release禁令形成完整的“本地红线”。七、延伸阅读从 CLAUDE.md 出发继续深入CLAUDE.md 本身刻意保持精简把深度留给权威文档。沿着它的指引建议按以下路径继续深入docs/contribute/project-structure.md——逐目录讲解packages/、plugins/及根文件的完整结构理解每个包的分工如catalog-model提供 Entity 定义与校验、integration/承载各代码托管平台公共逻辑CONTRIBUTING.md——完整贡献指南包括本地配置、DCOSigned-off-by与发布流程docs/architecture-decisions/——ADR 日志记录项目重大架构决策如默认目录文件格式、避免默认导出等且“记录只增不删只可标记为被取代/弃用”STYLE.md 与 REVIEWING.md——TypeScript 编码风格与 PR 审查/checklist 细则。总结CLAUDE.md 虽不足百行却完整覆盖了在 Backstage Monorepo 中“看懂结构 → 遵守风格 → 跑通命令 → 写对 Changeset → 提交规范 PR”的完整贡献闭环。其设计思路值得其他大型 Monorepo 参考用一份始终生效的指南文件收敛高频规则再用包名前缀core-/frontend-/backend-这样可机械判别的约定降低认知成本最后以 changeset 手写规范 发布红线保证版本治理不被个人操作干扰。掌握本文内容后你就可以直接依据仓库现状开展 Backstage 的本地开发与贡献工作。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考