学习笔记 · Obsidian
贡献流程与文档、代码规范
合并前的硬门槛
外部贡献不是“先写 PR 再讨论”。所有 PR 都必须：
- 关联一个 issue 或 discussion；
- 方案已被 maintainer 明确批准；
- issue 已分配给贡献者；
- 完整填写仓库 PR 模板；
- 新功能或行为变化按模板提供 release note；
- 使用英文提交 issue、PR、代码注释与文档。
未先获得批准或分配的早期 PR 可能被自动关闭。安全漏洞不应提交公开 issue，而应走仓库安全披露渠道。
使用 LLM 的边界
可以用 LLM 辅助理解、起草、测试和润色，但贡献者必须逐项理解并验证最终改动。禁止批量、低成本、未经验证的生成内容；明显的 AI spam 可能不经评审直接关闭。责任仍属于提交者，不能以“模型生成”解释错误、许可问题或未运行的测试。
文档开发工作流
文档仓库的本地基线包括 Python 3.13+、uv、Node.js/npm、Make 和 Git。只编辑 src/，build/ 是生成目录。
常用质量门：
make broken-links
make format
make lint
make lint_md_fix
make test文档应按用户意图选择类型：
| 类型 | 回答的问题 | 写作重点 |
|---|---|---|
| How-to | 如何完成具体任务 | 可执行步骤、前置条件和验证 |
| Conceptual | 为什么、是什么 | 心智模型、边界与权衡 |
| Reference | 精确接口是什么 | 完整、结构化、少叙事 |
| Tutorial | 如何从零学会 | 连贯路径、可运行成果 |
页面应有 frontmatter、清晰标题层级、可访问的替代文本和有效交叉链接。Python 与 JavaScript/TypeScript 内容在概念相同处共址维护，再生成各语言路由，减少两套文档漂移。示例代码必须能够运行，凭证用环境变量占位，不能包含真实密钥或隐私数据。
代码贡献工作流
- 先复现问题，用失败测试固定行为，再做最小修复。
- 保持向后兼容；公共 API 变化必须说明迁移方式，不能顺手扩大重构范围。
- 优先单元测试：不访问外部网络，快速、稳定，mock 外部依赖。
- 集成测试只验证真实服务接口点，通常需要凭证和额外环境，按独立流程运行。
- 新代码应补齐类型、docstring、异常处理和安全校验，并通过仓库 pre-commit 与质量检查。
- 可选依赖不能无条件导入；需要依赖的测试应使用仓库约定的
requires标记。 - 模板、查询和命令中的外部数据必须正确转义，避免注入和敏感信息泄露。
评审视角
一个可接受的贡献不仅要“测试通过”，还要回答：问题是否已获批准、改动是否最小、兼容性是否明确、失败模式是否有测试、文档是否同步、外部资源是否被安全处理、release note 是否准确。没有这些证据的 PR 即使能运行，也不满足生产级贡献标准。