企业官网建设流程全解析

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锁定为yarn@4.8.1，engines要求 Node22 || 24。可以说，这份文档是仓库贡献规范的“索引层”，而具体细节散落在 CONTRIBUTING.md、STYLE.md、REVIEWING.md、SECURITY.md 与 docs/architecture-decisions/ 等文件中——CLAUDE.md 的职责就是把这些文件串成一条可执行的操作链。

二、仓库关键目录与包命名体系

2.1 关键目录速览

CLAUDE.md 的 "Key Directories" 一节列出了六个核心位置：

从各包 package.json 可以验证这套描述：packages/app声明"backstage": { "role": "frontend" }且"private": true；packages/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 system）；
• frontend-前缀（如@backstage/frontend-plugin-api）→ 新前端系统（new frontend system）；
• backend-前缀（如@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-api（1.10.1-next.1）则对应后端插件与模块体系。因此，在packages/app-legacy与packages/app之间选择示例、或在新旧插件 API 之间选择依赖时，包名前缀是最快的判别依据。

三、代码规范（Code Standards）

CLAUDE.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 实际定义补充了底层实现：

需要特别强调的两条“红线”：

1. 禁止执行yarn build、yarn changesets version、yarn release——构建与发版由独立的发布工作流完成，PR 中不得触发；
2. 根 package.json 中release脚本确实串联了prepare-release.js → changeset version → create-release-changelog.js等步骤，说明发版链路是自动化、集中式的，个人贡献者无需也无法在本地参与。

五、Changeset 规则：版本策略与书写要求

5.1 何时必须写 Changeset

CLAUDE.md 给出的边界非常明确：

• 对packages/与plugins/目录下已发布（非 private）包产生影响的改动，必须附带 changeset；
• 这些目录之外的改动（如.patches/、.github/、docs/、根配置文件）不需要changeset；
• Changeset 文件直接手写存入/.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 对齐）：

5.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 本身刻意保持精简，把深度留给权威文档。沿着它的指引，建议按以下路径继续深入：

1. docs/contribute/project-structure.md——逐目录讲解packages/、plugins/及根文件的完整结构，理解每个包的分工（如catalog-model提供 Entity 定义与校验、integration/承载各代码托管平台公共逻辑）；
2. CONTRIBUTING.md——完整贡献指南，包括本地配置、DCO（Signed-off-by）与发布流程；
3. docs/architecture-decisions/——ADR 日志，记录项目重大架构决策（如默认目录文件格式、避免默认导出等），且“记录只增不删，只可标记为被取代/弃用”；
4. 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