RFC: Git Commit Message Guidelines
In the last few yers, the number of programmers concerned about writting structured commit messages had dramatically grown. As exposed by Tim Pope in article readable commit messages are easy to follow when looking through the project history. Moreover the AngularJS contributing guides introduced conventions that can be used by automation tools to automatically generate useful documentation, or by developpers during debbuging process.
This document borrow some concepts, conventions and even text mainly from these two sources, extending them in order to provide a sensible guideline for writing commit messages.
Consider the following commit messages:
On the one hand, looking at the first 5 messages is not possible to identify which part of the code had changed. (The remaining messages try to specify where is the change, but they don’t share any convention...)
On the other hand, commits introducing formatting changes (adding/removing spaces/empty lines, indentation), missing semi colons, comments, etc are not interesting to debbug code or to documenting changes, since no logic change inside them.
Although it is posible to find more information by checking which files had been changed and performing some diffs, it is not practical when looking in git history.
Structural conventions can speed up this process, by allowing filtering. For example, when bisecting, you can ignore files by doing:
git bisect skip $(git rev-list --grep irrelevant <good place> HEAD)
<type>(<scope>): <subject> <meta>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on github as well as in various git tools.
Subject line may be prefixed for continuous integration purposes. For example, JIRA requires ticket in the beggining of commit message message: "[LHJ-16] fix(compile): add unit tests for windows"
<type>
<scope>
Scope could be anything specifying place of the commit change. For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc...
<subject>
textSubject line should contains succinct description of the change.
<meta>
Additionally, the end of subject-line may contain twitter-inspired markup to facilitate changelog generation and bissecting.
#wip
- indicate for contributors the feature being implemented is not complete yet. Should not be included in changelogs (just the last commit for a feature goes to the changelog).#irrelevant
- the commit does not add useful information. Used when fixing typos, etc... Should not be included in changelogs.<subject>
use imperative, present tense: “change” not “changed” nor “changes”http://365git.tumblr.com/post/3308646748/writing-git-commit-messages http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
All breaking changes have to be mentioned in footer with the description of the change, justification and migration notes
BREAKING CHANGE: isolate scope bindings definition has changed and
the inject option for the directive controller injection was removed.
To migrate the code follow the example below:
Before:
scope: {
myAttr: 'attribute',
myBind: 'bind',
myExpression: 'expression',
myEval: 'evaluate',
myAccessor: 'accessor'
}
After:
scope: {
myAttr: '@',
myBind: '@',
myExpression: '&',
// myEval - usually not useful, but in cases where the expression is assignable, you can use '='
myAccessor: '=' // in directive's template change myAccessor() to myAccessor
}
The removed `inject` wasn't generaly useful for directives so there should be no code using it.
Closed bugs should be listed on a separate line in the footer prefixed with "Closes" keyword like this:
Closes #234
or in case of multiple issues:
Closes #123, #245, #992
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 ., where the hash is the SHA of the commit being reverted.
feat($browser): add onUrlChange event (popstate/hashchange/polling)
New $browser event:
- forward popstate event if available
- forward hashchange event if popstate not available
- do polling when neither popstate nor hashchange available
Breaks $browser.onHashChange, which was removed (use onUrlChange instead)
fix($compile): add unit tests for IE9
Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.
Closes #392
Breaks foo.bar api, foo.baz should be used instead
feat(directive): add directives disabled/checked/multiple/readonly/selected
New directives for proper binding these attributes in older browsers (IE).
Added coresponding description, live examples and e2e tests.
Closes #351
style($location): add couple of missing semi colons
docs(guide): update fixed docs from Google Docs
Couple of typos fixed:
- indentation
- batchLogbatchLog -> batchLog
- start periodic checking
- missing brace
feat($compile): simplify isolate scope bindings
Change the isolate scope binding options to:
- @attr - attribute binding (including interpolation)
- =model - by-directional model binding
- &expr - expression execution binding
This change simplifies the terminology as well as
number of choices available to the developer. It
also supports local name aliasing from the parent.
BREAKING CHANGE: isolate scope bindings definition has changed and
the inject option for the directive controller injection was removed.
To migrate the code follow the example below:
Before:
scope: {
myAttr: 'attribute',
myBind: 'bind',
myExpression: 'expression',
myEval: 'evaluate',
myAccessor: 'accessor'
}
After:
scope: {
myAttr: '@',
myBind: '@',
myExpression: '&',
// myEval - usually not useful, but in cases where the expression is assignable, you can use '='
myAccessor: '=' // in directive's template change myAccessor() to myAccessor
}
The removed `inject` wasn't generaly useful for directives so there should be no code using it.
Changleos may contain three sections: new features, bug fixes, breaking changes. This list could be generated by script when doing a release, along with links to related commits. Of course you can edit this change log before actual release, but it could generate the skeleton.
List of all subjects (first lines in commit message) since last release:
git log <last tag> HEAD --pretty=format:%s
New features in this release
git log <last release> HEAD --grep feat
Thanks to @stephenparish for the original text