MindSpore作为深度学习的开源框架，要靠广大开发者的共同参与才能蓬勃发展。想必华为昇腾团队的领导和运营也深知这一点，所以就跟华为云层出不穷的培训、直播、实验、跟帖等活动有丰富的礼物那样，MindSpore也常常开展各项活动。这点，作为开发者，张小白们一定是喜闻乐见的。

这不，张小白童鞋就发现了一个有奖品的活动 https://bbs.huaweicloud.cn/forum/thread-111428-1-1.html   ，并且在参加这个活动的过程中，学会了如何向开源框架MindSpore的Python API文档提issue和PR。

先科普一下：

issue，简单的说，就是给一个仓库提问题。当我们发现了仓库中代码的一个bug，我们会提一个issue暴露出问题。如果仓库的负责人看到了，解决了这个问题，则会close这个issue。

而PR呢？是Pull Request的缩写。提了issue之后，如何解决这个issue呢？一般情况下，我们会先把这个仓库fork到自己的仓库，然后在自己的仓库做更新和修改（commit），自己测试通过后，再将改好的内容提交到仓库——这一步就是Pull Request。仓库负责人看到PR后，也会进行一番审查和测试，发现没问题后，就会把我们提交的内容合并(Merge)到仓库中去。

就拿张小白刚提交的issue和PR为例吧。

（一）发现问题，提交issue

打开 https://www.mindspore.cn/doc/api_python/zh-CN/master/mindspore/mindspore.train.html    链接：

会发现 class mindspore.train.callback.LearningRateScheduler(learning_rate_function) 这个类的Note中，"This class are not supported on CPU." 存在一个语法错误，我们知道class作为类的名词，是单数。

那么正确的说法应该是："This class is not supported on CPU."，中文含义应该是：这个类不支持CPU（环境）。

那么发现了这个问题，我们就该提issue了。

我们去mindspore在gitee的主仓。 https://gitee.com/mindspore/mindspore 

点击 代码右边的 Issues（如箭头所示），再点击右边的 “+新建 Issue”按钮。系统会弹出以下界面：

这里有一个提bug的模板，你可以用，也可以不用。

我们填入标题：Problems with the Python API mindspore.train

在输入标题之后，gitee会在下面友善的提示这个issue是不是已经有了答案。我们可以关注或者不关注这些内容。

我们将正文清空，填入以下内容

I found some problems in Python API documents:
URL: https://www.mindspore.cn/doc/api_python/zh-CN/master/mindspore/mindspore.train.html
API name: mindspore.train

classmindspore.train.callback.LearningRateScheduler(learning_rate_function)

This class are not supported on CPU。

The correct usage is " This class is not supported on CPU ".

请注意，这里gitee是支持贴图的。张小白常常使用微信PC端的工具进行截图，简单又方便。

输入后的效果如下：

输入完毕后，点击“创建”。issue就会显示在Issues列表中，并且给你生成一串号，这个就是issue编号，后面提PR的时候会用到。

我们这次提交的issue编号为 #13BVAQ。（图中的issue状态为DONE其实是已经解决了，因为张小白截图迟了，正常刚提交时，这个状态 应该是橙色的“TODO”）

（拿个别的issue的例子示范一下）

（二）fork到个人仓库，下载个人仓库代码

下面我们开始PR前的一些准备工作。前面讲解PR概念的时候提到了，我们先要把MindSpore的仓库fork到自己的仓库：

在 https://gitee.com/mindspore/mindspore/ 主仓地址点击 右边的fork按钮（图中因张小白已经fork过了，所以显示的是forked，否则应该是fork）

点击后，系统会弹出这个菜单：

点击大大的“张”（这取决于你注册在gitee的名字），然后点击确认后，系统会将MindSpore的官方仓库复制到用户自己gitee的仓库下，并自动跳转到自己的gitee仓库页面：

等待页面刷新后，系统会显示以下内容：

那我们接着将自己在gitee的个人仓库的内容下载到本地：

mkdir mypr

cd mypr

git init

git remote add origin https://gitee.com/zhanghui_china/mindspore.git

上面这个链接可以通过点击个人仓库的“克隆/下载”按钮，再选择HTTPS，然后点击“复制”，将仓库的URL复制下来。

git pull origin master

（这里是pull master版本，如果需要pull其他版本可以将master改为对应的版本名称）

（三）本地修改问题代码

然后我们回头看我们发现问题的那个页面：

https://www.mindspore.cn/doc/api_python/zh-CN/master/mindspore/mindspore.train.html  ，函数右边有个“source”,标明了文档对应代码的位置，点击这个"source"

会弹出这个页面，告诉你该文档对应的源代码注释的位置：

mindspore.train.callback._lr_scheduler_callback

我们用Windows资源管理器，去刚才下载的仓库目录找到这个python代码：_lr_scheduler_callback.py

再用VSCode编辑这个文件：

将are改为is，然后保存。

（四）本地验证修改结果

怎么检验自己修改的内容对不对呢？

MindSpore的API文档都是用MindSpore Docs仓库的Sphinx工具生成。同样的，我们去MindSpore仓库找到docs仓库的位置：

点击MindSpore的“仓库” https://gitee.com/organizations/mindspore/projects 

显示出12个仓库，找到docs点进去：

点击“克隆/下载””，找到docs仓库的下载地址（HTTPS）: https://gitee.com/mindspore/docs.git 

本地创建一个mindspore-doc目录

git clone https://gitee.com/mindspore/docs.git

将代码仓下载下来

进入api_python目录

cd docs/api_python

根据requirements.txt的内容安装一些依赖包：

pip install -r requirements.txt

此时，本地需要安装gcc（gcc里面自带了make）

（可以参照张小白的博客： https://bbs.huaweicloud.cn/blogs/239829 完成Windows上gcc的安装）

并将原来MinGW上的 mingw32-make.exe复制一份叫做make.exe

执行make html试图生成本地文档：

注释掉仓库下docs\api_python\source_en\conf.py和docs\api_python\source_zh_cn\conf.py代码中的几个import，以便让编译通过（当然此时仅仅能生成mindspore的Python API文档，应该生成不了mindarmour，mindspore_hub或者mindspore_serving的API文档了。）

再重新make html

。。。

会报很多错，（红色部分），但是能走完。。

而且会告诉你， HTML文件生成了，在 build_zh_cn\html目录下。

打开这个目录下的index.html文件：

如果打开mindarmour，mindspore_hub，mindspore_serving，会发现右边都是空的：

说明前面说的是对的。

点击我们找到的issue对应的API mindspore.train

当然，目前生成的还是错的。为啥呢？

mindspore本地Python API文档的生成依赖于我们已经安装的mindspore的版本。正常的调试流程，应该是“编译mindspore源码，安装mindspore，然后生成api文档。”。但是一个比较快速的流程是：直接把自己改动后的python文件覆盖本地已经安装好的mindspore库。

张小白已经安装好的mindspore在  C:\Users\zhang\miniconda3\Lib\site-packages\mindspore\ 目录下。（可以通过搜索找 _lr_scheduler_callback.py 文件）

那将刚才改过的  _lr_scheduler_callback.py覆盖掉这个文件 

重新回到 mindspore-doc目录的相关目录 make html

...

再重新打开生成的文档：

可见修改确实生效了。

（五）提交本地修改代码到个人仓库

在本地测试通过之后，我们就可以将代码的变更提交个人仓库了。

git branch mypr

git checkout mypr

git branch

git add .

git commit -m "Fix Issue #I3BVAQ"

（上图仅用其他的issue示意）

git push --set-upstream origin mypr

去看看 远程仓库也可以看到这个变化。

（六）新建PR

到自己仓库，提PR。点击自己仓库的 “+Pull Request”按钮

会自动弹出以下页面：

好像就需要填这三个地方：标题，对应issue和标签（Mindspore的Python API文档修改可以增加 mindspore-contrib标签）

点击“创建”

（上图以别的PR为例）

PR好像就生成了。

（七）签署CLA

第一次在Mindspore仓库提交PR，i-robot会告诉你需要签署CLA。

点击 Please access here的here的链接，可以进入签署CLA的页面：

此时，需注意：在前面提交代码仓库的时候，会让你输入邮箱：

而你要确保这个邮箱跟  C:\Users\zhang\.gitconfig 的邮箱要保持一致。

张小白就因为这两个邮箱不一致，导致i-robot认为提交的我不是我。又需要重签cla。

具体签署的过程也很简单：

点击后，弹出以下窗口：

选择 sign individual CLA

输入gitee-id，邮箱，名字，然后提交即可.

正常应该是显示签署成功，上图只是张小白签过了，再签一次自然报已经签过。

签署完毕后，我们在PR的评论栏输入 /check_cla，得到肯定的答复，就说明签署成功。

（八）提交测试

在提交给审查人员之前，我们应该负责任地先把自己的代码在服务器上测试一遍。

尽管本次改动只有一个单词。但是测试还是不能少的。

我们在PR的评论区输入 /retest

mindspore-ci-bot这个小机器人会做jenkins测试环境的自动部署，并进行代码的测试，点击Link可以看到测试的过程：

从上面的过程可以看出，云端的测试包含 代码下载download-code，代码检查code-check，代码编译compile，ut-test，冒烟测试smoke-test等过程。虽然仅有一行代码的改动，但是mindspore-ci-bot 还是把各种环境都编译测试了一遍。所以这段测试时间历时也会比较长，一般在一小时左右。

测试完毕后，会在PR的评论区告诉你Build Result是SUCCESS还是FAIL。

一般情况下，如果SUCCESS，就可以做后续操作，否则，应该检查是什么问题，重新在本地修改代码，重新在本地测试完毕后，再重新提交PR的retest。

（九）等待审核

一般情况下，我们应该在此时，耐心等待MindSpore审核团队进行PR的审核就行了。

但是，我们也可以通过指定PR审核人的方式，迅速让审核团队进行操作。

MindSpore官方可能会在近期整理出模块对应的PR审核人的列表。这样方便开发者提交PR时，选择合适的审查人员。

比如可以在PR的编辑页面指定审查人员：

审核人员会进行 /lgtm。从本次实践的例子来看，有3个人参加了审核。

审核完之后，这个PR就会多了4个标签：approved和 3个lgtm-人名 

而且 bot机器人也会完成PR的合并。

而对应的issue，也会从TODO状态改为DONE状态。

再去看mindspore主仓的代码：

很高兴看到了自己的PR提交生效了。

至此，就完成了PR的全过程。

我们再去打开一下原来有bug的那个网页：https://www.mindspore.cn/doc/api_python/zh-CN/master/mindspore/mindspore.train.html 

可以看到，最终的API文档页面也得到了修正。（但是这个不是合并后马上生效，需耐心等待官方合并发布。）

有心人还可以看一下 r1.1版本的页面： https://www.mindspore.cn/doc/api_python/zh-CN/r1.1/mindspore/mindspore.train.html 

这个还是错误的。

当然，这里需要补充一句，如果我们发现了1.1分支的bug，那么就应该拉回1.1分支的代码进行修改；如果发现了master分支的bug，就应该拉回master分支的代码进行修改。我在论坛中看到有些童鞋发现了1.1分支的代码，但是又是从master拉回的分支进行了代码的修改，这样子操作还是有点危险的。因为有可能这个分支的bug已经被修复了。我们也可以在提交PR的时候注意一下：

比如这个是用自己个人仓库mypr的版本，往官方仓库mindspore/mindspore的master分支提交版本。

个人觉得以前的版本有bug，我们下最新的版本就行了。当然，也不反对有人就是喜欢给老版本提bug，但是记得一定要做到把PR提交到老版本才对。以免给其他开发人员造成困扰。。

好了，大家可以看到，尽管张小白只是改了一个单词，但是以上的操作应该都是不必可少的。希望大家能够通过本文了解具体的提issue和提PR的整个过程，也希望大家多为MindSpore社区做出贡献。

MindSpore BBS论坛的地址为：https://bbs.huaweicloud.cn/forum/forum-1076-1.html    

欢迎大家到论坛找张小白，或者找MindSpore团队的专家咨询。

。。

。。

。。

别急，还有彩蛋：

大家有没有发现，MindSpore.cn网站生成的内容跟使用make html 生成的内容，在文档风格上并不一样。

比如对于同一块区域：

而make html生成的如下：

MindSpore.cn显示的如下：

如果想将本地渲染成跟官网mindspore.cn一样的效果，需要将 https://www.mindspore.cn/doc/api_python/zh-CN/master/_static/css/theme.css 这个样式文件下载到本地。覆盖掉make html已经生成的 docs\api_python\build_zh_cn\html\_static\css下的同名文件。

你会发现，居然出现了官方显示的效果了：

这里多谢 论坛中 @longvoyage 大大的指点。

在写本文的过程中，张小白发了多个问题贴，试验了多种方式，并在群里骚扰了多个MindSpore团队的专家（如 @琦玉、@TingWang等等），才形成此文，为此向几位表示衷心的感谢。

（全文完，谢谢阅读）