参与贡献
修改流程
- 从
main创建分支。 - 按 SDD 维护规范 判断是否需要更新需求和计划。
- 修改对应应用或文档。
- 运行与改动相关的校验，包括
pnpm run check -- --all。 - 使用 Conventional Commits 创建提交。
- 推送分支并提交 Pull Request，填写仓库 PR 检查清单。
Commit 规范
本仓库使用 Conventional Commits 规范，提交信息由提交钩子自动校验：
<type>(<scope>): <description>type
| 类型 | 用途 |
|---|---|
feat | 新增功能或能力 |
fix | 修复问题 |
docs | 仅文档变更 |
refactor | 重构，不改变外部行为 |
test | 测试变更 |
build | 构建、依赖或打包变更 |
ci | CI/CD 配置变更 |
chore | 其他维护性变更 |
perf | 性能优化 |
revert | 回滚提交 |
scope 建议使用受影响的应用名或模块名，例如 fn-memos、cli、docs。描述使用祈使句，简明说明结果，不要以句号结尾。
feat(fn-memos): add configurable storage settings
fix(fn-memos): keep the data volume on upgrade
docs(contributing): document commit conventions
chore(hooks): update lint-staged rules复杂变更可以在标题后增加正文，说明背景、实现和影响；涉及不兼容变更时，在正文或页脚注明：
BREAKING CHANGE: change the application configuration field name提交前检查
项目通过 Lefthook 自动执行以下检查：
commit-msg：使用 Commitlint 校验提交格式。pre-commit：使用 lint-staged 校验暂存的 JSON 和 Shell 文件。pre-push：执行pnpm run check -- --all。
依赖安装后会自动安装 Git hooks。需要手动重新安装时执行：
pnpm exec lefthook install应用修改检查
- Manifest 字段与应用目录保持一致。
- 生命周期脚本通过
bash -n检查。 - JSON 配置可以被解析。
- 构建产物和
.DS_Store不提交。 - 面向用户的文档只更新
docs/下的统一文档页面，不再同步维护apps/<appname>/README.md。
文档修改检查
pnpm run check -- --sdd --docs
git diff --check应用说明应统一维护在文档站中。配置较多时优先增加现有文档章节，只有在内容确实独立且篇幅较大时才拆分页面。
Workspace 目录与测试布局
tooling/fn-os-apps-cli 是仓库里唯一的 TypeScript workspace：源码放在 src/，单元测试集中放在同级 tests/，并通过 test 调用该 workspace 的 vitest.config.ts。新增测试应优先放入 tests/，按被测模块组织文件；不要把测试混入 apps/ 下的 fnOS 应用目录。
docs 是 VitePress 文档 workspace，不承担 TypeScript 单元测试；应用目录是 fnOS 打包输入，主要通过 pnpm run check -- --all、脚本语法检查、JSON 校验和设备上的 install-local 验证，而不是强行引入 Vitest。
根目录通过 Turbo 执行 pnpm test。新增构建前置步骤应说明原因并保持可重复执行。
类型定义集中策略
类型依赖采用 pnpm catalog 统一版本（根 package.json 的 catalog），而非在每个 workspace 随意锁定版本。各 workspace 的 tsconfig.json 只声明运行时确实需要的全局类型：Node workspace 使用 node。新增类型包时先确认是否已在 catalog 中；优先复用根目录版本，并在对应 workspace 的 tsconfig.json 最小化 compilerOptions.types。共享业务类型应放在实际拥有它的 package 并通过公开入口导出，避免复制声明或依赖另一个 workspace 的内部路径。类型策略变更（新增全局类型、改变共享类型归属或 catalog 版本）须在 PR 描述中说明影响，并至少运行受影响 workspace 的 typecheck 和 test。