贡献指南 Contributing
@cloudflare/kumo

贡献指南 Contributing

为 Kumo 组件库贡献代码的指南。

开始之前

对于非小改动，先对齐再动手写代码：

  • 先在现有 issue 下评论，或新建一个 issue。
  • 确认范围、API 方向和迁移影响。
  • 小的修复或文档调整，可以直接提 PR。

1. 一次性环境设置

在仓库根目录：

pnpm install
pnpm build

要求：

  • Node ^24.12.0
  • pnpm >=10.26.0

推荐的本地设置：

  • 使用 Node 版本管理器 (nvm、fnm 等)。
  • 使用 VS Code，并选择工作区的 TypeScript 版本。
  • 如果 rebase 后依赖有变化，重新运行 pnpm install。

仓库访问与分支

内部贡献者通常直接 clone 并推送到 cloudflare/kumo:

git clone https://github.com/cloudflare/kumo.git
git switch -c <branch-name>
git push -u origin <branch-name>

如果你没有写入权限，请联系你的经理或 Kumo 维护者。

2. 选择正确的贡献类型

用下面的标准判断你的改动属于哪里：

  • 组件:位于 packages/kumo/src/components/ 的可复用 UI 原语
  • 区块:位于 packages/kumo/src/blocks/ 的可安装组合模式
  • 仅文档:位于 packages/kumo-docs-astro/ 的文档/演示/导航更新

添加新组件时，使用脚手架工具 (不要手动创建文件):

pnpm --filter @cloudflare/kumo new:component

3. 启动开发循环

在不同的终端中分别运行：

# 终端 1:监听 Kumo 包的构建输出
pnpm --filter @cloudflare/kumo dev

# 终端 2:文档站点
pnpm dev

这样你就能快速迭代，同时在真实的文档环境中验证你的改动。

4. 实现改动

典型的内部改动流程：

  1. 在 packages/kumo/src/... 中构建功能。
  2. 在 packages/kumo-docs-astro/src/components/demos/ 中添加或更新演示。
  3. 在 packages/kumo 中添加/更新测试。
  4. 在 packages/kumo-docs-astro/src/pages/ 中添加或更新文档页面。

如果你的演示要出现在注册表元数据中，演示命名必须严格符合：

  • 文件：{Component}Demo.tsx
  • 导出名必须以 Demo 结尾

实现要求：

  • 保持无障碍语义和键盘行为。
  • 保持 API 聚焦，避免一次性抽象。
  • 遵循 Kumo 现有的变体、属性 (props) 和结构模式。

5. 提 PR 前运行校验

在打开或更新 PR 之前，在仓库根目录运行：

pnpm lint
pnpm typecheck
pnpm --filter @cloudflare/kumo test

如果你改动了导出/构建行为，还要运行：

pnpm --filter @cloudflare/kumo build

可选 (视情况而定):

pnpm format
pnpm --filter @cloudflare/kumo test:run

Windsurf 和 hooks 能捕获额外的问题，但你在请求评审之前仍应在本地运行这些检查。

6. 正确处理 Changesets

如果你的改动涉及 packages/kumo/ 且需要发布，添加一个 changeset:

pnpm changeset

Changesets 指引：

  • 缺陷修复和低风险改进用 patch。
  • 向后兼容的新功能用 minor。
  • 仅破坏性改动用 major。
  • 摘要聚焦于用户可见的影响。

如果你的改动仅涉及文档，或是不可发布的包工作，通常不需要 changeset。

7. 发起并维护 PR

  • 从 main 拉分支并推送到 origin。
  • PR 标题格式：[package] 简短描述(示例：[kumo] add meter warning variant)。
  • 按 PR 模板填写测试细节和影响范围。
  • 评审开始后，优先使用后续提交，而不是强推重写后的历史。

Git 卫生要求：

  • 首次评审前，保持提交历史可读。
  • 评审开始后，避免重写已被评审过的提交。
  • 针对反馈添加后续提交 (fixup 提交即可)。

合并前必须经过 PR 评审。

PR 预览与测试

  • PR 会通过 CI 评论中的 pkg.pr.new 链接发布预发布构件。
  • 每个 PR 都应包含针对行为改动的测试。
  • Kumo 的大多数测试基于 Vitest，位于 packages/kumo 下。

发布流程 (你的改动如何发布)

  • 发布通过 Changesets 管理。
  • main 上已合并的 changeset 会驱动自动化的版本管理/发布流程。
  • 如果你需要一次紧急的、非固定节奏的发布，请联系维护者。

实用准则

  • 使用 Kumo 语义令牌，避免原生 Tailwind 颜色类。
  • 用 cn(...) 组合类名。
  • 优先扩展现有模式，而不是引入一次性 API 设计。
  • 为行为改动附上测试，而不只是渲染快照。

常见需要避免的坑：

  • 不要手动搭建组件脚手架;使用 new:component。
  • 不要依赖原生 Tailwind 颜色类 (bg-blue-500 等)。
  • 对于可发布的 packages/kumo 改动，不要跳过 changeset。

相关文档

按照 changeset 指南记录可发布的库改动，并参阅 AGENTS.md 了解约定与模式。