项目代码、分支及版本管理规范

文档

A 代码提交规范

A.1 工作前确认来源分支

开始代码编写工作前，先确认自己工作的基础分支的来源是否和要求的一致。一般分支要求源于当前项目最新版本；修复特定版本bug的，从该版本开始工作。

A.2 在提交代码前先拉取代码

每次提交代码前，先进行更新，当遇到可能的提交冲突时，和相关人员一起协同解决冲突。

A.3 提交前认真确认内容

提交前认真确认所提交的内容，只提要必要的和需求相符的改动，特别注意不要提交生产配置或密码等敏感信息。

A.4 提交说明要写清楚

提交时要在提交说明中写清楚所作改动的内容。

A.5 保持提交中功能的完整和解耦

原则上，应该再完成某个功能或函数的开发测试后，再提交代码，避免提交功能不完整的代码。对不同的功能的改动最好走单独的工作流程。

A.6 遵循代码体提交和审核流程

新增功能或修复BUG时，原则上需要按以下流程：
从源分支新建一个临时分支--进行修改--完成修改和测试--提交代码--请求向目标分支请求合并--项目负责人review合并请求--通过或打回修改。

B 分支管理规范

B.1 Master分支

代码库有且仅有一个主分支(master分支)。该分支不接受直接提交，只能合并请求。所有提供给用户使用的正式版本，都从该主分支上发布。

B.2 Develop分支

日常开发在另一条开发分支上完成，我们称之为develop分支。如果想正式对外发布，就在Master分支上，对Develop分支进行"合并"（merge），且是非快进式合并:

# 切换到Master分支
git checkout master
# 对Develop分支进行合并
git merge --no-ff develop

B.3 临时性分支

其他分支均为临时性分支，按目的来分有以下几种：

• 功能(feture)分支
• 预发布(release)分支
• 修补bug(fixbug)分支。

这三种分支都属于临时性需要，使用完以后，应该删除，使得代码库的常设分支始终只有Master和Develop。

B.3.1 功能分支

功能分支是为了开发某种特定功能，从Develop分支上面分出来的。开发完成后，要再并入Develop。功能分支的名字，可以采用feature-*的形式命名。
创建一个功能分支：

git checkout -b feature-x develop

开发完成后，将功能分支合并到develop分支：

git checkout develop
git merge --no-ff feature-x

删除feature分支：

git branch -d feature-x

B.3.2 预发布分支

预发布分支是指发布正式版本之前（即合并到Master分支之前），我们可能需要有一个预发布的版本进行测试。
预发布分支是从Develop分支上面分出来的，预发布结束以后，必须合并进Develop和Master分支。它的命名，可以采用release-*的形式。
创建一个预发布分支：

git checkout -b release-1.2 develop

确认没有问题后，合并到master分支：

git checkout master
git merge --no-ff release-1.2

对合并生成的新节点，做一个标签

git tag -a 1.2

再合并到develop分支：

git checkout develop
git merge --no-ff release-1.2

最后，删除预发布分支：

git branch -d release-1.2

B.3.3 修补bug分支

修补bug分支。软件正式发布以后，难免会出现bug。这时就需要创建一个分支，进行bug修补。
修补bug分支是从Master分支上面分出来的。修补结束以后，再合并进Master和Develop分支。它的命名，可以采用fixbug-*的形式。
创建一个修补bug分支：

git checkout -b fixbug-0.1 master

修补结束后，合并到master分支：

git checkout master
git merge --no-ff fixbug-0.1
git tag -a 0.1.1

再合并到develop分支：

git checkout develop
git merge --no-ff fixbug-0.1

最后，删除"修补bug分支"：

git branch -d fixbug-0.1

B.7 分支操作权限

项目管理员有权对develop和master分支进行修改(在develop上提交和合并代码，在master上合并代码)，主程序员有权对develop进行修改，其他人须在临时分支上工作后请求合并代码，其他分支命名需符合规范，管理员有权利和义务对非规范命名及过期的分支定期清理删除，若因此造成了工作代码丢失由开发人员自行承担。

C 版本管理规范

C.1 使用语义化版本号

使用semantic version规划制定版本号。
版本格式：主版本号.次版本号.修订号，版本号递增规则如下：
1.主版本号：当你做了不兼容的 API 修改，
2.次版本号：当你做了向下兼容的功能性新增，
3.修订号：当你做了向下兼容的问题修正。

C.2 发布后固定代码，并向外散布

发布使用git的tag功能，对特定代码打上版本标签，正式发布后，禁止覆盖版本标签(就算有BUG也只能新开小版本修复），同时有必要时需要在github的release中发布更新，或上传pypi。

C.3 提前制定开发计划

每个次版本号以上更新的内容一般需要项目负责人制定好开发计划后再进行开发并记录，同时在新版本正式发布时附带详细说明。

C.4 记录详细的Change Log

每次发布新版本都需要附加上对改动的详细说明，即Change Log。

C.5 生产环境只部署正式发布的版本

只有正式发布过的版本号对应的代码才能部署于生产环境。

参考资料：
[1]http://www.ruanyifeng.com/blog/2012/07/git.html
[2]https://nvie.com/posts/a-successful-git-branching-model

熟悉git使用的教程:
https://learngitbranching.js.org/