Deleting the wiki page '代码提交注意指南' cannot be undone. Continue?
0
代码提交注意指南
ZOMI酱 edited this page 2 years ago
代码提交注意指南
1、开发模式与开发流程
1.1 开发流程
对于高校开发团队Owner与学生来说，整体开发流程如下：
-
Fork MindSpore Vision仓代码至Gitee个人仓。
-
团队Owner根据需求分解任务交给团队学生。（即创建任务issues）
-
团队学生Fork MindSpore Vision仓至本地，根据任务新建分支进行开发。
-
团队学生开发完成后push代码至个人Vision仓。
-
团队学生按需创建PR (Pull Request)，申请合入MindSpore主仓master分支。
-
团队Owner对分支代码进行初步审核，团队Owner或高校学生触发CI门禁检查（评论/retest）。
-
华为Committer审核PR。
-
PR自动合入。
本流程为一般开发流程，部分开发前需要进行的操作未包含在内，如注册Gitee账号，配置Git客户端，SSH公钥等，请自行搜索配置
请参考bilibili视频连接：如何给MindSpore贡献代码
视频会手把手带着大家如何贡献代码到gitee、如何fork MindSpore仓，并进行代码提交，解决git中username冲突等的问题。请一定要先观看该视频哦，会给您节省后续很多麻烦！
1.2 开发模式
本次MindSpore Vision套件众智项目开发采用开发模式大致如下：
-
多个团队同时进行协作开发，每个高校开发同学从主仓Master分支Fork代码到个人仓，负责按需通过“Pull Request”提交满足质量要求的代码至Master。
-
高校开发团队Owner提交的PR需要通过CI门禁检查及两名华为Committer的审核。
-
单个PR应仅包含单个算子的代码，禁止多个算子代码合并提交。
-
为了防止共享服务器上git账户配置管理出现问题影响代码提交，不建议在共享服务器上进行开发与代码提交。共享服务器仅用于代码提交前的编译及测试。
2、签署CLA(Contributor License Agreement)
2.1 如何签署？
在首次提交代码至MindSpore社区前，需要签署CLA。
打开链接，选择个人签署：
2.2 为什么要签CLA？
第一次提交完代码后，会在 pulls 页面显示标签 mindspore-cla/no，表示没有签署 CLA，CLA 是参加开源项目的电子证明
为了让参加开源项目的每一个同学都有一个记录，方便后续简历写上参加 XXX 开源项目，我们要求每个同学签署CLA。同时，PR 下面的评论 i-robot 会提醒点击签署 CLA 协议：
2.3 CLA是什么？
CLA 是每个公司或组织自定义的，在细节上可能稍有不同，不过总体都包含以下内容：
-
关于签署该 CLA 的主体和贡献的定义；
-
授予著作权给拥有该软件知识产权的公司或组织；
-
专利许可的授予；
-
签署者保证依法有权授予上述许可；
-
签署者确保所有的贡献内容均为原创作品；
-
签署者为贡献内容支持的免责描述；
-
说明贡献者提交非原创作品应该采用的方式；
-
保证在获悉任何方面不准确的事实或情况之时通知签约方；
-
对于主体在中国的企业，还加入了一些本地化的内容，如 Alibaba Open Source Individual CLA。
因为 CLA 分别为个人级和公司级，所以对于不同名义签署时需要提供不同的信息。签署个人级 CLA 的时候需要提供个人信息（姓名、地址、邮箱、电话等），签署公司级 CLA 还需要提供公司信息（名称、地址、联系电话、邮箱、传真等）
2.4 谁应该签署CLA？
本次项目中，所有代码贡献者(Commit作者)都应该在首次提交PR前签署CLA。
因为代码合入MindSpore主仓前的CLA检查操作，主要是检查本次PR中所有commit信息中的git配置的邮箱是否签署过CLA，所以建议所有代码贡献者注意以下两点：
-
本地git配置的邮箱由开发者本人的信息填写。
-
保持本地git配置的邮箱与gitee网站上的邮箱一致。
2 代码提交格式要求
2.1 代码commit格式
为了增加commit信息的可读性，方便通过commit信息准确的追溯历史及了解commit内容，提高项目整体质量，所以对commit信息进行约束，约束后格式如下：
[Type] [Requirement] XXXXX
其中：
-
Type为commit类型，可选项为：
add：新增模块/模型。
fix：修复BUG。
test：PR提交后对测试用例进行修改。
misc：其他修改注释，代码格式或其他未归类的提交。
-
Requirement为本次需求列表中任务的Requirement ID。如无，则空。
-
XXXXX为commit简短描述，使用第一人称现在时的动词开头，首字母小写，结尾不要标点。
下面几个例子供参考：
[add] [I2U3AE] add new GPU operator Atan
[add] [I39E2B] add new data operator Flickr
[fix] [I33EXA] fix bug in the infer function of the operator Atan
[misc] [I2APAD] modify the description of the operator Atan
2.2 与MindSpore Vision主仓master分支同步
// 添加MindSpore主仓master分支
git remote add upstream https://gitee.com/mindspore/vision.git -t master
// 拉取MindSpore主仓master分支至本地
git fetch upstream
// 切换至master分支
git checkout master
// 本地master分支rebase MindSpore主仓master分支
git rebase upstream/master
// push本地master分支至master远程分支
git push
// 切换至Op1分支
git checkout Op1
// 本地Op1分支rebase本地master分支
git rebase master
// push本地Op1分支至Op1远程分支
git push -f
3、PR相关操作
3.1 PR创建
在Owner个人仓库主页点击“+ Pull Request”进行创建
进入PR创建界面后，根据实际情况填写以下内容：
-
选择需要合入的分支名称。
-
确保可自动合并，否则需要检查代码是否已进行同步，需解决冲突后重试。
-
填写PR标题，简略描述PR内容，可以和commit信息一致。
-
描述具体PR内容，一般包括文件列表，修改信息
-
禁止勾选“合并后关闭提到的任务”选项
提交PR后，需要在PR页面评论"/retest"命令触发CI构建
3.2 CI门禁检查
代码门禁是一项代码质量保障措施，目的是要求开发人员提交的代码必须满足一些要求才能合入代码仓库。目前MindSpore Vision代码合入前需要进行“jenkins”门禁检查，检查不通过，则无法完成PR合入等相关动作。
在PR页面评论 “/retest”命令触发门禁。
CI门禁系统下载测试的代码是个人仓PR分支commit代码与MindSpore主仓库master分支预合并后的代码。
下图为CI门禁检查涉及到的所有项目。只要其中任何一项出现报错，CI构建失败，PR不能合入。具体错误信息可以在下方的shell窗口中查看。
说明：
- 在触发CI门禁之前，请确保个人仓代码的PR分支rebase最新的MindSpore主仓库master分支后再触发门禁。
- 在触发CI门禁之前，请确保代码本地编译成功，编写的测试例可以正确执行通过。尽量避免因本地检查不足导致对公共资源的无效占用。
Delete Page