wehub-resource-sync
6.1 KiB
English | 简体中文
参与贡献
欢迎提交 Pull Request！无论你是修复 bug、添加功能、改进文档，还是提供反馈，所有贡献都能让 RustNet 变得更好。
项目范围
RustNet 追求小而快。并不是每个协议或功能都适合放在核心工具里，即使贡献的代码写得很好。
对于深度包检测（DPI），我们倾向于满足以下条件的协议：
- RustNet 用户中有相当一部分会在自己的网络中实际遇到。
- 能提取出可见且有用的信息（明文窗口足够宽，能提取出真正的元数据，而不仅仅是确认协议存在就进入 TLS）。
- 能以合理的维护成本融入现有架构。
如果某个协议在现代流量中很少见、几乎总是包裹在 TLS 里，或者仅服务于单一小众用户群，即使代码正确，我们也可能婉拒该 PR。请在实现任何新协议前先开一个 issue，以便我们在你投入实现时间之前确认其是否合适。
性能与优化
如果一个 PR 的出发点是性能，它必须证明相关代码确实位于真正的热点路径上。仅有微基准测试是不够的：它只能证明某个函数在孤立测试中变快了，并不能说明该函数对整体运行时间有影响。
- 先做性能分析。 在真实流量下采集火焰图（参见 PROFILING.zh-CN.md），确认相关代码确实占用了可观的 CPU 时间。
- 基准测试只是佐证，而非证明。 欢迎附上
cargo bench/ criterion 的对比结果来说明你的改动更快，但这并不能证明该代码是热点。 - 冷路径上的微优化可能会被婉拒并致谢。 优化很少执行的代码（连接建立、一次性解析、错误处理）会增加 review 和维护成本，却没有有意义的收益。
开发流程
我们采用标准的开源 fork 和功能分支方式：
- 先开 issue 讨论你打算做的改动。对于功能性和非平凡的代码重构，请在写代码之前等待维护者的回复。拼写错误、小型 bug 修复和文档勘误不需要先开 issue。
- Fork 本仓库
- 将 fork 克隆到本地
- 从
main创建功能分支（git checkout -b feature/your-feature） - 进行你的修改
- 推送到你的 fork（
git push origin feature/your-feature） - 向
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。