昇思贡献指南

• 昇思贡献指南
  • 贡献者许可协议
  • 开始
  • 贡献流程
    • 代码风格
    • Fork-Pull开发模式
    • 报告问题
    • 提交PR

贡献者许可协议

在你第一次提交代码给昇思社区之前，需要签署CLA，对于个体贡献者，详情请参照CLA在线文档

开始

• 可以在github或者Gitee仓库上进行Fork。
• 阅读README_CN.md和安装指导来获取项目信息和编译指令

贡献流程

代码风格

为了昇思的易于审核、维护和开发，请遵循如下规范

• 代码规范

  在昇思社区，Python代码风格可以参考Python PEP 8 Coding Style，C++ 代码规范可以参考Google C++ Coding Guidelines。 可以使用CppLint，CppCheck，CMakeLint, CodeSpell, Lizard, ShellCheck 和 PyLint，进行代码格式检查，建议将这些插件安装在你的IDE上。

• 单元测试

  Python单元测试风格建议采用pytest，C++ 单元测试建议采用Googletest Primer。测试用例的测试目的应该在命名上体现

• 重构

  我们鼓励开发者重构我们的代码，来消除code smell。所有的代码都必须经过代码风格检验、测试检验，重构代码也不例外。Lizard阈值，对于nloc((lines of code without comments)是100，cnc (cyclomatic complexity number)是20，如果你收到一个Lizard警告，你必须在合入仓库前重构你的代码。

• 文档

  我们使用MarkdownLint来检查markdown文档的格式。昇思的门禁在基于默认配置的情况下修改了如下的规则：

  • MD007（无序列表缩进）：indent参数设置为4，即所有无序列表的内容都是缩进四个字节。
  • MD009（行末空格）：br_spaces参数设为2，即行末可以有0个或者两个空格。
  • MD029（有序列表序号）：style参数设置为ordered，即有序列表按照升序排列

  具体细节，请参考RULES。

Fork-Pull开发模式

• Fork昇思仓库

  在提交昇思项目代码之前，请确保昇思已经被fork到你自己的仓库当中，这可以使得昇思仓库和你的仓库并行开发，因此请确保两者之间的一致性。

• Clone远程仓库

  如果你想下载代码到你的本地机器，请使用git。

  # For GitHub
  git clone https://github.com/{insert_your_forked_repo}/mindspore.git
  git remote add upstream https://github.com/mindspore-ai/mindspore.git
  # For Gitee
  git clone https://gitee.com/{insert_your_forked_repo}/mindspore.git
  git remote add upstream https://gitee.com/mindspore/mindspore.git

• 本地代码开发

  为了保证并行分支之间的一致性，在开发代码前请创建一个新的分支：

  git checkout -b {new_branch_name} origin/master

  说明：origin 为昇思官方仓库，注意在创建自己仓库时尽量避免出现origin关键字，以免出现混淆

• 推送代码到远程仓库

  在更新代码之后，你需要按照如下方式来推送代码到远程仓库：

  git add .
  git status # Check the update status
  git commit -m "Your commit title"
  git commit -s --amend #Add the concrete description of your commit
  git push origin {new_branch_name}

• 对昇思仓库提交推送请求--提交PR

  在最后一步，你需要在你的新分支和昇思master分支提交一个比较请求。在这之后，Jenkins门禁会自动运行创建测试，之后你的代码会被合入到远程主仓分支上。

报告问题

当你遇到一个问题时,提交一个详细的问题单会对昇思有很大的贡献，我们永远欢迎填写详细、全面的issue。

当报告issue时，参考下面的格式：

• 你使用的环境(mindspore、os、python等)是什么版本的
• 这是一个BUG REPORT还是一个FEATURE REQUEST
• 这个问题的类型是什么，在issue dashbord上添加标签并进行高亮
• 发生了什么问题
• 你期望的结果是什么
• 如何复现
• 对审核人员必要的注释

issues 警告:

如何确定哪一个issue是你要解决的？ 请添加一些commits在这个issue上，以此来告诉其他人你将会处理它。 如果一个issue已经被打开一段时间了， 建议在动手解决这个issue之前先检查一下是否还存在。 如果你解决了一个你自己提的issue， 在关闭之前需要让其他人知道。 如果你希望这个issue尽快被解决， 请给它打上标签，你可以在label list找到不同的标签。

具体可以参照该链接下已经提交的issue示例

提交PR

• 在 GitHub 或者 Gitee 针对一个issue提出你的解决方案。
• 在议题讨论和设计方案审核达成共识后，fork后完成开发后提交PR
• 贡献者的代码需要至少两个committerLGTM，PR才可以被允许推送，注意贡献者不允许在自己的PR上添加LGTM。
• 在PR被详细评审后，这个PR将会被确定能否被合入。

PRs 警告:

• 应避免任何无关的更改
• 确保您的提交历史记录只有一次，在确定是最终版提交记录后，将以往提交记录合并。
• 始终保持你的分支与主分支一致。
• 对于修复bug的PR，请确保链接上了issue