PR 规则与政策

PR 规则

• 我们 更倾向于较小的 PR。
• 如果你有写入权限，可使用 graphite 进行堆叠式提交，该权限将在你贡献较多后授予。
• 如果 PR 包含架构变更，请先创建一个议题或讨论。

开发政策

• 采用数据驱动的设计理念。
• 保持 API 简洁且文档完善。
• 如果实现来自其他项目，请始终提供原始来源的引用。

性能

• 本项目中所有性能问题均视为缺陷，包括所有运行时和编译时性能问题。
  • 遵循 Rust 性能手册 的指导建议。
  • 尽量减少 regex crate 的使用。使用 Rust 迭代器和字符串方法以获得更好的性能。
• 编译时间必须尽可能缩短，以降低对开发流程及下游工具的影响。
  • 减少第三方依赖以提升编译速度并降低项目复杂度。
  • 避免使用复杂的宏、泛型或其他会减慢编译或增加二进制体积的 Rust 技巧。
  • 我们的 CI 流水线 运行时间控制在 3 分钟内，任何性能退化都需立即修复。

维护政策

• 监控代码覆盖率以发现未使用的代码。目标达到 99% 的代码覆盖率。
• 主动监控并优化 CI 时间，以加快合并 PR。目前在 GitHub Actions 上的平均 CI 时间约为 3 分钟。
• 文档优先：文档应作为事实真相的来源。保持文档更新，并分享链接，而非反复回答相同问题。参见 GitLab 的 手册优先 做法。
• 一致的导入顺序：从“最远”到“最近”。
  • std
  • 外部 crate
  • Oxc crate
  • 本地 crate (crate)
  • super
  • mod

约定式提交

我们遵循 约定式提交：

提交包含以下结构化元素，以向使用者传达意图：

• fix：此类提交用于修复代码库中的错误。
• feat：此类提交用于引入代码库中的新功能。
• BREAKING CHANGE：在类型/作用域后附加 !，表示引入了破坏性 API 变更，例如 feat(parser)!: new feature。
• 作用域为 crate 名称。
• 类型包括 feat:、fix:、chore:、ci:、docs:、style:、refactor:、perf: 和 test:。

行动政策

摘自 Astral 的价值观：

我们倾向于采取行动，即使面对不确定性。我们更重视 务实执行 而非 长期争论；我们更倾向于事后请求 宽恕 而非事先获取 许可。我们珍视 决断力 —— 尤其是当决策并非清晰明确时，以及当决策可逆时更显重要。

倾向于行动并不等于鲁莽。相反，它是一种倾向于做出 负责任 的决策，并以 紧迫感 付诸实施，即使我们仍存在持续的模糊性或已知的未知因素。