提交Commit指南
===

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

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

## format

<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:

        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:

            <type>[optional scope]:< ><description>
            //empty line here
            [optional body]
            //empty line here
            BREAKING CHANGE:< ><description>
            //empty line here
            <detail>

+ ex:

            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

            <type>[optional scope]:< ><description>
            //empty line here
            [optional body]
            //empty line here
            Closes< ><issue number list>

+ ex:

            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

        revert:< ><type>[optional scope]:< ><description>
        //empty line here
        This reverts commit <hash>

+ ex:

        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)