贡献流程和规范说明

感谢您考虑参与贡献！我们欢迎任何形式的贡献，包括错误修复、功能增强、文档改进等，甚至只是简单的使用反馈。
无论您是经验丰富的开发者，还是首次参与开源项目的新手，您的贡献都非常宝贵。

您可通过以下方式支持本项目：

• 代码贡献：修复已知 Bug、优化性能、重构改进或实现新功能，请遵循后文的贡献流程和代码规范提交代码。
• 问题反馈：通过 Issue 报告 Bug 、提出功能建议或使用疑问，或参与需求评审与方案讨论。
• 文档完善：纠正文档错误、补充缺失内容、优化表述，或编写使用示例与教程，请遵循文档资料规范。
• 质量保障：补充或完善测试用例，审查 Pull Request 并提供建设性意见，协助其他贡献者改进代码质量。
• 社区推广：在 Issue/PR 中解答问题、分享使用经验与最佳实践，或通过撰写博客、教程及在技术社区、社交媒体等渠道宣传推广项目。

1. 贡献流程

1. 派生仓库：Fork 源代码仓库到个人仓库，然后将个人仓库克隆到本地开发环境。
2. 创建分支：基于最新的主分支创建功能分支，分支命名应简洁且能反映变更内容（如 fix_xxx_bug、feature_xxx）。
3. 代码开发：在功能分支上进行开发，请遵守代码规范，并保持提交记录清晰、原子化。
4. 本地测试：对代码进行充分的功能验证，根据开发模块情况按需补充单元测试，确保所有测试通过。
5. 文档更新：补充或更新与变更相关的文档，请遵守文档规范。
6. 请求合并：提交 PR ，请遵守 Pull Request 规范，详细流程参见 Pull Request 流程说明。
7. 跟踪合入：跟踪 Pull Request 进度，及时响应评审意见并修改代码，直至通过审查并合并入主线。

2. 代码规范

2.1 Python 代码规范

• 编码规范：遵循 PEP 8，建议使用 flake8 或 pylint 进行静态检查。
• 风格要求：单行代码长度不超过 120 个字符，函数超过 30 行要考虑拆分以提升可读性。
• 注释要求：复杂逻辑与公共接口需有注释，模块、类及关键函数应写 docstring 说明用途、参数与返回值。
• 异常处理：正确处理异常，禁止吞掉异常而不处理或记录；关键路径需确保资源释放。

2.2 C++ 代码规范

• 风格一致：遵循项目现有编码风格，与周边代码保持一致。
• 命名规范：类名和结构体大驼峰（如 DataManager），函数名小驼峰（如 parseData）。
• 注释要求：复杂逻辑与公共接口需有注释，说明功能、参数及返回值。
• 异常处理：正确处理异常，禁止吞掉异常而不处理或记录；资源获取采用 RAII，确保异常安全。

3. 文档资料规范

• 表述简洁：使用简洁明了的中文表述，避免歧义与冗余，技术术语保持统一。
• 结构清晰：标题层级分明，章节划分合理，重要结论或注意事项可适当突出。
• 示例完整：提供可运行的完整示例代码，注明运行环境或依赖，关键步骤配有说明。
• 图文并茂：复杂流程、配置项或界面操作需配必要图表，便于读者理解。

4. Pull Request 规范

• 体量适中：单次 PR 变更不宜过大，便于审查者理解与快速反馈。
• 单一职责：一个 PR 只解决一个问题或实现一个功能，便于回溯与合并。
• 及时响应：收到审查意见后及时回复或修改，避免阻塞合并流程。

5. Pull Request 流程说明

5.1 提交前检查清单

在提交 Pull Request 之前，请确保：

• 代码遵循项目的编码规范。
• 添加了必要的测试用例。
• 所有测试通过。
• 更新了相关文档。
• 提交信息清晰明确。
• 代码已经过自我审查。

5.2 创建 PR

在 GitCode 上创建 Pull Request 时，请完整填写以下内容：

1. 标题：简明概括本次变更的主题或功能。
2. 描述：说明更改内容、修改原因、自测情况（含环境与结果），便于审查者理解。
3. 关联 Issue：PR 要与 Issue 关联，便于追溯。

5.3 代码审查

1. 提交 PR 后，由 Reviewers 与 Committers 进行内容审核。
2. 根据评审意见修改代码并推送更新；可能需多轮迭代，请及时响应并保持沟通。

5.4 代码合并

PR 须依次获得以下四个标签后方可合入主干：

标签	说明
ascend-cla/yes	CLA 签署：首次贡献需完成 CLA 签署，后续提交会自动获得此标签。
ci-pipeline-passed	CI 通过：在 PR 中评论 compile 触发流水线；未通过时按提示修改后重新提交。
lgtm	Reviewer 通过：2个 Reviewers 审核通过后，在 PR 中评论 /lgtm 获得。
approved	Committer 通过：Committers 审核通过后，在 PR 中评论 /approved 获得。

集齐上述四个标签后，PR 将合并至主干分支。