代码仓库规范
目录
背景
目标
代码仓库规范
仓库创建
权限管理
仓库初始化
.gitignore
README.md
分支管理
Tag管理
代码仓库列表
参考链接
背景
代码仓库不规范往往会带来各种问题,影响代码质量及开发效率,如:
-
项目开发阶段,混乱的分支可能引起多人合作开发过程中的代码冲突
-
项目运维阶段,新功能或bug修复导致线上故障难以回滚
-
项目代码缺乏review,代码质量存在隐患
-
项目组中添加新同学,代码上手开发时间成本较高
针对以上问题,制定代码仓库规范,通过流程化方式降低问题出现的可能性。
目标
除解决背景中提到的问题外,代码仓库规范旨在达成以下目标:
-
业务可持续:避免项目迭代到后期线上、开发等分支错乱,确保系统代码长期可维护,业务变化可追溯
-
知识传承:项目新同学可根据代码重复流程,降低上手成本,促进知识不断积累、传递
-
远程仓库整洁:只提交项目开发/测试/运行相关的文件,IDE配置文件、编译文件等不可上传污染远程仓库
代码仓库规范
仓库创建
项目主R负责申请创建项目代码仓库,代码仓库的创建应遵循以下原则:
-
按照不同的项目创建相应的代码仓库,避免不相关项目的代码放到一个库
-
避免按工程创建代码库,易导致代码仓库过多的问题。合理做法是按业务或按功能将同类工程放入一个代码仓库中
权限管理
合理的权限管理可以避免项目主分支合入未review代码,权限管理应遵循以下原则:
-
项目成员拥有非主分支Write权限,组内非项目成员拥有Read权限
-
项目主R保留主分支Write权限,同时按需为相应同学开放Write权限
-
Leader保留Admin权限
仓库初始化
.gitignore
原则上除了源代码、配置文件、单元测试代码、数据库初始化SQL,其他文件都应该加入到 .gitignore 以避免上传至远程仓库。
通用 .gitignore 文件模板如下,各项目可根据需要补充:
代码块
Plain Text
.idea/
.DS_Store
*.iml
target/
*.log
*.class
.settings/
.project
*.jar
*.war
*.nar
*.ear
*.zip
*.tar.gz
*.rar
README.md
README文件的目的是帮助代码仓库的浏览者快速了解项目相关信息,在README文件中需要包含以下信息:
-
简要说明此代码库解决的问题
-
项目结构简介,以模块粒度说明每个模块的作用、运行环境、线上链接等
-
项目文档外链,如需求文档、设计文档等
-
其他注意事项,如项目特殊依赖等
-
问题及需求反馈
README示例:
分支管理
良好的分支管理可以提高项目主分支代码质量,较为完整的分支示例及对应分支说明如下:
分支名称 | 说明 | 作用 | 注意事项 | 由何分支检出(checkout) | 向何分支合入(merge) | 何时删除 |
---|---|---|---|---|---|---|
master | 主分支/线上分支 | 上线前该分支打Tag | 保留Write权限,由项目主R进行合入 | N/A |
| N/A |
develop | 公共开发分支 | 供feature-*分支检出、合入,作为项目开发过程中的核心分支 | 保留Write权限,项目开发成员不可直接在该分支提交代码,需要以PR方式合入 | master | release-* | N/A |
feautre-* | 个人开发分支/新功能分支 | 项目开发成员各自独立持有使用 | 开发人员间不可混用,避免开发过程中发生冲突 | develop | develop | 完成合入操作后删除 |
release-* | 预上线分支 | feature-*分支汇总至develop分支后进行预上线测试使用 | 除修复测试出的bug外不做其他修改及提交 | develop | master develop | 完成合入操作后删除 |
hotfix-* | 线上bug修复分支 | 临时性紧急修复线上bug |
| master | master develop | 完成合入操作后删除 |
由于组内项目在进行项目拆分后(预计国庆节后开始项目拆分)同一代码仓库只会由2~3人同时维护,采用上述分支模板会降低开发效率且不会取得太高的收益,因此引入分支权限,使用较为简洁的分支进行开发及管理,只保留master、feature-*分支,遵循以下原则:
-
仓库必须有一个主分支(master),主分支只有部分同学有Write权限
-
上线作业/工程必须采用主分支上的代码
-
开发新功能(feature)、修复bug、测试,统一使用feature-*分支(简洁分支管理不存在develop分支,feature-*分支从master分支检出)
-
feature-*分支向主分支合入需要以PR形式进行,并配合Code review,完成后由具有Write权限的同学合并至主分支
-
定期删除已合并至主分支的feature-*分支,避免仓库分支过多难以管理
Tag管理
Tag可以理解成不可更新的特殊分支,也可以理解为某次commit指定的易于理解的别名,方便项目发布过程中的版本管理及线上问题回滚。Tag管理遵循以下原则:
-
Tag需要在上线前创建,上线所用的Tag需要在主分支上创建
-
项目上线需要以Tag为基准(例外:离线托管平台上的Spark等作业需要指定分支发布),保证线上发布版本能够找到对应Tag
-
Tag一般不做删除
Tag示例:
参考链接