Github使用规范

软工实践

一、分支管理

• 原则：保证 master 分支是稳定可用的版本
• 项目成员的本地代码变动一律签入远程项目的dev分支
• 当且仅当在dev分支完成一个稳定可用的milestone且短期内对此现行版本不再做任何改动时合并进master

二、签入代码

前提条件

每一次从团队远程仓库同步到本地后，在做任何改动前都要先在本地运行一次。
每一次 pull request 的代码必须确保没有代码错误，且能在本地正常运行
如果某个模块写了一半临时先去写别的之前，应在未完成模块前加上“//TODO:”（AS是会检测出这个关键字高亮的），然后完成了其他模块要pr的时候content里面记得写上一行xxx模块（或函数等等）待完成。

pull request注释信息规范

每次签入代码时，需在注释中提供对所做修改的合理概括的标题和具体详尽的内容。描述的信息应是此次改动是什么而非具体代码是怎么实现的。

Title

• 标题末尾不添加句号
• 遵守如下格式：<类别>(事项): <描述> 例如：fix(记录): Android4.0 下点击分享按钮闪退
  其中，
  
  • 类别为下面类别列表选其一，描述统一为中文
  • 注意：括号和冒号为英文字符，冒号后有一空格

类别列表

feat：新功能（feature）
fix：修补bug
docs：文档（documentation）
style：格式（不影响代码运行的变动）
refactor：重构（即不是新增功能，也不是修改bug的代码变动）
test：增加测试
chore：构建过程或辅助工具的变动

Content

• 分点详细解释标题描述的改动详情
• 每个分点项的末尾不添加任何符号
• 英文和中文字符之间用空格隔开
• 每个分点项遵守如下格式：- <详细描述>
  例如：

- 更新 GoDaddy 类的 GoDaddyEurope 方法
- 替换 GoDaddy 类的 runer 属性为 runner

一个注释信息清晰好看的github项目示例： https://github.com/TryGhost/Ghost-CLI/commits/master

三、关于commit

• 确保每一次的 commit 是目的明确的、有意义的改动。
• 如果某次提交修改的范围太小，比如只修改了一个文件中某个变量的赋值操作，应与其他 commit 合并。

• 如果某次提交修改的范围太大，如改动了非常多的文件，建议划分为多次 commit 。
  如何衡量：当发现很难在注释里一次描述清楚所有改动的时候，就意味着此次 commit 需要划分，此时应先把当前的变动 stash 起来，新建一条分支先去解决预期外的问题。

  推荐在着手代码前先写好 commit 信息，然后再开始动手实现，一旦完成就 commit 。

commit注释

参考pull request注释规范，区别在于描述粒度更小、更具体。

使用gitkraken提交commit（推荐）

图形界面的好处在于写commit注释信息的时候有title栏和content栏可直接填入。

使用命令行提交commit

在使用命令行进行提交时，通常使用git commit -m '注释信息'来填写commit注释信息，但是-m参数适合单行注释，对于多行的commit注释来说是不合适的。 应使用git commit -v命令，会自动跳出文本栏以供commit注释信息的编辑，其中文本的首行将作为commit的标题，剩余部分将作为补充信息。

四、关于团队实战中遇到的问题

问题1：

• “编写xxxx”不对。commit描述的是代码做了什么，而不是你做了什么。
• “feat(登录界面): 编写登录界面”不对。没有具体描述的时候甚至可以直接不写冒号和后续的文字，而不用feat(A): 实现A。冒号后面写的应该是对A的某个子部分的描述。可以【feat(登录): 实现界面】 或者 【feat(登录界面)】