git使用规范
Git规范（公司使用gitlab）
版本规范
前端项目使用语义化版本进行发布:
版本格式：主版本号.次版本号.修订号，版本号递增规则如下：
- 主版本号：当你做了不兼容的 API 修改，
- 次版本号：当你做了向下兼容的功能性新增，
- 修订号：当你做了向下兼容的问题修正。
先行版本号及版本编译元数据可以加到“主版本号.次版本号.修订号”的后面，作为延伸。
分支模型
master分支
master分支表示一个稳定的发布版本.
- 场景: 前端应用会跟随工作版本迭代, 在dev分支测试稳定后, 会合并到master分支, 并使用tag标记应用版本和对应的工作版本
- tag规范:
v{version}@{SSA_version}, 例如 v0.1.0@SSA_1.1 - 权限: 由项目负责人进行审核合并, 普通开发者应当没有权限
dev分支
开发者主要工作的分支, 最新的特性或bug修复都会提交到这个分支. 开发者如果在该分支进行了提交，在push到远程之前应该先pull一下， 并尽量使用rebase模式，保证分支的简洁
- 命名规范: dev
- tag规范: 在dev分支中也可能会经历发布过程（发布到测试环境）, 例如bug修复版本. 这里同样使用tag来标记这些发布. 例如v0.1.1
- 提交规范：如果是在开发分支上进行开发，在推送到远程之前，应该使用
git rebase形式更新本地分支。
feature分支
涉及多人协作或者大功能的开发, 应该从dev分支checkout出独立的feature分支, 避免干扰dev分支
-
场景:
- 涉及多人协作: 团队多个成员在同一个项目下负责开发不同的功能, 这时候每个成员在自己的feature分支独立开发
- 大功能开发: 大功能开发跨越周期比较长, 需要多次迭代才会稳定. 这时候应该在独立的分支上开发. 方便跟踪历史记录, 也免于干扰dev分支的迭代和发布
-
命名规范
- feature-name: name是功能名称
- feature-SSA_version: 这也是团队常见的模式, 当无法使用一个功能名称来描述时, 可以使用SSA版本号作为’功能’
-
合并时机
- 当feature分支迭代稳定, 并通过测试后, 合并到dev分支. 合并到dev后, feature分支的生命周期就结束了(应当删除掉). 后续bug修复和功能优化直接在dev开发
- 当多个feature分支需要合并对外发布临时版本时. 合并到preview分支 . ⚠️这种情况不应该合并到dev分支, 因为feature分支可能还不稳定或未完成. 比如为了联调某些功能.
-
合并方式
- 不要使用fast-forward. 这样可以在分支图上查看到分支历史
preview分支
临时的预览分支, preview分支用于临时合并feature分支, 这其中可能会修复某些bug或者冲突. 可以选择性地将这些提交cherrypick回feature分支. 当预览结束后就可以销毁preview分支
release分支
release分支主要是临时创建修改某个发布版本的bug修复分支
- 命名规范
release-{SSA_version}外部人员只会关注SSA版本
- 如何修复
- 如果对应bug可以在dev分支直接被修复, 可以先提交到dev分支(或者已经修复了), 然后再cherrypick到release分支
- 如果bug在新版本无法复现. 比如新版本升级了依赖. 那么在release分支直接修复即可
- 发布
- bug修复测试通过后，可以直接发布到生产环境，并且重新打包一个tag标记
提交信息规范
一个好的提交信息, 会帮助你提高项目的整体质量.
- why
- 格式统一的提交信息可以帮助自动化生成changelog
- 版本库不只是存放代码的仓库, 也记录项目的开发记录. 这些记录应该可以帮助后来者快速地学习和回顾代码. 也应该方便其他协作者review你的代码
- 原则: 半年后, 你能看懂你的commit做了什么东西
- 方式: 使用git commit(打开编辑器)而不是git commit -m
- 必要信息
- 为什么进行这次提交?
- 提交改变了什么, 让其他reviewer更容易审核代码和忽略无关的改变
- 如何解决的问题?
- 问题是什么导致的？
- 简短说明使用什么方式, 策略, 修复了问题.
- 变化可能影响哪些地方
- 说明变动功能的细节。 一个提交不应该做超过2个功能的变动
- 为什么进行这次提交?
提交格式
我们采用基于angular的提交规范, 简化和扩展了不同点。
<type>(<scope>): <subject>
<body>
<footer>
header
如果提交时feature或者fix(已发布的版本), 这些提交信息应该出现在CHANGELOG
- type: 说明commit的类别. 可以配合emoji使用, 让阅读者更快地区分提交的类型,允许以下类型:
- Feat: 新功能/新特性
- Fix: 修复了bug，贴上issues或禅道bug号
- Docs: 文档
- Style: 优化项目结构或者代码格式
- Test: 增加测试
- Chore: 构建过程, 辅助工具升级. 如升级依赖, 升级构建工具
- Perf: 性能优化
- Revert: revert之前的commit
- git revert 命令用于撤销之前的一个提交, 并在为这个撤销操作生成一个提交
- Refactor: 代码重构
- Build或Release: 构建或发布版本
- CI: 持续集成
- Safe: 修复安全问题
- scope: 可选. 说明提交影响的范围. 例如样式, 后端接口, 逻辑层等等
- subject: 提交目的的简短描述, 动词开头, 不超过80个字符. 不要为了提交而提交
body
可选. 对本次提交的详细描述. 如果变动很简单, 可以省略
footer
可选. 只用于说明不兼容变动(break change)和关闭 Issue(如果使用gitlab上的Issuse，#1542)或禅道BUG号(#zentao203)
模板和示例
# 50-character subject line
#
# 100-character wrapped longer description. This should answer:
#
# * Why was this change necessary?
# * How does it address the problem?
# * Are there any side effects?
#
# Include a link to the ticket, if any.
参考vue, angular等开源库项目的提交
跳过CI
如果项目上配有gitlab-ci，可以在标题header上添加 [ci skip] 即可跳过本次提交CI.
Commitlint 提交验证
git commit提交信息的验证，依赖于@commitlint/cli, husky
注：如果使得 vue-cli 3 创建的项目，默认已经有yorkie，不再需要安装 husky
配置 commitlint.config.js
推荐使用：
@smart/commitlint-config
module.exports = {
extends: ['@smart/commitlint-config']
}
或者使用依赖@commitlint/config-conventional, 并配置扩展下面：
module.exports = {
extends: ['@commitlint/config-conventional'],
rules: {
'type-enum': [2, 'always', [
'Feat', 'New', 'Fix', 'Docs', 'Style',
'Test', 'Chore', 'Revert', 'Perf',
'Build', 'Release', 'Safe'
]],
'type-case': [2, 'always', 'start-case'],
'subject-full-stop': [0, 'never'],
'subject-case': [0, 'never'],
'header-max-length': [2, 'always', 80]
}
}
package.json 添加上
"husky": {
"hooks": {
"commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
}
}
// 或者
"gitHooks": {
"pre-commit": "vue-cli-service lint --no-fix",
"commit-msg": "commitlint -E GIT_PARAMS"
},
还可以添加其他钩子，比如："pre-commit": "npm run lintNofix"
配置好后就可以在git commit时验证通过后，才能提交！
生成更新日志
安装conventional-changelog-cli 和 @smart/conventional-changelog-smart
使用命令，即可方便生成出CHANGLOG.md更新日志文件
conventional-changelog -n ./node_modules/@smart/conventional-changelog-smart/index.js -i CHANGELOG.md -s -r 0
BUG 处理规则
公司使用禅道管理bug，而非gitlab上的Issues
对于测试，目前会经历两个阶段
- 冒烟测试：在对测试正式发版之前会要求对代码进行自测，及冒烟测试。
- 正式测试阶段：正式测试阶段测试人员会在禅道进行bug提交和管理，对BUG的处理规则如下：
- [确认]: 已大致定位原因, 需要较多时间处理的BUG, 可置为"确认"
- [提需求]: 无规律或只出现一次的BUG, 研发没找到原因, 加上必要排查日志后, 可提需求给测试; 复现后重新打开
- [不予解决]: 没有修改程序代码, 是由于其他原因(需求变更等)而解决的问题;
- [解决]：修复bug并提交到git dev分支下后，修改禅道上的bug状态，并且填写解决方案。
BUG的数量可能会和个人的KPI挂钩。所以要谨慎自测
发布工作流
- 流程
- 进行代码变更
- 提交这些变更, 进行CI让这些变更通过测试
- 如果没通过就打tag, 一旦出现测试失败, tag就得重新打
- 使用
npm version命令提升package.json的版本号, 更新CHANGELOG.md - 打上tag, 提交
- 可选. 合并到release分支
-
工具
持续集成
前端项目基于公司内部部署的gitlab-ci来进行持续部署。包含以下阶段(stage):
持续集成阶段
- 检查：包括单元测试和代码lint。
- 所有push到版本库的代码都会跑这个阶段. 可以在提交title中包含
[ci skip]来跳过这个阶段
- 所有push到版本库的代码都会跑这个阶段. 可以在提交title中包含
- 构建: 对前端项目进行构建.
- 只有打上版本tag的提交或release分支会跑构建任务
交付
目前前端资源是跟随后端Jar/War包一起部署的，通过将构建结果推送到一个’git发布版本库’的形式实现.
扩展
- 如何写好 Git commit log?
- 提交信息emoji规范
- Commit message 和 Change log 编写指南
- Git远程操作详解
- git钩子定制团队代码提交流程规范