Skip to content

Instantly share code, notes, and snippets.

@thmsdmcrt

thmsdmcrt/commit.md

Forked from abravalheri/commit.md
Created May 9, 2019 07:51
Show Gist options
  • Save thmsdmcrt/bbcb87e5d50da802bc4d8928d6e74e2b to your computer and use it in GitHub Desktop.
Save thmsdmcrt/bbcb87e5d50da802bc4d8928d6e74e2b to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. @abravalheri abravalheri revised this gist Mar 1, 2016. 1 changed file with 1 addition and 3 deletions.
    4 changes: 1 addition & 3 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -34,16 +34,14 @@ Consider the following commit messages:
    * Bit of refactoring
    * Check whether links do exist and throw exception
    * Fix sitemap include (to work on case sensitive linux)


    * Fix small typo in docs widget (tutorial instructions)
    * Fix test for scenario.Application - should remove old iframe
    * docs - various doc fixes
    * docs - stripping extra new lines
    * Replaced double line break with single when text is fetched from Google
    * Added support for properties in documentation

    On the one hand looking at the first group of messages is not possible to identify which part of the code had changed. In turn, the second group of messages try to specify where is the change, but they don’t share any convention...
    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.

  2. @abravalheri abravalheri revised this gist Mar 1, 2016. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -35,6 +35,7 @@ Consider the following commit messages:
    * Check whether links do exist and throw exception
    * Fix sitemap include (to work on case sensitive linux)


    * Fix small typo in docs widget (tutorial instructions)
    * Fix test for scenario.Application - should remove old iframe
    * docs - various doc fixes
  3. @abravalheri abravalheri revised this gist Mar 1, 2016. 1 changed file with 19 additions and 9 deletions.
    28 changes: 19 additions & 9 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -16,6 +16,7 @@ This document borrow some concepts, conventions and even text mainly from these
    - [Breaking changes](#breaking-changes)
    - [Referencing issues](#referencing-issues)
    * [Examples](#examples)
    * [Revert](#revert)
    * [Generating CHANGELOG.md](#generating-changelogmd)

    Goals
    @@ -65,26 +66,31 @@ Proposal
    <footer>
    ```

    Subject line contains succinct description of the change. 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.
    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](https://bigbrassband.com/git-for-jira.html)
    > requires ticket in the beggining of commit message message:
    > "[LHJ-16] fix(compile): add unit tests for windows"
    #### Allowed `<type>`
    * feat
    * fix (bug fix)
    * docs (documentation)
    * style (formatting, missing semi colons, …)
    * refactor
    * test (when adding missing tests)
    * chore (maintain)
    * **feat**: A new feature
    * **fix**: A bug fix
    * **docs**: Documentation only changes
    * **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing
    semi-colons, etc)
    * **refactor**: A code change that neither fixes a bug nor adds a feature
    * **perf**: A code change that improves performance
    * **test**: Adding missing tests
    * **chore**: Changes to the build process or auxiliary tools and libraries such as documentation
    generation

    #### Allowed `<scope>`
    Scope could be anything specifying place of the commit change. For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc...

    #### `<subject>` text
    Subject line should contains succinct description of the change.

    * use imperative, present tense: “change” not “changed” nor “changes”
    * don't capitalize first letter
    * no dot (.) at the end
    @@ -96,7 +102,7 @@ Additionally, the end of subject-line may contain twitter-inspired markup to fac
    * `#irrelevant` - the commit does not add useful information. Used when fixing typos, etc... Should not be included in changelogs.

    #### Message body
    * just as in <subject> use imperative, present tense: “change” not “changed” nor “changes”
    * just as in `<subject>` use imperative, present tense: “change” not “changed” nor “changes”
    * includes motivation for the change and contrasts with previous behavior

    http://365git.tumblr.com/post/3308646748/writing-git-commit-messages
    @@ -147,6 +153,10 @@ or in case of multiple issues:
    Closes #123, #245, #992
    ```

    ### 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.

    ### Examples
    ```
    feat($browser): add onUrlChange event (popstate/hashchange/polling)
  4. @abravalheri abravalheri revised this gist Mar 1, 2016. No changes.
  5. @abravalheri abravalheri revised this gist Mar 1, 2016. 1 changed file with 13 additions and 15 deletions.
    28 changes: 13 additions & 15 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -5,19 +5,18 @@ In the last few yers, the number of programmers concerned about writting structu
    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.

    * [Goals](#goals)
    * [Generating CHANGELOG.md](#generating-changelogmd)
    * [Recognizing unimportant commits](#recognizing-unimportant-commits)
    * [Provide more information when browsing the history](#provide-more-information-when-browsing-the-history)
    * [Format of the commit message](#format-of-the-commit-message)
    * [Subject line](#subject-line)
    * [Allowed `<type>`](#allowed-type)
    * [Allowed `<scope>`](#allowed-scope)
    * [`<subject>` text](#subject-text)
    * [Message body](#message-body)
    * [Message footer](#message-footer)
    * [Breaking changes](#breaking-changes)
    * [Referencing issues](#referencing-issues)
    * [Proposal](#proposal)
    - [Commit Message Format](#commit-message-format)
    + [Allowed `<type>`](#allowed-type)
    + [Allowed `<scope>`](#allowed-scope)
    + [`<subject>` text](#subject-text)
    + [Allowed `<meta>`](#allowed-meta)
    + [Message body](#message-body)
    + [Message footer](#message-footer)
    - [Breaking changes](#breaking-changes)
    - [Referencing issues](#referencing-issues)
    * [Examples](#examples)
    * [Generating CHANGELOG.md](#generating-changelogmd)

    Goals
    -----
    @@ -57,7 +56,7 @@ git bisect skip $(git rev-list --grep irrelevant <good place> HEAD)

    Proposal
    --------
    ### Message Format
    ### Commit Message Format
    ```
    <type>(<scope>): <subject> <meta>
    <BLANK LINE>
    @@ -148,8 +147,7 @@ or in case of multiple issues:
    Closes #123, #245, #992
    ```

    Examples
    --------
    ### Examples
    ```
    feat($browser): add onUrlChange event (popstate/hashchange/polling)
  6. @abravalheri abravalheri revised this gist Mar 1, 2016. 1 changed file with 65 additions and 61 deletions.
    126 changes: 65 additions & 61 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,6 +1,8 @@
    Commit Message Conventions
    Commit Message Guidelines
    ==========================
    Conventions borrowed from [the AngularJS commit conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/) and [Tim Pope article](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
    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](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) readable commit messages are easy to follow when looking through the project history. Moreover [the AngularJS contributing guides](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md) 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.

    * [Goals](#goals)
    * [Generating CHANGELOG.md](#generating-changelogmd)
    @@ -23,70 +25,53 @@ Goals
    * allow ignoring commits by git bisect (not important commits like formatting)
    * provide better information when browsing the history

    Generating CHANGELOG.md
    -----------------------
    Changleos may contain these 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.
    Motivation
    ----------
    Consider the following commit messages:

    List of all subjects (first lines in commit message) since last release:
    ```bash
    git log <last tag> HEAD --pretty=format:%s
    ```

    New features in this release
    ```bash
    git log <last release> HEAD --grep feat
    ```

    ### Recognizing unimportant commits
    These are formatting changes (adding/removing spaces/empty lines, indentation), missing semi colons, comments. So when you are looking for some change, you can ignore these commits - no logic change inside this commit.

    When bisecting, you can ignore these by:
    ```bash
    git bisect skip $(git rev-list --grep irrelevant <good place> HEAD)
    ```
    * fix comment stripping
    * fixing broken links
    * Bit of refactoring
    * Check whether links do exist and throw exception
    * Fix sitemap include (to work on case sensitive linux)

    ### Provide more information when browsing the history
    This would add kinda “context” information.
    Look at these messages (taken from last few angular’s commits):
    * Fix small typo in docs widget (tutorial instructions)
    * Fix test for scenario.Application - should remove old iframe
    * docs - various doc fixes
    * docs - stripping extra new lines
    * Replaced double line break with single when text is fetched from Google
    * Added support for properties in documentation

    All of these messages try to specify where is the change. But they don’t share any convention...
    On the one hand looking at the first group of messages is not possible to identify which part of the code had changed. In turn, the second group of messages try to specify where is the change, but they don’t share any convention...

    Look at these messages:
    * fix comment stripping
    * fixing broken links
    * Bit of refactoring
    * Check whether links do exist and throw exception
    * Fix sitemap include (to work on case sensitive linux)
    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.

    Are you able to guess what’s inside ? These messages miss place specification...
    So maybe something like parts of the code: docs, docs-parser, compiler, scenario-runner, …
    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.

    I know, you can find this information by checking which files had been changed, but that’s slow. And when looking in git history I can see all of us tries to specify the place, only missing the convention.
    Structural conventions can speed up this process, by allowing filtering. For example, when bisecting, you can ignore files by doing:
    ```bash
    git bisect skip $(git rev-list --grep irrelevant <good place> HEAD)
    ```

    ---

    Format of the commit message
    ----------------------------
    Proposal
    --------
    ### Message Format
    ```
    <type>(<scope>): <subject>
    <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 contains succinct description of the change. 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
    Subject line contains succinct description of the change.
    > Subject line may be prefixed for continuous integration purposes.
    > For example, [JIRA](https://bigbrassband.com/git-for-jira.html)
    > requires ticket in the beggining of commit message message:
    > "[LHJ-16] fix(compile): add unit tests for windows"
    #### Allowed `<type>`
    * feat
    @@ -105,48 +90,54 @@ Scope could be anything specifying place of the commit change. For example $loca
    * don't capitalize first letter
    * no dot (.) at the end

    ### Message body
    #### Allowed `<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.

    #### Message body
    * just as in <subject> use imperative, present tense: “change” not “changed” nor “changes”
    * includes motivation for the change and contrasts with previous behavior

    http://365git.tumblr.com/post/3308646748/writing-git-commit-messages
    http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

    ### Message footer
    #### Message footer

    #### Breaking changes
    ##### Breaking changes
    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.
    ```

    #### Referencing issues
    ##### Referencing issues
    Closed bugs should be listed on a separate line in the footer prefixed with "Closes" keyword like this:
    ```
    Closes #234
    @@ -157,13 +148,6 @@ or in case of multiple issues:
    Closes #123, #245, #992
    ```

    ### Meta information
    The end of subject-line may contain twitter-inspired markup to facilitate changelog generation and bissecting.

    #### Allowed:
    * `#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.

    Examples
    --------
    ```
    @@ -249,4 +233,24 @@ scope: {
    }
    The removed `inject` wasn't generaly useful for directives so there should be no code using it.
    ```
    ```

    Generating CHANGELOG.md
    -----------------------
    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:
    ```bash
    git log <last tag> HEAD --pretty=format:%s
    ```

    New features in this release
    ```bash
    git log <last release> HEAD --grep feat
    ```

    ---

    Thanks to @stephenparish for [the original text](https://gist.github.com/stephenparish/9941e89d80e2bc58a153)
  7. @abravalheri abravalheri revised this gist Mar 1, 2016. 1 changed file with 18 additions and 15 deletions.
    33 changes: 18 additions & 15 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,6 +1,6 @@
    Commit Message Conventions
    ==========================
    These rules are adopted from [the AngularJS commit conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/).
    Conventions borrowed from [the AngularJS commit conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/) and [Tim Pope article](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)

    * [Goals](#goals)
    * [Generating CHANGELOG.md](#generating-changelogmd)
    @@ -25,19 +25,18 @@ Goals

    Generating CHANGELOG.md
    -----------------------
    We use these three sections in changelog: new features, bug fixes, breaking changes.
    This list could be generated by script when doing a release. Along with links to related commits.
    Changleos may contain these 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:
    ```bash
    git log <last tag> HEAD --pretty=format:%s
    ```


    New features in this release
    ```bash
    git log <last release> HEAD --grep feature
    git log <last release> HEAD --grep feat
    ```

    ### Recognizing unimportant commits
    @@ -58,7 +57,6 @@ Look at these messages (taken from last few angular’s commits):
    * Replaced double line break with single when text is fetched from Google
    * Added support for properties in documentation


    All of these messages try to specify where is the change. But they don’t share any convention...

    Look at these messages:
    @@ -91,7 +89,7 @@ Any line of the commit message cannot be longer 100 characters! This allows the
    Subject line contains succinct description of the change.

    #### Allowed `<type>`
    * feat (feature)
    * feat
    * fix (bug fix)
    * docs (documentation)
    * style (formatting, missing semi colons, …)
    @@ -117,7 +115,6 @@ http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
    ### Message footer

    #### Breaking changes

    All breaking changes have to be mentioned in footer with the description of the change, justification and migration notes

    ```
    @@ -150,7 +147,6 @@ BREAKING CHANGE: isolate scope bindings definition has changed and
    ```

    #### Referencing issues

    Closed bugs should be listed on a separate line in the footer prefixed with "Closes" keyword like this:
    ```
    Closes #234
    @@ -161,12 +157,19 @@ or in case of multiple issues:
    Closes #123, #245, #992
    ```

    ### Meta information
    The end of subject-line may contain twitter-inspired markup to facilitate changelog generation and bissecting.

    #### Allowed:
    * `#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.

    Examples
    --------
    ```
    feat($browser): onUrlChange event (popstate/hashchange/polling)
    feat($browser): add onUrlChange event (popstate/hashchange/polling)
    Added new event to $browser:
    New $browser event:
    - forward popstate event if available
    - forward hashchange event if popstate not available
    - do polling when neither popstate nor hashchange available
    @@ -175,7 +178,7 @@ Breaks $browser.onHashChange, which was removed (use onUrlChange instead)
    ```

    ```
    fix($compile): couple of unit tests for IE9
    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
    @@ -186,7 +189,7 @@ Breaks foo.bar api, foo.baz should be used instead
    ```

    ```
    feat(directive): ng:disabled, ng:checked, ng:multiple, ng:readonly, ng:selected
    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.
    @@ -199,7 +202,7 @@ style($location): add couple of missing semi colons
    ```

    ```
    docs(guide): updated fixed docs from Google Docs
    docs(guide): update fixed docs from Google Docs
    Couple of typos fixed:
    - indentation
    @@ -211,7 +214,7 @@ Couple of typos fixed:
    ```
    feat($compile): simplify isolate scope bindings
    Changed the isolate scope binding options to:
    Change the isolate scope binding options to:
    - @attr - attribute binding (including interpolation)
    - =model - by-directional model binding
    - &expr - expression execution binding
  8. @stephenparish stephenparish revised this gist Jul 29, 2014. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -30,13 +30,13 @@ This list could be generated by script when doing a release. Along with links to
    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:
    ```
    ```bash
    git log <last tag> HEAD --pretty=format:%s
    ```


    New features in this release
    ```shell
    ```bash
    git log <last release> HEAD --grep feature
    ```

  9. @stephenparish stephenparish revised this gist Jul 29, 2014. 1 changed file with 3 additions and 2 deletions.
    5 changes: 3 additions & 2 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,5 +1,6 @@
    AngularJS Git Commit Message Conventions
    ========================================
    Commit Message Conventions
    ==========================
    These rules are adopted from [the AngularJS commit conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/).

    * [Goals](#goals)
    * [Generating CHANGELOG.md](#generating-changelogmd)
  10. @stephenparish stephenparish revised this gist Jul 29, 2014. 1 changed file with 3 additions and 1 deletion.
    4 changes: 3 additions & 1 deletion commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -9,6 +9,7 @@ AngularJS Git Commit Message Conventions
    * [Subject line](#subject-line)
    * [Allowed `<type>`](#allowed-type)
    * [Allowed `<scope>`](#allowed-scope)
    * [`<subject>` text](#subject-text)
    * [Message body](#message-body)
    * [Message footer](#message-footer)
    * [Breaking changes](#breaking-changes)
    @@ -96,7 +97,8 @@ Subject line contains succinct description of the change.
    * refactor
    * test (when adding missing tests)
    * chore (maintain)
    Allowed <scope>

    #### Allowed `<scope>`
    Scope could be anything specifying place of the commit change. For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc...

    #### `<subject>` text
  11. @stephenparish stephenparish revised this gist Jul 29, 2014. 1 changed file with 13 additions and 13 deletions.
    26 changes: 13 additions & 13 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,19 +1,19 @@
    AngularJS Git Commit Message Conventions
    ========================================

    * Goals
    * Generating CHANGELOG.md
    * Recognizing unimportant commits
    * Provide more information when browsing the history
    * Format of the commit message
    * Subject line
    * Allowed <type>
    * Allowed <scope>
    * Message body
    * Message footer
    * Breaking changes
    * Referencing issues
    * Examples
    * [Goals](#goals)
    * [Generating CHANGELOG.md](#generating-changelogmd)
    * [Recognizing unimportant commits](#recognizing-unimportant-commits)
    * [Provide more information when browsing the history](#provide-more-information-when-browsing-the-history)
    * [Format of the commit message](#format-of-the-commit-message)
    * [Subject line](#subject-line)
    * [Allowed `<type>`](#allowed-type)
    * [Allowed `<scope>`](#allowed-scope)
    * [Message body](#message-body)
    * [Message footer](#message-footer)
    * [Breaking changes](#breaking-changes)
    * [Referencing issues](#referencing-issues)
    * [Examples](#examples)

    Goals
    -----
  12. @stephenparish stephenparish revised this gist Jul 28, 2014. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -88,7 +88,7 @@ Any line of the commit message cannot be longer 100 characters! This allows the
    ### Subject line
    Subject line contains succinct description of the change.

    #### Allowed <type>
    #### Allowed `<type>`
    * feat (feature)
    * fix (bug fix)
    * docs (documentation)
    @@ -99,7 +99,7 @@ Subject line contains succinct description of the change.
    Allowed <scope>
    Scope could be anything specifying place of the commit change. For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc...

    #### <subject> text
    #### `<subject>` text
    * use imperative, present tense: “change” not “changed” nor “changes”
    * don't capitalize first letter
    * no dot (.) at the end
  13. @stephenparish stephenparish revised this gist Jul 28, 2014. 1 changed file with 3 additions and 1 deletion.
    4 changes: 3 additions & 1 deletion commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -28,7 +28,9 @@ This list could be generated by script when doing a release. Along with links to
    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`
    ```
    git log <last tag> HEAD --pretty=format:%s
    ```


    New features in this release
  14. @stephenparish stephenparish created this gist Jul 28, 2014.
    244 changes: 244 additions & 0 deletions commit.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,244 @@
    AngularJS Git Commit Message Conventions
    ========================================

    * Goals
    * Generating CHANGELOG.md
    * Recognizing unimportant commits
    * Provide more information when browsing the history
    * Format of the commit message
    * Subject line
    * Allowed <type>
    * Allowed <scope>
    * Message body
    * Message footer
    * Breaking changes
    * Referencing issues
    * Examples

    Goals
    -----
    * allow generating CHANGELOG.md by script
    * allow ignoring commits by git bisect (not important commits like formatting)
    * provide better information when browsing the history

    Generating CHANGELOG.md
    -----------------------
    We use these three sections in changelog: 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
    ```shell
    git log <last release> HEAD --grep feature
    ```

    ### Recognizing unimportant commits
    These are formatting changes (adding/removing spaces/empty lines, indentation), missing semi colons, comments. So when you are looking for some change, you can ignore these commits - no logic change inside this commit.

    When bisecting, you can ignore these by:
    ```bash
    git bisect skip $(git rev-list --grep irrelevant <good place> HEAD)
    ```

    ### Provide more information when browsing the history
    This would add kinda “context” information.
    Look at these messages (taken from last few angular’s commits):
    * Fix small typo in docs widget (tutorial instructions)
    * Fix test for scenario.Application - should remove old iframe
    * docs - various doc fixes
    * docs - stripping extra new lines
    * Replaced double line break with single when text is fetched from Google
    * Added support for properties in documentation


    All of these messages try to specify where is the change. But they don’t share any convention...

    Look at these messages:
    * fix comment stripping
    * fixing broken links
    * Bit of refactoring
    * Check whether links do exist and throw exception
    * Fix sitemap include (to work on case sensitive linux)

    Are you able to guess what’s inside ? These messages miss place specification...
    So maybe something like parts of the code: docs, docs-parser, compiler, scenario-runner, …

    I know, you can find this information by checking which files had been changed, but that’s slow. And when looking in git history I can see all of us tries to specify the place, only missing the convention.

    ---

    Format of the commit message
    ----------------------------
    ```
    <type>(<scope>): <subject>
    <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
    Subject line contains succinct description of the change.

    #### Allowed <type>
    * feat (feature)
    * fix (bug fix)
    * docs (documentation)
    * style (formatting, missing semi colons, …)
    * refactor
    * test (when adding missing tests)
    * chore (maintain)
    Allowed <scope>
    Scope could be anything specifying place of the commit change. For example $location, $browser, $compile, $rootScope, ngHref, ngClick, ngView, etc...

    #### <subject> text
    * use imperative, present tense: “change” not “changed” nor “changes”
    * don't capitalize first letter
    * no dot (.) at the end

    ### Message body
    * just as in <subject> use imperative, present tense: “change” not “changed” nor “changes”
    * includes motivation for the change and contrasts with previous behavior

    http://365git.tumblr.com/post/3308646748/writing-git-commit-messages
    http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

    ### Message footer

    #### Breaking changes

    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.
    ```

    #### Referencing issues

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

    Examples
    --------
    ```
    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)
    ```

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

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

    ```
    style($location): add couple of missing semi colons
    ```

    ```
    docs(guide): updated fixed docs from Google Docs
    Couple of typos fixed:
    - indentation
    - batchLogbatchLog -> batchLog
    - start periodic checking
    - missing brace
    ```

    ```
    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.
    ```