Commit Message Format Rules
It is desirable to keep the history of the stable branch develop as clean and linear as possible for more effective code review and automatic generation of CHANGELOG.md. There are a few ways to achieve this with Git, but here the process is established to put the burden on the developer of a new branch. More specifically the developer of issue3 must squash all local commits from issue3 branch into a single properly formatted commit before publishing changes and doing a pull request to develop. If you are new to squashing commits start here.
Before going through the steps for doing this a word on the standard format for the commits. The consolidated commit message must follow the following conventions adapted from Google project AngularJS which will greatly enhanced the historical information on develop and allow for automatic generation of the changelog. The format of the commit message must follow the following convention.
<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>
Any line of the commit message must not be longer than 100 characters. This allows the message to be easier to read on github as well as in various git tools.
<type>
Should be either of the following:
- feat (when working on new feature)
- fix (when fixing a bug or addressing a security vulnerability)
- docs (when working on documentation)
- style (improving formatting, missing semi colons, indentation, etc.)
- refactor (when doing minor or major refactoring work)
- test (when adding missing tests)
- chore (maintain)
<scope>
Should specify the location of the commit as succinctly and completely as possible (e.g. $location, $rootScope, ngHref, ngClick, ngView)
<subject>
Subject line contains succinct description of the change. Remember it must not be longer than 100 characters and this *includes* both the <type>(<scope>) identified before. Here are some convensions:
- use imperative, present tense: “change” not “changed” nor “changes”
- don't capitalize first letter
- no period full stop (.) at the end
<body>
[Optional] Slightly more elaborated description possibly spanning over several lines never more than 100 characters each.
- just as in <subject> use imperative, present tense
- includes motivation for the change and contrasts with previous behavior
<footer>:
[Optional] should include either breaking changes and/or references of what issues were resolved if any. All breaking changes have to be mentioned in footer with the description of the change, justification and migration notes.
The following includes several examples of properly formatted squashed commit messages.
A new feature commit.
feat($browser): onUrlChange event (popstate/hashchange/polling) Added new event to $browser: * 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) A fix for browser compatibility commit.
fix($compile): couple of 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
A new feature request from issue #351 commit.
feat(directive): ng:disabled, ng:checked, ng:multiple, ng:readonly, ng:selected New directives for proper binding these attributes in older browsers (IE). Added coresponding description, live examples and e2e tests. Closes #351, #456
Some cleanup commit.
style($location): add couple of missing semi colons
Some documentation work commit.
docs(guide): updated fixed docs from Google Docs Couple of typos fixed: * indentation * batchLogbatchLog -> batchLog * start periodic checking * missing brace
A new feature with major breaking changes.
feat($compile): simplify isolate scope bindings
Changed 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.
For example, you've been working on your branch and made three commit with vague non-useful messages such as “Work in progress”, “Small fix”, etc. You want to wrap up the work with a nice single squashed commit following the above format. You can use Git's rebase tool but it is not the only way. Some examples are included below but you may need to refer to online documentation on this or ask one of the core developers for help.
In SourceTree
There is a good article on interactive rebase and squashing commits here.
Git command line
> git rebase -i HEAD~3
This will pull open an editor with something like the following.
pick f7f3f6d Work on docs pick 310154e Work in progress pick a5f4a0d Small fix # Rebase 710f0f8..a5f4a0d onto 710f0f8 # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup = like "squash", but discard this commit's log message # x, exec = run command (the rest of the line) using shell # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # Note that empty commits are commented out
To squash the three commits into one you would edit the script to look like this.
pick f7f3f6d Work on docs squash 310154e Work in progress squash a5f4a0d Small fix # Rebase 710f0f8..a5f4a0d onto 710f0f8 # # Commands: # p, pick = use commit # r, reword = use commit, but edit the commit message # e, edit = use commit, but stop for amending # s, squash = use commit, but meld into previous commit # f, fixup = like "squash", but discard this commit's log message # x, exec = run command (the rest of the line) using shell # # These lines can be re-ordered; they are executed from top to bottom. # # If you remove a line here THAT COMMIT WILL BE LOST. # # However, if you remove everything, the rebase will be aborted. # # Note that empty commits are commented out
When saving this you will return to a text editor where you can merge the commit messages seeying something like this.
# This is a combination of 3 commits. # The first commit's message is: Work on docs # This is the 2nd commit message: Work in progress # This is the 3rd commit message: Small fix
Those commits are practically useless in the grand scheme of things. You want to replace it with a single properly formatted message following above conventions. In this case you would remove the above from the text editor and replace it with something like the following.
docs(developer-guide.rst): update docs with new code base refactory What's changed in details: * Change backend section to reflect migration to NodeJS * Refactor various part of guide with new content * Introduce new conventions and standards Save this nicely formatted commit and then you're ready to publish your work and do a pull request. <code> > git push
Although if you were working entirely on a detached local branch like I do you would need to push like this instead.
$ git push --set-upstream origin replace-this-with-branch-name
Do the pull request from bitbucket and use the last commit as the message.