socketstream/socketstream — pull request #428 by RomanMinkin (2014-01-28 22:54:13+00:00)
Title: [feature][grunt] Release and docs generator

Hi everyone,

Paul, i know there is a lot, but I was trying to automate as much processes as possible, even version releasing. Please take you time to figure it out.

**NOTE** branch `gh-pages` should be initialized before merging this PR!

Related issue: https://github.com/socketstream/socketstream/issues/412

I came up with **Release and Documentation generator** approach, based on `grunt`.

Detailed guidelines can be found in [CONTRIBUTING.md](https://github.com/RomanMinkin/socketstream/blob/feature/release-and-docs-generator/CONTRIBUTING.md)

## Short version:

- **Docs generation tasks**:
- **grunt build:docs** - build/re-build documentation
- **grunt watch:docs** - run docs web site locally the way process will watch for changes
- **grunt update:docs**

- **Release generation tasks**:
- **grunt release:start** - Increase patch version by 1, add suffix "SNAPSHOT" as `major.minor.(patch+1)-SNAPSHOT` and commit `package.json`
- **grunt release:prepare** - Run all the tests, generates `CHANGELOG.md` since laste release and and clean up version to just `major.minor.patch`
- **grunt release:complete** - Complete release by commiting `CHANGELOG.md` and package.json and adding version tag
- **grunt release:push** - Push to origin tags, master and gh-pages branches

- Example repository [https://github.com/RomanMinkin/ss-grunt-test](https://github.com/RomanMinkin/ss-grunt-test)
- Example commits [https://github.com/RomanMinkin/ss-grunt-test/commits/master](https://github.com/RomanMinkin/ss-grunt-test/commits/master)
- Example generated [CHANGELOG.md](https://github.com/RomanMinkin/ss-grunt-test/blob/master/CHANGELOG.md)

## Git Commit Guidelines

These rules are adopted from the [AngularJS commit conventions][commit-message-format].

We have very precise rules over how our git commit messages can be formatted. This leads to **more
readable messages** that are easy to follow when looking through the **project history**. But also,
we use the git commit messages to **generate the SocketStream change log**.

### Commit Message Format
Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
format that includes a **type**, a **scope** and a **subject**:

```
():

```

Examples:
```
feat(http): add `connect.compress()` middleware to the stack
```
```
docs(docs): typo fix
```
```
feat(websockets): add transport `engineio`

More efficient engine.io replced socket.io
```
```
fix(http): use blue ink instead of red ink

BREAKING CHANGE: `http` now uses blue ink instead of red.

To migrate, change your code from the following:

`http.start('blue')`

To:

`http.start('red')`
```

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.

### Type
Is recommended to be one of these (only **feat** and **fix** show up in the `CHANGELOG.md`):

* **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 or 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
The scope could be anything specifying place of the commit change. For example `cli`,
`http`, `publish`, `session`, `websocket`, `request` etc...

### Subject
The subject contains 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**.

A detailed explanation can be found in this [AngularJS commit conventions document][commit-message-format].

## Documentation generation

We use [ngdocs][ngdocs] module for generating documentation files.

We have two type of documentation:

* **API** - takes from directly from source code from comments to functions and objects defenition
* **Tutorials** - markdown files, located within `src/docs` and have `*.ngdoc` extension

To build/re-build documentation run:
```
grunt build:docs
```

To runt documentation web site locally the way process will watch for changes and re-building docs on the fly run:
```
grunt watch:docs
```

To update local `gh-page` branch by mergin from `master` run:
```
grunt update:docs
```

## Release
#### This guide is only for developers who allowed to perform releases

There are helpful `grunt` tasks for overall version releasing process:

1. First of all we need put a mark into **GIT History Tree** by increasing patch version by **1**, adding suffix "**SNAPSHOT**" (ex. "**0.3.15-SNAPSHOT**") and commiting `package.json`:
```
grunt release:start
```

2. Then we can perform regular commits with changes and pull requests

3. Once we decide to release a new version we need to **prepeare release** and run all the tests, generate `CHANGELOG.md` since the release start point (**mark commit from step 1**) and clean up version to just "**0.3.15**":
```
grunt release:prepare
```

4. If previouse step passed we need to **complete release** by commiting `CHANGELOG.md`, `package.json` and adding version tag:
```
grunt release:complete
```

5. Finnaly if all good, just push `tags` and both `master` and `gh-pages` branches to `origin`:
```
grunt release:push
```

## Conclusion

Benefits are:

1. Automation of docs generation process
2. Serving docs site on `gh-pages`
3. Unified **Commit Message Format** allows us to track and aggregate all the project changes in `CHANGELOG.md` automatically, example https://github.com/RomanMinkin/ss-grunt-test/blob/master/CHANGELOG.md
4. Release automation

[ngdocs]: https://github.com/idanush/ngdocs/wiki/API-Docs-Syntax
[commit-message-format]: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit#