CONTRIBUTING.md

贡献指南

感谢参与 Folio。当前项目处于快速迭代阶段，贡献目标是：优先提交小而清晰、可验证、方便合并的改动。

1. 开始开发前

• 优先从已有 Issue 开始；准备处理某个 Issue 时，可在 Issue 下评论 /claim 或直接说明“我想认领/我来处理”。
• 如果 Issue 已被其他贡献者认领，请先沟通，避免重复实现。
• 大 Issue 可以拆成多个可独立合入的小 PR，不要求一次完成全部 roadmap。

2. Commit 规范

Commit message 尽量使用中文描述，方便维护者和中文贡献者快速理解历史。

推荐保留 Conventional Commit 类型前缀，正文使用中文：

feat: 增加流式事件重连能力
fix: 修复投资组合回撤峰值计算
refactor: 重构 Provider Router 接线
ci: 收敛 PR 检查并降低无关报错
chore: 更新依赖与开发配置

原则：

• 一个 commit 尽量只表达一个明确目的；
• 避免 update、fix bug、changes 这类无法理解具体内容的描述；
• 英文技术名词、类名、协议名可以保留，不要求强行翻译。

3. PR 要求

PR 描述至少包含：

• 改了什么；
• 为什么要改；
• 对应 Issue（如有）；
• 做了哪些验证；
• 已知未完成项或后续工作（如有）。

如果 PR 只完成大 Issue 的一个独立子能力，请明确说明 scope，不需要为了“关闭整个 Issue”扩大改动范围。

4. UI 改动与截图

只有 PR 导致用户可见的 UI 样式、布局、组件外观、文案呈现或可见状态发生变化时，才要求提供截图。

例如以下情况需要截图：

• 页面、弹窗、卡片、按钮、表格等外观或布局发生变化；
• 新增可见组件、页面或状态；
• loading / success / error / empty 等可见状态样式发生变化；
• 字体、颜色、间距、图标、格式化显示等视觉结果发生变化。

以下情况不要求截图，只需在 PR 中注明“无可见 UI 变化”：

• 纯交互逻辑调整，但最终视觉表现不变；
• URL / 输入校验、安全策略、权限判断等 UI 层逻辑修复；
• 数据绑定、状态机、事件处理、后台 IPC、缓存、持久化等内部行为变化；
• 仅增加或修改 UI 单元测试，但没有改变实际视觉结果；
• 纯内部重构。

需要截图时，最低要求：

• 至少提供一张 修改后的 UI 截图；
• 如果是在修改已有界面，优先提供 Before / After 对比截图；
• 如果是新增页面、弹窗、状态或组件，没有 Before 场景时，只提供 After 截图即可；
• 如果 PR 修改了多个关键可见状态，应覆盖最关键的状态截图。

截图应直接放在 PR 描述或评论中，保证维护者无需本地启动项目也能判断 UI 结果。

5. 测试与 CI

每个准备进入正式审核的 PR 都必须提交可复现的测试报告。仅写“已测试”“unit tests cover …”“本地通过”等描述，不视为测试报告。缺少测试报告的 PR 不会被批准。

测试报告最低需要包含：

• 环境：至少说明 Bun 版本与操作系统；
• 实际执行命令：列出真实运行过的 test / typecheck / smoke 命令；
• 结果：明确 pass / fail / skipped 数量，或给出可核对的关键输出；
• 失败说明：如果存在失败，说明是否能在当前 main 复现，是否属于已知 baseline / 平台差异；
• 与改动对应的验证：至少有一组测试真正覆盖本 PR 的核心行为。

推荐格式：

环境：Bun 1.4.2 / macOS 15.x

bun test packages/shared/src/foo.test.ts
→ 12 passed / 0 failed

bun run typecheck
→ core/shared/ui/electron 全部 exit 0

bun test --isolate
→ 1211 passed / 5 failed
→ 5 项均可在 origin/main 复现，为 Windows 路径/符号链接基线问题

PR 默认关注高信号检查：

• Typecheck；
• 与本次改动工作区相关的 Focused tests；
• Secret scan。

全仓 Unit tests 在 PR 中主要作为提示信号；如果失败来自已知 baseline、平台差异或与本 PR 无关的问题，请在测试报告中说明。未知的新回归仍应修复。

涉及以下内容时，请提供更强的验证证据：

• 金融计算与数据正确性；
• Secret / 隐私 / 权限边界；
• 数据迁移或持久化；
• Provider / 外部 API 的真实接线；
• Agent / Eval / Tool Calling 的关键执行路径；
• 会导致数据丢失或不可逆行为的修改。

这类 PR 不一定要求大型完整 E2E，但应至少提供能验证真实边界或关键集成路径的 smoke / integration 结果。

6. 保持改动可合并

• 优先小 PR，避免顺手重构大量无关代码；
• 不要为了性能或架构“完美”扩大 scope，除非确实存在明显问题；
• 新增协议或公共类型时保持向后兼容，必要时采用并行迁移；
• stacked PR 请明确依赖关系，前置 PR 合并后及时 rebase，避免重复提交历史。

7. 安全

不要提交真实 API Key、Token、Cookie、私钥、数据库连接串或包含敏感信息的截图/日志。

如需测试 Secret Redaction，请使用明显的 fake fixture，并放在测试文件中。