• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# MindSpore贡献指南
2
3[View English](./CONTRIBUTING.md)
4
5<!-- TOC -->
6
7- [MindSpore贡献指南](#mindspore贡献指南)
8    - [贡献者许可协议](#贡献者许可协议)
9    - [快速入门](#快速入门)
10    - [贡献流程](#贡献流程)
11        - [代码风格](#代码风格)
12        - [Fork-Pull开发模型](#fork-pull开发模型)
13        - [报告Issue](#报告issue)
14        - [提交PR](#提交pr)
15        - [本地代码自检](#本地代码自检)
16
17<!-- /TOC -->
18
19## 贡献者许可协议
20
21向MindSpore社区提交代码之前，您需要签署《贡献者许可协议（CLA）》。
22
23个人贡献者请参见[ICLA在线文件](https://www.mindspore.cn/icla)。
24
25## 快速入门
26
27- 在[Github](https://github.com/mindspore-ai/mindspore)或[Gitee](https://gitee.com/mindspore/mindspore)上fork代码仓。
28- 参见[README_CN.md](README_CN.md)和[安装页面](https://www.mindspore.cn/install)了解项目信息和构建说明。
29
30## 贡献流程
31
32### 代码风格
33
34请遵循此风格，以便MindSpore审查、维护和开发。
35
36- 编码指南
37
38    MindSpore社区使用[Python PEP 8 编码风格](https://pep8.org/)和[谷歌C++编码风格](http://google.github.io/styleguide/cppguide.html)。建议在IDE中安装以下插件，用于检查代码格式：[CppLint](https://github.com/cpplint/cpplint)、[CppCheck](http://cppcheck.sourceforge.net)、[CMakeLint](https://github.com/cmake-lint/cmake-lint)、[CodeSpell](https://github.com/codespell-project/codespell)、[Lizard](http://www.lizard.ws)、[ShellCheck](https://github.com/koalaman/shellcheck)和[PyLint](https://pylint.org)。
39
40- 单元测试指南
41
42    MindSpore社区使用Python单元测试框架[pytest](http://www.pytest.org/en/latest/)和C++单元测试框架[Google Test Primer](https://github.com/google/googletest/blob/master/docs/primer.md)。注释名称需反映测试用例的设计意图。
43
44- 重构指南
45
46    我们鼓励开发人员重构我们的代码，以消除[代码坏味道](https://zh.wikipedia.org/wiki/%E4%BB%A3%E7%A0%81%E5%BC%82%E5%91%B3)。所有代码都要符合编码风格和测试风格，重构代码也不例外。无注释的代码行（nloc）的[Lizard](http://www.lizard.ws)阈值为100，圈复杂度（cnc）的阈值为20。当收到Lizard警告时，必须重构要合并的代码。
47
48- 文档指南
49
50    我们使用MarkdownLint来检查Markdown文档格式。MindSpore CI基于默认配置修改了以下规则。
51    - MD007（无序列表缩进）：参数**indent**设置为**4**，表示无序列表中的所有内容都需要缩进4个空格。
52    - MD009（行尾空格）：参数**br_spaces**设置为**2**，表示行尾可以有0或2个空格。
53    - MD029（有序列表的序列号）：参数**style**设置为**ordered**，表示升序。
54
55    有关详细信息，请参见[规则](https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md)。
56
57### Fork-Pull开发模型
58
59- Fork MindSpore代码仓
60
61    在提交代码至MindSpore项目之前，请确保已fork此项目到您自己的代码仓。MindSpore代码仓和您自己的代码仓之间可能会并行开发，请注意它们之间的一致性。
62
63- 克隆远程代码仓
64
65    如果您想将代码下载到本地计算机，最好使用git方法：
66
67    ```shell
68    # 在GitHub上：
69    git clone https://github.com/{insert_your_forked_repo}/mindspore.git
70    git remote add upstream https://github.com/mindspore-ai/mindspore.git
71    # 在Gitee上：
72    git clone https://gitee.com/{insert_your_forked_repo}/mindspore.git
73    git remote add upstream https://gitee.com/mindspore/mindspore.git
74    ```
75
76- 本地开发代码。
77
78    为避免分支不一致，建议切换到新分支：
79
80    ```shell
81    git checkout -b {新分支名称} origin/master
82    ```
83
84    以master分支为例，如果MindSpore需要创建版本分支和下游开发分支，请先修复上游的bug，
85    再更改代码。
86
87- 将代码推送到远程代码仓。
88
89    更新代码后，以正式的方式推送更新：
90
91    ```shell
92    git add .
93    git status # 查看更新状态。
94    git commit -m "你的commit标题"
95    git commit -s --amend # 添加commit的具体描述。
96    git push origin {新分支名称}
97    ```
98
99- 将请求拉取到MindSpore代码仓。
100
101    在最后一步中，您需要在新分支和MindSpore主分支之间拉取比较请求。完成拉取请求后，Jenkins CI将自动设置，进行构建测试。拉取请求应该尽快合并到上游master分支中，以降低合并的风险。
102
103### 报告Issue
104
105发现问题后，建议以报告issue的方式为项目作出贡献。错误报告应尽量书写规范，内容详尽，感谢您对项目作出的贡献。
106
107报告issue时，请参考以下格式：
108
109- 说明您使用的环境版本（MindSpore、OS、Python等）。
110- 说明是错误报告还是功能需求。
111- 说明issue类型，添加标签可以在issue板上突出显示该issue。
112- 问题是什么？
113- 期望如何处理？
114- 如何复现？（尽可能精确具体地描述）
115- 给审核员的特别说明。
116
117**Issue咨询：**
118
119- **解决issue时，请先评论**，告知他人由您来负责解决该issue。
120- **对于长时间未关闭的issue**，建议贡献者在解决该issue之前进行预先检查。
121- **如您自行解决了自己报告的issue**，仍需在关闭该issue之前告知他人。
122- **如需issue快速响应**，可为issue添加标签。标签详情，参见[标签列表](https://gitee.com/mindspore/community/blob/master/sigs/dx/docs/labels.md)。
123
124### 提交PR
125
126- 在[GitHub](https://github.com/mindspore-ai/mindspore/issues)或[Gitee](https://gitee.com/mindspore/mindspore/issues)上通过issue提出您的想法。
127- 如果是需要大量设计细节的新功能，还应提交设计方案。
128- 经issue讨论和设计方案评审达成共识后，在已fork的代码仓开发，并提交PR。
129- 任何PR至少需要位2位审批人的LGTM标签。请注意，审批人不允许在自己的PR上添加LGTM标签。
130- 经充分讨论后，根据讨论的结果合并、放弃或拒绝PR。
131
132**PR咨询：**
133
134- 避免不相关的更改。
135- 确保您的commit历史记录有序。
136- 确保您的分支与主分支始终一致。
137- 用于修复错误的PR中，确保已关联所有相关问题。
138
139### 本地代码自检
140
141在开发过程中，建议使用pre-push功能进行本地代码自检，可以在本地进行类似CI门禁上Code Check阶段的代码扫描，提高上库时跑门禁的成功率。使用方法请参见[pre-push快速指引](scripts/pre_commit/README_CN.md)。
142