chore(project): add conventional-changelog/standard-version support

marviq · Aug 4, 2016 · f5a2ce7 · f5a2ce7
1 parent 44521ac
commit f5a2ce7
Show file tree

Hide file tree

Showing 3 changed files with 232 additions and 1 deletion.
diff --git a/.gitmessage b/.gitmessage
@@ -0,0 +1,135 @@
+
+
+##  ============================================================================
+##  Commit Message Format for automated CHANGELOG generation.
+##  ----------------------------------------------------------------------------
+##
+##      <type>([<scope>]): <subject>
+##      [ <BLANK LINE> <body> ]
+##      [ <BLANK LINE> <footer> ]
+##
+##      type    ::  What type of change this commit contains;
+##      scope   ::  What item of code this commit is changing;
+##      subject ::  A short description of the change;
+##
+##      body    ::  A more in-depth description of the change;
+##
+##      footer  ::  References to issues that this change closes, as well as
+##                  Information about `BREAKING CHANGE`s.
+##
+##  <type>
+##  ----------------------------------------------------------------------------
+##
+##      Is recommended to be one of the below items. If the prefix is `feat`,
+##      `fix` or `perf`, it will appear in the CHANGELOG. However, if there is
+##      any `BREAKING CHANGE`, the commit will always appear in the CHANGELOG.
+##
+##        * 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;
+##
+##  <scope>
+##  ----------------------------------------------------------------------------
+##
+##      Could be anything specifying place of the commit change. For example
+##      `$location`, `$browser`, `$compile`, `$rootScope`, `ngHref`, `ngClick`,
+##      `ngView`, etc...
+##
+##  <subject>
+##  ----------------------------------------------------------------------------
+##
+##      A succinct description of the change:
+##
+##        * Use the imperative, present tense: "change" not "changed" nor
+##          "changes";
+##        * Don't capitalize first letter;
+##        * No dot (.) at the end;
+##
+##  <body>
+##  ----------------------------------------------------------------------------
+##
+##      Just as in the <subject>, use the imperative, present tense: "change"
+##      not "changed" nor "changes".
+##
+##      The body should include the motivation for the change and contrast this
+##      with previous behavior.
+##
+##  <footer>
+##  ----------------------------------------------------------------------------
+##
+##      The footer should contain any information about breaking changes
+##      and is also the place to reference GitHub issues that this commit
+##      Closes.
+##
+##      Breaking changes should start with the word `BREAKING CHANGE:` with a
+##      space or two newlines. The rest of the commit message is then used for
+##      this.
+##
+##  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
+##  ----------------------------------------------------------------------------
+##
+##  Appears under "Features" header, pencil subheader:
+##
+##      feat(pencil): add 'graphiteWidth' option
+##
+##
+##  Appears under "Bug Fixes" header, graphite subheader, with a link to
+##  issue #28:
+##
+##      fix(graphite): stop graphite breaking when width < 0.1
+##
+##      Closes #28
+##
+##
+##  Appears under "Performance Improvements" header, and under
+##  "Breaking Changes" with the breaking change explanation:
+##
+##      perf(pencil): remove graphiteWidth option
+##
+##      BREAKING CHANGE:
+##
+##      The graphiteWidth option has been removed. The default graphite width
+##      of 10mm is always used for performance reason.
+##
+##
+##  The following commit and commit `667ecc1` do not appear in the CHANGELOG if
+##  they are under the same release. If not, the revert commit appears under
+##  the "Reverts" header.
+##
+##      revert: feat(pencil): add 'graphiteWidth' option
+##
+##      This reverts commit 667ecc1654a317a13331b17617d973392f415f02.
+##
+##
+##  ============================================================================
+##  Original Specification:
+##  ----------------------------------------------------------------------------
+##
+##    * Adapted from:
+##
+##      https://github.com/bcoe/conventional-changelog-standard/blob/v1.2.1/convention.md#commit-message-format
+##      https://github.com/angular/angular.js/blob/v1.5.7/CONTRIBUTING.md#commit
+##
+##    * Latest:
+##
+##      https://github.com/bcoe/conventional-changelog-standard/blob/master/convention.md#commit-message-format
+##      https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit
+##
diff --git a/README.md b/README.md
@@ -196,6 +196,100 @@ The default grunt task also includes the `test` task. You may or may not want to
 Refer to the [releases on GitHub](https://github.com/marviq/generator-bat/releases) for a detailed log of changes.
 
 
+## Contributing
+
+### Prerequisites
+
+* [npm and node](https://nodejs.org/en/download/)
+* [git flow](https://github.com/nvie/gitflow/wiki/Installation)
+* [jq](https://stedolan.github.io/jq/download/)
+
+
+### Setup
+
+Clone this repository somewhere, switch to it, then:
+
+```bash
+$ git config commit.template ./.gitmessage
+$ git flow init -d
+$ npm install
+```
+
+This will:
+  * Setup [a helpful reminder](.gitmessage) of how to make [a good commit message](#commit-message-format-discipline).  If you adhere to this, then a detailed,
+    meaningful [CHANGELOG](CHANGELOG.md) can be constructed automatically.
+  * Setup the git flow [branching model](#branching-model) and checkout the `develop` branch.
+  * Install all required dependencies.
+
+
+### Commit
+
+#### Branching Model
+
+This project uses [`git flow`](https://github.com/nvie/gitflow#readme).  Here's a quick [cheat sheet](http://danielkummer.github.io/git-flow-cheatsheet/).
+
+
+#### Commit Message Format Discipline
+
+This project uses [`conventional-changelog/standard-version`](https://github.com/conventional-changelog/standard-version) for automatic versioning and
+[CHANGELOG](CHANGELOG.md) management.
+
+To make this work, *please* ensure that your commit messages adhere to the
+[Commit Message Format](https://github.com/bcoe/conventional-changelog-standard/blob/master/convention.md#commit-message-format).  Setting your `git config` to
+have the `commit.template` as referenced below will help you with [a detailed reminder](.gitmessage) of how to do this on every `git commit`.
+
+```bash
+$ git config commit.template ./.gitmessage
+```
+
+
+### Release
+
+* Determine what your next [semver](https://docs.npmjs.com/getting-started/semantic-versioning#semver-for-publishers) `<version>` should be:
+  ```bash
+  $ version="<version>"
+  ```
+
+* Create and checkout a `release/v<version>` branch off of `develop`:
+  ```bash
+  $ git flow release start "v${version}"
+  ```
+
+* Bump the package's `.version`, update the [CHANGELOG](./CHANGELOG.md), commit these, and tag the commit as `v<version>`:
+  ```bash
+  $ npm run release
+  ```
+
+* If all is well this new `version` **should** be identical to your intended `<version>`:
+  ```bash
+  $ jq ".version == \"${version}\"" package.json
+  ```
+
+  *If this is not the case*, then either your assumptions about what changed are wrong, or (at least) one of your commits did not adhere to the
+  [Commit Message Format Discipline](#commit-message-format-discipline); **Abort the release, and sort it out first.**
+
+* Merge `release/v<version>` back into both `develop` and `master`, checkout `develop` and delete `release/v<version>`:
+  ```bash
+  $ git flow release finish -n "v${version}"
+  ```
+
+  Note that contrary to vanilla `git flow`, the merge commit into `master` will *not* have been tagged (that's what the
+  [`-n`](https://github.com/nvie/gitflow/wiki/Command-Line-Arguments#git-flow-release-finish--fsumpkn-version) was for). This is done because `npm run release`
+  has already tagged its own commit.
+
+  I believe that in practice, this won't make a difference for the use of `git flow`; and ensuring it's done the other way round instead would render the use
+  of `conventional-changelog` impossible.
+
+
+### Publish
+
+```bash
+git checkout v<version>
+npm publish
+git checkout develop
+```
+
+
 ## License
 
 [BSD-3-Clause](LICENSE)
diff --git a/package.json b/package.json
@@ -17,7 +17,8 @@
   "description": "BAT, the Backbone Application Template; a Yeoman generator collection created by marviq",
   "devDependencies": {
     "coffeelint": "^1.15.7",
-    "jshint": "^2.9.2"
+    "jshint": "^2.9.2",
+    "standard-version": "^2.3.1"
   },
   "files": [
     "AUTHORS",
@@ -53,6 +54,7 @@
     "url": "git+https://github.com/marviq/generator-bat.git"
   },
   "scripts": {
+    "release": "standard-version",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "version": "0.1.27"