代码仓库规范

 代码仓库规范

目录

背景

目标

代码仓库规范

仓库创建

权限管理

仓库初始化

.gitignore

README.md

分支管理

Tag管理

代码仓库列表

参考链接
 

背景

代码仓库不规范往往会带来各种问题，影响代码质量及开发效率，如：

1. 项目开发阶段，混乱的分支可能引起多人合作开发过程中的代码冲突

2. 项目运维阶段，新功能或bug修复导致线上故障难以回滚

3. 项目代码缺乏review，代码质量存在隐患

4. 项目组中添加新同学，代码上手开发时间成本较高

针对以上问题，制定代码仓库规范，通过流程化方式降低问题出现的可能性。

目标

除解决背景中提到的问题外，代码仓库规范旨在达成以下目标：

1. 业务可持续：避免项目迭代到后期线上、开发等分支错乱，确保系统代码长期可维护，业务变化可追溯

2. 知识传承：项目新同学可根据代码重复流程，降低上手成本，促进知识不断积累、传递

3. 远程仓库整洁：只提交项目开发/测试/运行相关的文件，IDE配置文件、编译文件等不可上传污染远程仓库

代码仓库规范

仓库创建

项目主R负责申请创建项目代码仓库，代码仓库的创建应遵循以下原则：

1. 按照不同的项目创建相应的代码仓库，避免不相关项目的代码放到一个库

2. 避免按工程创建代码库，易导致代码仓库过多的问题。合理做法是按业务或按功能将同类工程放入一个代码仓库中

权限管理

合理的权限管理可以避免项目主分支合入未review代码，权限管理应遵循以下原则：

1. 项目成员拥有非主分支Write权限，组内非项目成员拥有Read权限

2. 项目主R保留主分支Write权限，同时按需为相应同学开放Write权限

3. 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文件中需要包含以下信息：

1. 简要说明此代码库解决的问题

2. 项目结构简介，以模块粒度说明每个模块的作用、运行环境、线上链接等

3. 项目文档外链，如需求文档、设计文档等

4. 其他注意事项，如项目特殊依赖等

5. 问题及需求反馈

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-*分支，遵循以下原则：

1. 仓库必须有一个主分支(master)，主分支只有部分同学有Write权限

2. 上线作业/工程必须采用主分支上的代码

3. 开发新功能(feature)、修复bug、测试，统一使用feature-*分支(简洁分支管理不存在develop分支，feature-*分支从master分支检出)

4. feature-*分支向主分支合入需要以PR形式进行，并配合Code review，完成后由具有Write权限的同学合并至主分支

5. 定期删除已合并至主分支的feature-*分支，避免仓库分支过多难以管理

Tag管理

Tag可以理解成不可更新的特殊分支，也可以理解为某次commit指定的易于理解的别名，方便项目发布过程中的版本管理及线上问题回滚。Tag管理遵循以下原则：

1. Tag需要在上线前创建，上线所用的Tag需要在主分支上创建

2. 项目上线需要以Tag为基准(例外：离线托管平台上的Spark等作业需要指定分支发布)，保证线上发布版本能够找到对应Tag

3. Tag一般不做删除

Tag示例：

 参考链接