Contributing

开始之前

对于非简单的改动，编写代码之前先对齐以下几点：

先在现有 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。

仓库访问与分支

Internal contributors normally clone and push directly to cloudflare/kumo:

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

如果你没有写权限，请联系你的主管或 Kumo 维护者。

2. 选择正确的贡献类型

根据以下分类确定你的改动应归属到哪里：

组件（Component）：packages/kumo/src/components/ 下可复用的 UI 原语
块（Block）：packages/kumo/src/blocks/ 下可安装的组合模式
仅文档：packages/kumo-docs-astro/ 下的文档、demo 和导航更新

添加新的组件时，请使用脚手架生成（不要手动创建文件）：

pnpm --filter @cloudflare/kumo new:component

3. 启动开发循环

请在两个独立的终端中运行：

# Terminal 1: watch Kumo package output
pnpm --filter @cloudflare/kumo dev

# Terminal 2: docs site
pnpm dev

这样你可以在实际文档环境中验证改动的同时，获得快速的开发循环。

4. 实现改动

典型的内部改动流程：

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

如果你希望 demo 出现在注册表元数据中，请保持 demo 命名完全一致：

文件名：{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 和 git hooks 能捕获其他问题，但在请求评审之前，你仍应在本地运行检查。

6. 正确处理 Changesets

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

pnpm changeset

Changeset 使用指引：

使用 patch 发布 bug 修复和低风险改进。
使用 minor 发布新的向后兼容功能。
仅在破坏性变更时使用 major。
保持摘要聚焦于用户可见的影响。

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

7. 开启并维护 PR

从 main 创建分支并推送到 origin。
PR 标题格式：[package] short description（示例：[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。