doc(commit_convention): add git commit_convention

2013-09-25 19:43:42 -07:00 · 2013-09-25 19:43:42 -07:00 · 6aec85e6c2
commit 6aec85e6c2
parent 70e7bcd9e4
2 changed files with 78 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -49,4 +49,5 @@ Miscellaneous
 - [Testing and Code Coverage](doc/make/coverage.md)
 - Building Doxygen Documentation: `doxygen src/Doxyfile`
 - [Coding style](doc/coding_style.md)
+- [Git Commit Convention](doc/commit_convention.md)
 - [Automatic builds](doc/make/travis.md)
--- a/doc/commit_convention.md
+++ b/doc/commit_convention.md
@ -0,0 +1,77 @@
+Git Commit Convention
+=====================
+
+We are using the following convention for writing git-commit messages.
+It is based on the one from AngularJS project([doc][angularjs-doc],
+[commits][angularjs-git]).
+
+[angularjs-git]: https://github.com/angular/angular.js/commits/master
+[angularjs-doc]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#
+
+Format of the commit message
+----------------------------
+
+    <type>(<scope>): <subject>
+    <NEWLINE>
+    <body>
+    <NEWLINE>
+    <footer>
+
+``<type>`` is:
+
+ - feat (feature)
+ - fix (bug fix)
+ - doc (documentation)
+ - style (formatting, missing semicolons, ...)
+ - refactor
+ - test (when adding missing tests)
+ - chore (maintain, ex: travis-ci)
+
+``<scope>`` is a name of module or a directory which contains changed modules. For instance,
+it could be
+
+ - kernel/expr
+ - kernel
+ - library/rewrite
+
+``<subject>`` has the following constraints:
+
+ - use imperative, present tense: "change" not "changed" nor "changes"
+ - do not capitalize the first letter
+ - no dot(.) at the end
+
+``<body>`` has the following constraints:
+
+ - just as in ``<subject>``, use imperative, present tense
+ - includes motivation for the change and contrasts with previous
+   behavior
+
+``<footer>`` is optional and may contain two items:
+
+ - Breaking changes: All breaking changes have to be mentioned in
+   footer with the description of the change, justification and
+   migration notes
+ - Referencing issues: Closed bugs should be listed on a separate line
+   in the footer prefixed with "Closes" keyword like this:
+
+    Closes #123, #456
+
+Examples
+--------
+
+fix(kernel): add declarations for operator<<(std::ostream&, expr const&) and operator<<(std::ostream&, context const&) in the kernel
+
+The actual implementation of these two operators is outside of the
+kernel. They are implemented in the file 'library/printer.cpp'. We
+declare them in the kernel to prevent the following problem. Suppose
+there is a file 'foo.cpp' that does not include 'library/printer.h',
+but contains
+
+    expr a;
+    ...
+    std::cout << a << "\n";
+    ...
+
+The compiler does not generate an error message. It silently uses the
+operator bool() to coerce the expression into a Boolean. This produces
+counter-intuitive behavior, and may confuse developers.