0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
ascend-robotascend-robotdocs: add directory structure doc, contribution guide and license docs
ad40a494创建于 14 天前历史提交

开发者贡献指南

欢迎您参与 MindSpeed 项目的开发！本指南旨在帮助您了解如何为项目做出贡献，包括开发流程、代码规范、测试要求等。

一、贡献流程

1.1 特性提案与评审

在开始开发新特性前，请遵循以下流程：

  1. 提交 issue：在 GitCode 上提交 issue，描述您想要实现的特性或修复的问题。
  2. 方案评审：
    • 华为员工：请在 WeLink 搜索 MindSpeed-Core PR检视群 进行方案评审
    • 社区贡献者：通过 issue 进行公开讨论
  3. 方案设计：编写软件方案设计文档，使用类图、序列图等软件工程语言描述整体方案和修改点，设计规范请参考MindSpeed Core设计文档。
  4. 阅读开发规范：仔细阅读本文档，遵守开发规范，不给自己挖坑，方便后续的维护。

1.2 开发流程

特性提案 → 方案评审 → 代码开发 → 测试验证 → 文档编写 → PR 提交 → CI 检测 → 代码检视 → 合入

二、代码开发规范

2.1 特性注册

  • 新增特性需通过继承 MindSpeedFeature 类进行注册，详细说明请参考特性开发文档
  • 在 mindspeed/features_manager/ 目录下按照特性维度创建文件夹
  • 特性文件应独立，功能内聚

2.2 Patch 使能规则

  • 禁止默认使能：新增特性禁止默认使能相关 patch（原生特性适配除外）
  • Patch 注册：通过 MindSpeedPatchesManager.register_patch 函数注册 patch
  • Monkey Patch 使用限制：尽量避免使用 Monkey patch，仅在无其他方案时使用

2.3 代码设计原则

  1. 架构解耦：特性本体与框架适配应解耦，方便不同框架适配使能
  2. 装饰器使用：使用装饰器时需保证原有函数一定被执行，不改变原有语义
  3. 类替换优先：如需同时 patch __init__ 和 forward，建议新建类进行替换
  4. 工厂模式：当不兼容特性对同类修改时，考虑使用工厂模式通过配置选择实现
  5. 善用抽象：使用抽象、提取、搬移等方式，提前考虑后续版本迭代，避免代码腐化
  6. 命名准确：注意函数/变量的命名准确性，请勿出现模糊表述的命名

2.4 代码质量要求

指标 限制
单个函数行数 ≤ 200 行
单个文件行数 ≤ 1000 行
命名规范 清晰准确，避免模糊表述
上帝类/函数 禁止出现

2.5 兼容性处理

  • 发现与原有特性不兼容时，需添加代码拦截报错，并在文档中添加兼容性说明

三、测试用例规范

3.1 用例位置

新增特性需在 tests_extend/unit_tests 目录下根据特性维度选择合适位置创建测试用例。

3.2 测试要求

  1. 场景覆盖率：确保测试用例覆盖主要使用场景
  2. 精简完备：用例应精简但覆盖必要场景，并不是多就好
  3. 参数化测试：使用 pytest.mark.parametrize 对多种数据类型和入参进行测试

3.3 分布式测试用例

  • 分布式测试用例可继承 unit_tests.common.DistributedTest 类
  • 注意：分布式初始化耗时较长，单卡测试用例请勿继承 DistributedTest

四、文档编写规范

4.1 文档位置

新增特性需在 docs 文件夹下根据特性维度选择合适路径存放文档。

4.2 文档内容要求

文档需包含以下内容：

  • 问题分析：清晰描述解决的问题
  • 解决方案：详细说明技术方案，请勿用一两句话概括性总结
  • 使用场景：包括使用限制和适用条件
  • 使用方法：提供代码示例和配置说明
  • 使用效果：展示性能或精度提升数据

4.3 文档格式

  • 建议使用类图、活动图、序列图等软件工程语言描述方案
  • 如有需要，添加特性之间的兼容性说明

五、代码提交与PR规范

5.1 PR 标题与描述

  • 标题：简洁完备，概括主要修改内容
  • 描述：清晰说明修改目的、内容和影响
  • 测试结果：新增特性需提供精度、性能测试结果

5.2 CI 门禁

  • 提交 PR 后，请评论 compile 触发 CI 门禁检测
  • 合入需通过门禁与至少两位开发者检视（+2）

5.3 分支管理

  • 考虑涉及分支，如有必要请在 master 和对应分支均提交 PR
  • 注意版本节奏，提前预留 PR 修改合入时间，不接受先合入再修改的要求

5.4 代码检查

  • 遵守编程规范，Code check 屏蔽需逐行检查，禁止批量无脑申请屏蔽
  • 大于 500 行的提交，需要进行代码串讲与评审
  • 严格把关质量，勿犯低级错误，发现问题请尽快解决

5.5 开源合规

  • 检查引入的开源代码的开源协议
  • 新增文件需增加对应的版权声明

5.6 提交策略

  • 小步快走：避免一次性提交大量代码
  • 质量优先：每次提交都应保证代码质量

六、社区行为准则

6.1 贡献者约定

  • 尊重他人的工作和意见
  • 保持沟通友好和专业
  • 遵循项目代码规范和最佳实践
  • 及时响应反馈和问题

6.2 问题反馈

  • 使用清晰的标题和详细的描述
  • 提供复现步骤和环境信息
  • 遵守 issue 模板要求

七、联系我们

  • GitHub/GitCode：通过 issue 和 PR 进行交流
  • 华为员工：WeLink 搜索 MindSpeed TMG群组
  • 社区讨论：加入项目的 Discussions 板块

感谢您的贡献！MindSpeed 的发展离不开每一位开发者的努力。

MindSpeed Team