Merge pull request #1437 from deis/commit-guideline

ref(contributing): changes to the commit style guideline

Author: Matthew Fisher

CONTRIBUTING.md

@@ -33,43 +33,50 @@ This is a rough outline of what a contributor's workflow looks like:
 
 Thanks for your contributions!
 
-### Format of the Commit Message
+### Commit Style Guideline
 
 We follow a rough convention for commit messages borrowed from CoreOS, who borrowed theirs
 from AngularJS. This is an example of a commit:
 
-```
     feat(scripts/test-cluster): add a cluster test command
 
     this uses tmux to setup a test cluster that you can easily kill and
     start for debugging.
-```
 
-To make it more formal it looks something like this:
+To make it more formal, it looks something like this:
 
-```
-{type}({scope}): {subject}
-<BLANK LINE>
-{body}
-<BLANK LINE>
-{footer}
-```
 
-Any line of the commit message cannot be longer than 90 characters, with the subject line
-limited to 70 characters. This allows the message to be easier to read on github as well
+    {type}({scope}): {subject}
+    <BLANK LINE>
+    {body}
+    <BLANK LINE>
+    {footer}
+
+The {scope} can be anything specifying place of the commit change.
+
+The {subject} needs to use imperative, present tense: “change”, not “changed” nor
+“changes”. The first letter should not be capitalized, and there is no dot (.) at the end.
+
+Just like the {subject}, the message {body} needs to be in the present tense, and includes
+the motivation for the change, as well as a contrast with the previous behavior. The first
+letter in a paragraph must be capitalized.
+
+All breaking changes need to be mentioned in the {footer} with the description of the
+change, the justification behind the change and any migration notes required.
+
+Any line of the commit message cannot be longer than 72 characters, with the subject line
+limited to 50 characters. This allows the message to be easier to read on github as well
 as in various git tools.
 
 The allowed {types} are as follows:
 
-```
-feat -> feature
-fix -> bug fix
-docs -> documentation
-style -> formatting
-refactor
-test -> adding missing tests
-chore -> maintenance
-```
+    feat -> feature
+    fix -> bug fix
+    docs -> documentation
+    style -> formatting
+    ref -> refactoring code
+    test -> adding missing tests
+    chore -> maintenance
 
 ### More Details on Commits
 

docs/contributing/standards.rst

@@ -194,8 +194,8 @@ Format of the Commit Message
     <BLANK LINE>
     {footer}
 
-Any line of the commit message cannot be longer than 90 characters, with the subject
-line limited to 70 characters. This allows the message to be easier to read on github
+Any line of the commit message cannot be longer than 72 characters, with the subject
+line limited to 50 characters. This allows the message to be easier to read on github
 as well as in various git tools.
 
 Subject Line
@@ -209,7 +209,7 @@ The allowed {types} are as follows:
 - fix -> bug fix
 - docs -> documentation
 - style -> formatting
-- refactor
+- ref -> refactoring code
 - test -> adding missing tests
 - chore -> maintenance