Git简明协作规范
1.分支约定
1.1.主分支 main
主分支为永久唯一分支，设置为保护分支，状态为只读不可推送，为上线稳定分支，需要从该分支按阶段创建tag，该分支只能由develop和hotfix分支合并而来，除了bug修复外通常该分支表示较大批次的改动。
1.2.开发分支 develop
开发分支可以为永久分支，也可以为阶段性分支，总体存在周期较长，是某一个开发阶段合并的目标分支，项目初始开发可以基于此分支直接开发，一旦上线后将不可以在此分支上直接开发，需要专门的分支，该分支每次为小批量推送，例如完成1个功能或者修复1个问题后进行合并，更新后即可进行测试环境测试，测试通过后合并至main分支。
1.3.功能开发分支feature-*
这类分支属于临时分支，主仓库一般不出现，每个人的子仓库中可以存在，这些分支由develop创建而来，开发中可以及时提交，最后发起合并至develop分支。
命名示例：feature-branch-1
1.4.测试修复分支fix-*
这类分支同样属于临时迭代分支，主仓库不出现，每个人的子仓库中可以存在，当feature-*合并至develop分支之后，经过测试发现bug，则可以临时创建fix分支，快速修复后合并至develop分支进行下一轮测试。
命名示例：fix-branch-1
1.5.稳定修复分支hotfix-*
该分支属于临时分支，从main分支创建而来，当上线版本发现bug时，在此分支上进行修复，修复成功确保不会引入新问题的情况下，可以直接合并至main分支及develop分支，否则如果开发内容较多，需要先合并至develop分支进行测试，测试无误再合并至main分支并且打tag。
命名示例：hotfix-branch-dbquery-2
2.tag约定
每次合并至 main 分支后都要打 tag 并发布版本，tag 命名规范为：vx.y.z[-(alpha|beta|rc).n]，其中加黑部分x为主版本号、y为次版本号、z为修订号，n为对应类型发布包的序号，正式版本将不再包含中括号部分的内容。
版本命名规范参考：语义化版本 2.0.0
3.Git协作流程
3.1.初始创建仓库
需要项目研发经理或技术经理在组织下为团队创建仓库，注意仓库要按照开发的模块进行拆分，为了方便维护和版本发布，两个独立的程序仓库必须分开，如果团队共用一套文档也需要创建单独的文档仓库。
首先在组织下点击创建仓库按钮，输入仓库名称和简介同时根据需要填写其他相关信息，最后创建。
注意：仓库名称按照小写字母命名，采用中划线"-“进行分割，如tutorial-example；默认分支名称一定为main
创建后可以clone仓库到本地或者为已有的仓库添加远程：
# 这里URL仅为示例
git clone git@192.168.8.8:bigdata/tutorial-example.git
cd tutorial-example
echo "# 练习项目" > README.md
# 或者为已有项目添加远程
git init
git remote add origin git@192.168.8.8:bigdata/tutorial-example.git
然后初始化推送：
git add .
git commit -m "first commit"
git push -u origin main
# 创建开发分支
git checkout -b develop
git push origin develop
推送后刷新仓库可以看到初始的内容，然后进行仓库设置，设置合适的协作者，通常为项目核心成员添加管理员权限，负责代码review及合并，其他研发成员设置为可写权限，其他项目组成员设置为可读权限。
然后进行分支保护设置：在分支保护部分，要对main分支和develop分支，设置为禁止推送并确认生效。
这样仓库即可初始化完毕，每个仓库只初始化一次。
3.2.项目成员拉取仓库到本地
在3.1步骤完成后，项目组研发成员即可初始化仓库进入开发状态，成员应该首先fork当前项目到个人仓库下，然后再拉取自己的仓库到本地：
# 按照个人仓库的URL克隆
git clone http://192.168.8.8:3000/zengzy/tutorial-example.git
cd tutorial-example
# 添加上游分支 用于拉取最新修改
git remote add upstream http://192.168.8.8:3000/bigdata/tutorial-example.git
然后拉取develop分支：
# 拉取develop分支
git checkout -b develop origin/develop
git pull upstream develop
git pull upstream main
然后即可在develop分支下进行研发。
3.3.功能开发
确保当前在develop分支下，然后开始进行新功能的研发：
# 拉取upstream的更新
git pull upstream develop
# 创建特性分支
git checkout -b feature-branch-1
然后即可开始进行功能开发和自测，完成后推送：
git add .
git commit -m "feature: 添加新的功能xxx"
git push origin feature-branch-1
推送后回到上游仓库页面，发起pull request请求，将fork仓库的feature-branch-1合并至上游仓库的develop分支，也就是说合并目标选择主仓库的develop分支，拉取分支选择个人仓库中刚推送的feature分支，最后创建合并请求（pull request）。
合并请求创建后，项目中核心研发会看到请求通知，并审查详细的改动，如果没问题会将PR进行合并，合并后管理员可以选择删除原分支，也可以不删除。
当管理员合并代码后即可对develop分支内容进行功能提测，同时研发人员也要拉取内容到本地并推送到自己的仓库：
git checkout develop
git pull upstream develop
git push -u origin develop
特性分支可以删除掉：
git branch -d feature-branch-1
git push origin :feature-branch-1
3.4.测试功能修复
如果在对develop分支测试时出现错误，则需要进行测试功能修复，对应的研发人员切换至develop分支操作如下：
# 拉取当前最新内容
git pull upstream develop
# 创建测试功能修复分支
git checkout -b fix-branch-device-query-01
然后研发人员即可在当前分支下进行bug的修补，修复完成后提交代码：
git add .
git commit -m "fix: 修复测试bug xxx."
git push -u origin fix-branch-device-query-01
然后同样按照上面的流程向主仓库发起合并请求（pull request）。
发起合并请求后，等待项目组管理员进行代码合并，合并完成继续进行测试，测试通过后和上面一样拉取最新代码到个人仓库即可：
git checkout develop
git pull upstream develop
git push -u origin develop
# 可以删除fix分支
git branch -d fix-branch-device-query-01
git push origin :fix-branch-device-query-01
3.5.稳定版本发布
当develop分支完全通过测试后，项目组核心研发成员就可以发布稳定版本了，如果是内部测试可以发布beta版，如果通过实验局测试可以发布预览版，如果后续验证稳定则可以发布stable版，正常发版操作如下：
1.项目组管理员进入主仓库，发起合并请求–创建合并请求，将develop分支合并至main分支。
2.发起合并请求后，如有必要可请项目组其他管理员进行确认，确认无误后执行合并请求将代码合并至main分支。
3.如果main分支部分内容比develop新，则需要将更新部分再PR合并回develop，正常应避免出现这类情况。
4.最后管理员需要在main分支上打tag以及发布版本：
# 有管理员权限的研发进行操作
git checkout main
git pull origin main
# 创建tag
git tag v1.0.0
git push origin v1.0.0
然后即可在仓库看到打好的标签，正常git页面都支持版本发布的操作，需要在打好的tag上发布版本，注意填写好发布版本的内容描述部分，并且上传打包好的二进制发布包，可以是zip/tar.gz等格式，最后完成稳定版本发布即可。
二进制发布包命名规范：<package-name>-<version>-[os]-[cpu-arch].tar.gz 其中 <> 内容是必选的，[] 内容是可选的，version 和发版的版本号命名一致，但是要去掉开头的 v，os 可以是 linux / windows / darwin 等通用操作系统平台，如果我们只支持 Linux 平台并且大家都了解，那么 os 可以不写，另外如果我们只支持特定的发行版，建议还是写一下，例如 el7 / el8 等，最后 cpu-arch 表示 CPU 芯片的架构，目前通常都是 64 位的，例如：amd64 或 aarch64 ，另外对于 Java 或 Python 等跨平台的程序则不需要添加 cpu-arch 。
5.版本发布后，所有研发人员可以拉取最新的稳定版代码到本地：
# 测试分支
git checkout develop
git pull upstream develop
git push -u origin develop
# 主分支
git checkout main
git pull upstream main
git fetch upstream --tags
git push origin --tags
3.6.稳定版本修复
当线上稳定版本出现bug需要修复时，研发人员需要从main分支创建hotfix分支用于bug修复，操作如下：
git checkout main
git pull upstream main
# 创建hotfix分支
git checkout -b hotfix-branch-face-search-2
然后可以进行稳定版本功能修复，修复完成之后推送至远程仓库：
git add .
git commit -m "hotfix: 修复功能xx"
git push origin hotfix-branch-face-search-2
然后向上游仓库发起合并请求，正常应该合并至develop分支，待验证通过后再由管理员合并至main分支并进行发版，如果确定不会引入新的问题情况下也可以直接向main分支发起合并，由管理员进行合并、发版、同步develop分支操作。
操作成功后项目开发者可以从本地同步修改及tag信息，最后可以删除hotfix分支。
FAQ
1.PR冲突解决
为了防止自己在发起PR时，管理员已经合并其他人的PR，导致develop分支超前，如果此时自己的功能已经完成研发需要提交时，那么可以先在本地进行一步合并最后再发起提交，操作示例如下：
# 首先在特性分支上完成commit feature-branch-f1
git add .
git commit -m "feature: 新增功能项xxx"
# 拉取开发分支内容
git checkout develop
git pull upstream develop
# 如果有新的PR则需要本地处理合并 创建临时合并分支
git checkout -b temp-merge
# 合并功能分支
git merge feature-branch-f1
# 合并成功以merge分支替代原有分支
git branch -d feature-branch-f1
git branch -m temp-merge feature-branch-f1
# 推送合并后的分支
git push -u origin feature-branch-f1
然后即可正常向主仓库develop发起合并请求，等待合并。
此规范在标准gitflow基础上进行了精简，抛弃了Release分支，使用起来更加简单明了一些。
Reference:
Gitflow Workflow | Atlassian Git Tutorial
