<p align="center"><a href="CONTRIBUTING.md">English</a> | <strong>简体中文</strong></p>

# 参与贡献

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

## 项目范围<a id="project-scope"></a>

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

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

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

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

## 性能与优化<a id="performance-optimizations"></a>

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

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

## 开发流程<a id="development-workflow"></a>

我们采用标准的开源 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

## 代码质量要求<a id="code-quality-requirements"></a>

在提交 PR 之前，请确保：

- **单元测试**：为复杂或关键的代码路径添加测试
- **无死代码**：删除未使用的代码、导入和依赖
- **代码风格**：遵循代码库中已有的代码风格和模式
- **Clippy**：修复所有 clippy 警告
  ```bash
  cargo clippy --all-targets --all-features -- -D warnings
  ```
- **禁止 clippy 抑制**：不要使用 `#[allow(clippy::...)]` 来抑制警告。请修复根本问题（例如减少参数、重构代码）。如果确实无法避免，请在 PR 中说明。
- **格式化**：运行格式化工具
  ```bash
  cargo fmt
  ```
- **安全审计**：检查依赖中的已知漏洞和策略违规
  ```bash
  cargo deny check
  ```

## CI 检查<a id="ci-checks"></a>

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

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

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

## 依赖策略<a id="dependency-policy"></a>

请谨慎添加依赖：

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

## 安全<a id="security"></a>

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

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

## PR 指南<a id="pr-guidelines"></a>

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

## 重复 Pull Request<a id="duplicate-pull-requests"></a>

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

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

## AI 辅助贡献<a id="ai-assisted-contributions"></a>

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

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

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

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

## 有问题？<a id="questions"></a>

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