---
# System prepended metadata

title: 提交Commit指南

---

提交Commit指南
===

###### tags: `work` `done`
[toc]

## Golden rule
> for adding human and machine readable meaning to commit messages

## format
```text
<type>[optional scope]:< ><description>
//empty line here
[optional body]
//empty line here
[optional footer]
```
+ `type` : 由下列選項擇一
    + `build`(常用): Changes that affect the build system or external dependencies *(example scopes: gulp, broccoli, npm)*
    + `chore`: Updating grunt tasks etc; no production code change *(means nothing that an external user would see)*
        > + implementation (of an existing feature, which doesn't involve a fix),
        > + configuration (like the .gitignore or .gitattributes),
        > + private internal methods...
    + `ci`: Changes to our CI configuration files and scripts *(example scopes: Travis, Circle, BrowserStack, SauceLabs)*
    + `docs`(常用): Documentation only changes
    + `feat`(常用): A new feature *(this correlates with **PATCH** in semantic versioning^[[semantic versioning](https://semver.org/#summary)])*
    + `fix`(常用): A bug fix *(this correlates with **MINOR** in semantic versioning)*
    + `hotfix`: 
    + `perf`(常用): A code change that improves performance
    + `refactor`: A code change that neither fixes a bug nor adds a feature
    + `style`: Changes that do not affect the meaning of the code *(white-space, formatting, missing semi-colons, etc)*
    + `test`(常用): Adding missing tests or correcting existing tests
+ `scope` : (optional)目前沒有統一的標準，通常會跟軟體開發方法而變
    > Scope could be anything specifying place of the commit change
    + 元件導向範例：`init` `runner` `watcher` `config` `web-server` `proxy`
    + MTC範例: `model` `view` `controller`
    + 物件導向(類別名稱) 
+ `description` : The subject contains a succinct description of the change
    + ==ENGLISH ONLY==
    + less than 50 characters
        > 50字元的限制而是一個[經驗法則](https://stackoverflow.com/questions/2290016/git-commit-messages-50-72-formatting)。
        > 讓標題保持在 50 字以下能夠確保標題的可讀性，並且強迫作者思考如何用更簡潔的方式表達發生什麼事情。
        > 如果你很難總結出標題，這代表你可能在一個 commit 裏面做了太多的改變。請儘量讓 commits 單一化，一次只更動一個主題 (atomic commits)。
    + don't capitalize the first letter
    + no dot (.) at the end
    + use the imperative, present tense: "change" not "changed" nor "changes"
        > 由於語言習慣問題，大家比較常使用指示性語句，來描述事實。為了避免這個問題，我們提供一個簡單的把戲來幫助大家完成正確的祈使句型
        > 一個正確的 Git commit 標題應該要能夠代入下面的句型，使之成為完整的句子：
        >  + ==If applied, this commit will <你的標題>==
        >  ex:
        >      + If applied, this commit will update getting started documentation
        >      + If applied, this commit will update getting started documentation
        >  若不正確使用祈使句，會導致句子語意不通順
        >  ex:
        >      + If applied, this commit will fixed bug with Y
        >      + If applied, this commit will changing behavior of X
+ `body` :  (optional) more details than the `description` include motivation for the change and contrasts with previous behavior
    > 解釋"what"和"why"(改變了"什麼"和"為什麼"改變)
    + less than 72 characters *per line*
    + use the imperative, present tense: "change" not "changed" nor "changes"
    + `markdown` style
    + ex:
        ```markdown
        More detailed explanatory text, if necessary.  Wrap it to 
        about 72 characters or so. 

        Further paragraphs come after blank lines.

        - Bullet points are okay, too
        - Use a hanging indent
        ```
+ `footer` :  (optional) only needed for two cases: `break change` and `close issue`
    + `break change`: All breaking changes have to be mentioned in footer with the description of the change, justification and migration notes. *(this correlating with `MAJOR` in semantic versioning)*
        + start with the word `BREAKING CHANGE: <description>` and follow a newline .The rest of the commit message is then used for this.
        + format:
            ```text
            <type>[optional scope]:< ><description>
            //empty line here
            [optional body]
            //empty line here
            BREAKING CHANGE:< ><description>
            //empty line here
            <detail>
            ```
        + ex:
            ```markdown
            BREAKING CHANGE: isolate scope bindings definition has changed.
            
            `port-runner` command line option has changed to `runner-port`, so that it is
            consistent with the configuration file syntax.

            To migrate your project, change all the commands, where you use `--port-runner`
            to `--runner-port`.
            ```
    + `close issue`: Closed issues should be listed on a separate line in the footer prefixed with `Closes:` 
        + format
            ```text
            <type>[optional scope]:< ><description>
            //empty line here
            [optional body]
            //empty line here
            Closes< ><issue number list>
            ```
        + ex:
            ```markdown
            Closes #123, #245, #992
            ```
+ ==special case== `revert`: If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit \<hash\>., where the hash is the SHA of the commit being reverted.
    + format
        ```text
        revert:< ><type>[optional scope]:< ><description>
        //empty line here
        This reverts commit <hash>
        ```
    + ex:
        ```markdown
        revert: feat(pencil): add 'graphiteWidth' option

        This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
        ```

## All-in-one solution


## reference
1. [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.4)
2. [karma commit msg](http://karma-runner.github.io/0.10/dev/git-commit-msg.html)
3. [Commit message 和 Change log 编写指南](http://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html)
4. [如何寫一個 Git Commit Message](https://blog.louie.lu/2017/03/21/%E5%A6%82%E4%BD%95%E5%AF%AB%E4%B8%80%E5%80%8B-git-commit-message/)
5. [优雅的提交你的 Git Commit Message](https://zhuanlan.zhihu.com/p/34223150)