Git Commit Message 这样写会更好，替专案引入规範与範例

Git Commit Message 的用意与规範

其实写 Commit 记录讯息，有时候跟写程式注解还蛮像的，
最好可以写下「为什么」你要作这样的异动，
而不是单单只记录下你做了「什么」异动，
Commit 记录讯息最好兼俱 Why 及 What，让日后进行维护人员更快进入状况。

Commit Message 这样写会更好：

还没使用 Git 之前，大家习惯在程式码里面写注解。但是注解常常不会随着程式码的异动而更新。因此开始使用 Git 后，就应该把注解记录在 commit 里面，以保持程式码的整洁跟可读性。做 issue 的时候，不应该一次 commit 所有异动，应该独立 commit 每个不同意义的异动，这样 commit 讯息才会跟异动的程式码有关联。每次 commit 都是针对异动的档案做说明：Why & What。这样的 commit 讯息能让日后进行维护人员更快进入状况每次 commit 都加上 issue 编号，方便追蹤程式异动的原因。不能只把 Git 当作程式码的 FTP，这样太可惜了，要把 Git 当作历史查阅的工具才拿发挥 Git 的功能。

好与不好的真实案例

用一个小插曲证实 Commit 讯息的重要性
上面 PPT 是我在工作中遇到的两个案例，範例中包含「好的 Commit Message」与「不良的 Commit Message」。
在範例中可见：
「好的 Commit Message」如何在一年后的让维护人员进入状况，
「不良的 Commit Message」如何在一个月内让维护人员找不出异动脉络。

Commit Message 之规範

在撰写 Git 与 SVN 等版本控制软体 Commit Message 时，可以参照国外 AngularJS 团队的规範： AngularJS Git Commit Message Conventions

以下为这套讯息规範的展示与说明：
Commit Message 规範範例：

Commit Message 规範範例解析：

Commit Message 规範组成：

Header: <type>(<scope>): <subject> - type: 代表 commit 的类别：feat, fix, docs, style, refactor, test, chore，必要栏位。 - scope 代表 commit 影响的範围，例如资料库、控制层、模板层等等，视专案不同而不同，为可选栏位。 - subject 代表此 commit 的简短描述，不要超过 50 个字元，结尾不要加句号，为必要栏位。Body: 72-character wrapped. This should answer: * Body 部份是对本次 Commit 的详细描述，可以分成多行，每一行不要超过 72 个字元。 * 说明程式码变动的项目与原因，还有与先前行为的对比。Footer:  - 填写任务编号（如果有的话）. - BREAKING CHANGE（可忽略），记录不兼容的变动，   以 BREAKING CHANGE: 开头，后面是对变动的描述、以及变动原因和迁移方法。

type: subject 是简述不要超过 50 个字元

type 只允许使用以下类别：

feat: 新增/修改功能 (feature)。fix: 修补 bug (bug fix)。docs: 文件 (documentation)。style: 格式 (不影响程式码运行的变动 white-space, formatting, missing semi colons, etc)。refactor: 重构 (既不是新增功能，也不是修补 bug 的程式码变动)。perf: 改善效能 (A code change that improves performance)。test: 增加测试 (when adding missing tests)。chore: 建构程序或辅助工具的变动 (maintain)。revert: 撤销回覆先前的 commit 例如：revert: type(scope): subject (回覆版本：xxxx)。

Commit 讯息範例

範例 fix：

fix: 自订表单新增/编辑页面，修正离开页面提醒逻辑问题：1. 原程式码进入新增页面后，没做任何动作之下，离开页面会跳提醒2. 原程式码从新增/编辑页面回到上一页后（表单列表页面），离开页面会跳提醒原因：1. 新增页面时，页面自动建立空白题组会调用 sort_item，造成初始化 unload 事件处理器。2. 回到上一页后，就不需要监听 unload 事件，应该把 unload 事件取消。调整项目：1. 初始化 unload 事件处理器：排除新增表单时，页面自动建立空白题组调用 sort_item 的情境2. 回到上一页后，复原表单被异动状态且清除 unload 事件处理器issue #1335

fix: 意见反应，信件看不到图片问题问题：1. 客户反应：意见反应的信件都看不到图片。原因：1. 目前程式码都会要求先登入后才可查看使用者上传的档案，   造成在信件上会看不见图片的问题。调整项目：1. File.php，经讨论后，开放让意见反应页面上传的档案，不用登入就可以查看/下载。issue #1229

---

範例 feat:

feat: message 信件通知功能因应新需求做调整： 通知和 message 都要寄发每日信件， 通知和 message 都用放在同一封信里面就好， 不然信件太多可能也不会有人想去看。调整项目：1. mail_template.php，新增 message 区块。2. Send_today_notify_mail.php，新增 取得每日 Message 逻辑。3. Message_model_api.php，新增 $where 参数，以便取得每日讯息。4. Message_api.php、Message_group_user_model_api.php，新增 **取得讯息使用者** 逻辑，以便捞取每日讯息。issue #863

feat: 表单统计，多显示计画名称栏位因应需求做调整：1. 列表资讯多加「计画名称」栏位，以利后续汇出资料处理。调整项目：1. Assessment_form.php，汇出表单统计时，新增训练计画名栏位。2. customize.php，表单统计查询时，多显示训练计画名栏位。3. Complex_assessment_form_api.php、Complex_assessment_form_model_api.php：  - 取得表单统计资料时，多取得计画名称。issue #1200

---

範例 chore:

chore: 更新 testing 环境更新 ci-phpunit-test 套件 0.16 => 0.17for Request GET 带参数功能。

chore:调整单元测试环境调整项目：1. MX/Modules将客製化 Testing 的逻辑移除，否则在测试环境中无法正确存取档案。2. 加入 tests/unit 与 tests/integration 目录，并将测试档案移至合宜的位置。3. AdminTestCase.php，继承 TestCase，实作登入逻辑、setUp 与 tearDown，供其他测试案例继承使用。4. Bootstrap.php，引入 AdminTestCase.php 共测试案例继承用。5. Login.php，因测试案例中不能有 header 的设定，更动系统登入逻辑，在测试环境中改用 redirect 转址。6. phpunit.xml，取消严谨宣告覆盖模式，避免造成测试不通过（若需知道你的测试案例覆盖了哪些类别或逻辑，可自行打开）。## 备注： unit 与 integration 目录分别为「单元测试目录」与「整合测试目录」，单元测试目录负责测试 Api 与 Model，整合测试目录则负责测试 Controller。issue #709

---

範例 style:

style: message 页面，对 Component 做 Beautifier经 IE 浏览器测试后发现 Component 里面仍然夹带 ES6 语法，但是目前 Component 的程式码都被压缩成一行，为了日后修改程式方便，故先对所有被压缩的程式码做 Beautifier调整项目：1. 针对所有被压缩的程式码做 Beautifier2. 移除被注解的程式码，原本被注解的程式码应该是压缩前的程式码，但是经测试后发现这些被注解的程式码都是旧 Code，故移除。issue #1219issue #1028

style: 统一换行符号 CRLF to LF统一换行符号

style: 调整 HTML 缩排issue #964

---

範例 refactor:

refactor: 重构取得「签核流程种类名称」逻辑原程式码取得流程名称的逻辑散落在多个档案，为了让未来新增/修改种类名称时，不必到多个档案找查程式，现在统一透过 Process::get_type_name($process_type) 方法，取得流程种类名称。调整项目：1. Process.php，新增 get_type_name() 方法，供取得流程名称称用。2. workflow_type_name.php，此 View 档案只是为了取得流程名称，现在以 Process:: get_type_name() 取代，故删除。3. Workflow_api.php，get_process_name() 方法是为了取得流程名称，现在以 Process:: get_type_name() 取代，故删除。4. 其他档案：改用 Process:: get_type_name()  取得流程名称。issue #1253

refactor: 表单统计，语意化调整汇出表单时的表单答题资料，应该是以表单 $assessment_result  为基準做统计，故更改变数名称 $user => $assessment_resultissue #1200

refactor: 每日通知信件，重构程式结构考量将来可能会需要寄送多种资讯给使用者，故重构程式结构，让未来扩充功能时比较方便。调整内容：1. Send_today_notify_mail：  - 把取得「系统通知」逻辑搬移至 System_notify_handler.php  - 把取得「站内讯息」逻辑搬移至 Message_handler.php  - 引入 Pipeline，把取得各种系统资讯的逻辑注入进 Pipeline。  - 透过 Pipeline 取得每日通知信件内容，并建立信件 HTML2. Daily_email 介面：  - 定义 每日信件处理器 Xxx_handler 的方法  - 之后要扩充新的功能，必须按照 Daily_email 介面的定义，实作方法。3. message.php、system_notify.php：  - 将「系统通知」与「站内讯息」的 Email 页面独立出来。issue #1308

---

範例 perf:

perf: 评核表单列表，优化取得受评者速度原本取得受评者的逻辑会造成载入页面缓慢（开发机约 52 秒），故做优化。调整方式：原程式码每个表单迴圈进入 DB 取得受评者资料。改成进 DB 一次捞取全部受评者资料，再回到 PHP 分配资料。结果：开发机载入页面时间  52 秒 => 5秒issue #1272

---

範例 docs:

docs: 新增注解

docs: 修正型别注解让 IDE 可以读取到正确的类别

docs: 移除过期的注解issue #1229

此文章也会同步到：我的部落格