domcyrus--rustnet/CONTRIBUTING.zh-CN.md

English | 简体中文

参与贡献

欢迎提交 Pull Request！无论你是修复 bug、添加功能、改进文档，还是提供反馈，所有贡献都能让 RustNet 变得更好。

项目范围

RustNet 追求小而快。并不是每个协议或功能都适合放在核心工具里，即使贡献的代码写得很好。

对于深度包检测（DPI），我们倾向于满足以下条件的协议：

• RustNet 用户中有相当一部分会在自己的网络中实际遇到。
• 能提取出可见且有用的信息（明文窗口足够宽，能提取出真正的元数据，而不仅仅是确认协议存在就进入 TLS）。
• 能以合理的维护成本融入现有架构。

如果某个协议在现代流量中很少见、几乎总是包裹在 TLS 里，或者仅服务于单一小众用户群，即使代码正确，我们也可能婉拒该 PR。请在实现任何新协议前先开一个 issue，以便我们在你投入实现时间之前确认其是否合适。

性能与优化

如果一个 PR 的出发点是性能，它必须证明相关代码确实位于真正的热点路径上。仅有微基准测试是不够的：它只能证明某个函数在孤立测试中变快了，并不能说明该函数对整体运行时间有影响。

• 先做性能分析。 在真实流量下采集火焰图（参见 PROFILING.zh-CN.md），确认相关代码确实占用了可观的 CPU 时间。
• 基准测试只是佐证，而非证明。 欢迎附上 cargo bench / criterion 的对比结果来说明你的改动更快，但这并不能证明该代码是热点。
• 冷路径上的微优化可能会被婉拒并致谢。 优化很少执行的代码（连接建立、一次性解析、错误处理）会增加 review 和维护成本，却没有有意义的收益。

开发流程

我们采用标准的开源 fork 和功能分支方式：

1. 先开 issue 讨论你打算做的改动。对于功能性和非平凡的代码重构，请在写代码之前等待维护者的回复。拼写错误、小型 bug 修复和文档勘误不需要先开 issue。
2. Fork 本仓库
3. 将 fork 克隆到本地
4. 从 main 创建功能分支（git checkout -b feature/your-feature）
5. 进行你的修改
6. 推送到你的 fork（git push origin feature/your-feature）
7. 向 main 提交 Pull Request，并引用相关 issue

代码质量要求

在提交 PR 之前，请确保：

• 单元测试：为复杂或关键的代码路径添加测试
• 无死代码：删除未使用的代码、导入和依赖
• 代码风格：遵循代码库中已有的代码风格和模式
• Clippy：修复所有 clippy 警告

  cargo clippy --all-targets --all-features -- -D warnings
  

• 禁止 clippy 抑制：不要使用 #[allow(clippy::...)] 来抑制警告。请修复根本问题（例如减少参数、重构代码）。如果确实无法避免，请在 PR 中说明。
• 格式化：运行格式化工具

  cargo fmt
  

• 安全审计：检查依赖中的已知漏洞和策略违规

  cargo deny check
  

CI 检查

当你提交 PR 时，我们的 CI 流水线会自动运行以下检查：

• Clippy lint
• 代码格式化验证
• 多平台构建
• 测试套件

请在请求 review 之前确保所有 CI 检查通过。

依赖策略

请谨慎添加依赖：

• 除非有充分的理由，否则不要添加依赖
• 尽可能优先使用标准库方案
• 如果必须添加依赖，请在 PR 描述中说明理由
• 考虑依赖的维护状态和安全记录

安全

对于网络监控工具，安全至关重要：

• 编写代码时牢记安全
• 避免引入常见漏洞（注入、缓冲区问题等）
• 谨慎处理用户输入和网络数据解析
• 请负责任地报告安全问题（参见 SECURITY.zh-CN.md）

PR 指南

• 清晰描述你的改动做了什么以及为什么
• 链接任何相关的 issue
• 保持 PR 聚焦——每个 PR 只做一件事
• 及时响应 review 反馈
• 在提交 PR 之前在本地验证。PR 模板中列出了需要执行的精确命令。

重复 Pull Request

如果两个或多个 PR 解决了同一个 issue，维护者将根据代码质量、测试覆盖率和架构契合度来评估，而不是提交顺序。最符合项目需求的 PR 将被合并；其他 PR 将被关闭并致谢。如果你的 PR 被另一个替代，你工作中的有用部分（文档、测试、边界情况）可能会被移植并给予署名。

为避免重复工作，请在开始编码之前，在相关 issue 下评论说明你有意处理它。

AI 辅助贡献

欢迎使用 AI 辅助贡献，但前提是你将其输出视为自己的作品并对其负责。

如果你使用 AI 助手（Copilot、Claude、ChatGPT、Cursor 或类似工具）来辅助编写代码或文档：

• 阅读你提交的每一行。你要对它负责。
• 自己运行 PR 模板中列出的验证命令。不要提交代码后附带一句“无法在本地运行测试”并请 reviewer 验证。
• 确保 PR 描述与代码一致。 如果模型写了 PR 正文，请确认它确实描述了 diff 实际做的事情。
• 不要把一个改动拆成多个仅涉及样式的逐文件提交 来让工作看起来是增量完成的。一个逻辑改动，一个提交，附带有意义的提交信息。
• 不要在提交 issue 的下一秒就开 PR。 给维护者和其他贡献者留出时间对你提出的方案发表意见。

那些显示出未经 review 的 AI 输出痕迹的 PR（测试失败、虚构 API、无关的捆绑改动、描述不匹配）将被关闭。

有问题？

如果你有任何问题，或者想在开始工作之前讨论潜在的贡献，欢迎随时开一个 issue。