Clarify

参与贡献

感谢你对 Clarify 的兴趣！以下是参与贡献的指南。

开发环境

# 克隆仓库
git clone https://github.com/taicode-labs/clarify.git
cd clarify

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev:docs    # 文档站点
pnpm dev:www     # 营销站点

代码规范

TypeScript

  • 所有代码必须是 TypeScript，strict: true
  • 优先使用显式类型，避免 any
  • 保持包的 tree-shakeable（避免副作用导入）

目录约定

  • 使用 source/ 作为源码目录，而不是 src/
  • 包当前使用 Vite library build 输出 ESM / CJS / DTS
  • 应用使用 Vite + @tailwindcss/vite + @vitejs/plugin-react
  • 面向用户的文档应描述 clarify dev / clarify build，不要要求用户维护内部 Vite 配置

提交规范

所有提交信息必须用英文编写。 不允许使用中文或其他语言。

提交格式

遵循 Conventional Commits 规范：

类型说明
feat:新功能
fix:错误修复
docs:仅文档更改
refactor:既不修复错误也不添加功能的代码更改
chore:构建过程、工具或依赖更新

提交示例

feat: add sidebar navigation component

- Add NavTree component with recursive rendering
- Support collapsible sections
- Integrate with virtual:clarify-routes

fix: resolve hydration mismatch on 404 pages

docs: update deployment guide with Vercel examples
  • 主题行控制在 72 个字符以内
  • 需要时在正文补充上下文

PR 流程

  1. Fork 仓库 并从 main 分支创建功能分支
  2. 编写代码 并确保通过类型检查
  3. 更新文档 如果更改了用户可见的行为
  4. 提交 PR 并提供清晰的描述，说明做了什么和为什么

如何选择修改位置

变更类型通常修改位置
配置加载、路由发现、插件 hooks、SSG、raw content artifactspackages/cli
Header、侧边栏、MDX 组件、OpenAPI UI、内容操作、主题行为packages/renderer
官方文档内容apps/docs/source
营销文案和落地页apps/www/source

跨 CLI 和 Renderer 的功能应先定义构建时数据形状，通过虚拟模块暴露，再在 Renderer 中消费。

验证命令

根据变更范围运行：

pnpm typecheck
pnpm build

聚焦单包时可使用：

pnpm --filter @clarify-labs/cli typecheck
pnpm --filter @clarify-labs/renderer typecheck
pnpm --filter @clarify-labs/docs build

文档变更也应尽量运行 docs build，因为 MDX 内容会参与编译。

依赖规则

  • 使用 pnpm，不要使用 npm 或 yarn
  • 跨包依赖使用 workspace:*
  • 优先选择维护良好、轻量级的库
  • 仅限 React 生态

需要帮助？