-
Notifications
You must be signed in to change notification settings - Fork 139
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
BREAKING CHANGE: addMatchers syntax has changed Before: this.addMatchers({}); After: jasmine.Expectation.addMatchers({});
- Loading branch information
1 parent
e44b566
commit 14e5c82
Showing
11 changed files
with
263 additions
and
158 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
<a name="2.1.9"></a> | ||
## 2.1.9 (2014-04-06) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,148 @@ | ||
# Contributing to AngularFun | ||
|
||
|
||
## Table of Contents | ||
* [Issues](#issues) | ||
* [Pull Requests](#pull-requests) | ||
* [Commit Message Guidelines](#commit-message-guidelines) | ||
|
||
|
||
## Issues | ||
If you find a bug in the source code or a mistake in the documentation, you can help by submitting an [issue](https://github.com/CaryLandholt/AngularFun/issues) to the repository. Even better, you can submit a [Pull Request](#pull-requests) with a fix. | ||
|
||
Before you submit your issue, search the [archive](https://github.com/CaryLandholt/AngularFun/issues). Maybe your question was already answered. | ||
|
||
If your issue appears to be a bug, and hasn't been reported, open a new issue. Help to maximize the effort spent fixing issues and adding new features, by not reporting duplicate issues. Providing the following information will increase the chances of your issue being dealt with quickly: | ||
|
||
* **Overview of the issue** - if an error is being thrown a non-minified stack trace helps | ||
* **Motivation for or Use Case** - explain why this is a bug for you | ||
* **Version(s)** - is it a regression? | ||
* **Operating System** - is this a problem with only Windows? | ||
* **Reproduce the error** - provide a live example (using [Plunker](http://plnkr.co/edit) or [JSFiddle](http://jsfiddle.net/)) or an unambiguous set of steps. | ||
* **Related issues** - has a similar issue been reported before? | ||
* **Suggest a Fix** - if you can't fix the bug yourself, perhaps you can point to what might be causing the problem (line of code or commit) | ||
|
||
|
||
## Pull Requests | ||
Before you submit your pull request, consider the following guidelines: | ||
|
||
* Search for an open or closed [Pull Request](https://github.com/CaryLandholt/AngularFun/pulls) that relates to your submission. You don't want to duplicate effort. | ||
* Make your changes in a new git branch | ||
```bash | ||
$ git checkout -b my-fix-branch master | ||
``` | ||
* Create your patch, **including appropriate test cases** | ||
* In lieu of a formal styleguide, take care to maintain the existing coding style. Lint your code. | ||
* Run the full test suite, and ensure that all tests pass | ||
* Commit your changes using a descriptive commit message that follows the [Commit Message Guidelines](#commit-message-guidelines) and passes the commit message presubmit hook `validate-commit-msg.js`. Adherence to the [Commit Message Guidelines](#commit-message-guidelines) is required, because release notes are automatically generated from these messages. | ||
```bash | ||
$ git commit -a | ||
``` | ||
Note: the optional commit `-a` command line option will automatically "add" and "rm" edited files | ||
* Build your changes locally to ensure all the tests pass | ||
```bash | ||
$ grunt test | ||
``` | ||
* Push your branch | ||
```bash | ||
$ git push origin my-fix-branch | ||
``` | ||
* Send a pull request to `AngularFun:master` | ||
* If changes are suggested then: | ||
- Make the required updates | ||
- Re-run the test suite to ensure tests are still passing | ||
- Rebase your branch and force push to your repository (this will update your Pull Request): | ||
```bash | ||
$ git rebase master -i | ||
$ git push -f | ||
``` | ||
|
||
**Thank you for your contribution!** | ||
|
||
After your pull request is merged, you can safely delete your branch, and pull the changes from the main (upstream) repository: | ||
|
||
* Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows: | ||
```bash | ||
$ git push origin --delete my-fix-branch | ||
``` | ||
* Check out the master branch: | ||
```bash | ||
$ git checkout master -f | ||
``` | ||
* Delete the local branch: | ||
```bash | ||
$ git branch -D my-fix-branch | ||
``` | ||
* Update your master with the latest upstream version: | ||
```bash | ||
$ git pull --ff upstream master | ||
``` | ||
|
||
|
||
## Commit Message Guidelines | ||
There are 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, the git commit messages are used to generate the [Changelog](CHANGELOG.md). | ||
|
||
|
||
### 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](#type)**, a **[Scope](#scope)**, and a **[Subject](#subject)**: | ||
|
||
``` | ||
<type>(<scope>): <subject> | ||
<BLANK LINE> | ||
<body> | ||
<BLANK LINE> | ||
<footer> | ||
``` | ||
|
||
Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier to read using various git tools. | ||
|
||
#### Type | ||
Must be one of the following: | ||
|
||
* **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, 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 `build`, `ci`, etc... | ||
|
||
#### Subject | ||
The subject contains a succinct description of the change: | ||
|
||
* use the imperative, present tense: "change" not "changed" nor "changes" | ||
* don't capitalize the first letter | ||
* no dot (.) at the end | ||
|
||
#### Body | ||
Just as in the **[Subject](#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](#breaking-changes)** and is also the place to reference issues that this commit **[Closes](#referencing-issues)** | ||
|
||
##### Breaking Changes | ||
All breaking changes have to be mentioned in the footer with the description of the change, justification, and migration notes | ||
|
||
``` | ||
BREAKING CHANGE: gulp dev task has been deprecated | ||
gulp dev was superfluous | ||
Before: | ||
gulp dev | ||
After: | ||
gulp | ||
``` | ||
|
||
##### Referencing Issues | ||
Closed bugs should be listed on a separate line in the footer prefixed with the "Closes" keyword like: | ||
|
||
``` | ||
Closes #123 | ||
Closes #589 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,13 +1,6 @@ | ||
# AngularFun [![Build Status](https://secure.travis-ci.org/CaryLandholt/AngularFun.png)](http://travis-ci.org/CaryLandholt/AngularFun) | ||
*By [@CaryLandholt](https://twitter.com/carylandholt)* | ||
|
||
# AngularFun [![Version][version-image]][version-url] [![Build Status][build-image]][build-url] [![Dependency Status][dependencies-image]][dependencies-url] [![License][license-image]][license-url] | ||
> An [AngularJS](http://angularjs.org/) large application Reference Architecture | ||
[![Built with Grunt](https://cdn.gruntjs.com/builtwith.png)](http://gruntjs.com/) | ||
[![Dependency Status](https://david-dm.org/CaryLandholt/AngularFun.png)](https://david-dm.org/CaryLandholt/AngularFun) | ||
[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/CaryLandholt/angularfun/trend.png)](https://bitdeli.com/free "Bitdeli Badge") | ||
|
||
## About | ||
The intent is to provide a base for creating your own AngularJS applications with minimal boilerplate setup and ceremony. | ||
|
||
Simply follow the patterns and you'll get a complete development workflow, including: | ||
|
@@ -25,49 +18,78 @@ Simply follow the patterns and you'll get a complete development workflow, inclu | |
* a unit testing strategy | ||
* a server to run the application | ||
|
||
## Prerequisites | ||
* Must have [Git](http://git-scm.com/) installed | ||
* Must have [node.js (at least v0.8.1)](http://nodejs.org/) installed with npm (Node Package Manager) | ||
* Must have [Grunt](http://gruntjs.com/) node package installed globally. `npm install -g grunt-cli` | ||
* For Windows machines, you may need to install [karma](https://github.com/karma-runner/karma) globally. `npm install -g karma` | ||
|
||
## Install Angular Fun | ||
Enter the following commands in the terminal. | ||
## Table of Contents | ||
* [Installing](#installing) | ||
* [Compiling](#compiling) | ||
* [JS Love](#js-love) - prefer JavaScript over CoffeeScript? | ||
* [Running](#running) | ||
* [Making Changes](#making-changes) | ||
* [Testing](#testing) | ||
* [Commentary](#commentary) | ||
* [Contributing](#contributing) | ||
* [Changelog](#changelog) | ||
* [License](#license) | ||
|
||
1. `git clone git://github.com/CaryLandholt/AngularFun.git` | ||
2. `cd AngularFun` | ||
3. `npm install` | ||
4. `grunt bower:install` | ||
|
||
## Compile Angular Fun | ||
## Installing | ||
Before running, you must install and configure the following one-time dependencies: | ||
|
||
* [Git](http://git-scm.com/) | ||
* [Node.js](http://nodejs.org/) | ||
* [Grunt](http://gruntjs.com/) - use the terminal command below | ||
```bash | ||
$ npm install -g grunt-cli | ||
``` | ||
* [karma](https://github.com/karma-runner/karma) - For Windows machines, you may need to install [karma](https://github.com/karma-runner/karma) globally. Use the terminal command below | ||
```bash | ||
$ npm install -g karma | ||
``` | ||
|
||
Once the dependencies have been installed, enter the following commands in the terminal: | ||
```bash | ||
$ git clone [email protected]:CaryLandholt/AngularFun.git | ||
$ cd AngularFun | ||
$ npm install | ||
$ grunt bower:install | ||
``` | ||
|
||
|
||
## Compiling | ||
You have options. | ||
|
||
1. `grunt build` - will compile the app preserving individual files (when run, files will be loaded on-demand) | ||
2. `grunt` or `grunt dev` - same as `grunt` but will watch for file changes and recompile on-the-fly | ||
3. `grunt prod` - will compile using optimizations. This will create one JavaScript file and one CSS file to demonstrate the power of [r.js](http://requirejs.org/docs/optimization.html), the build optimization tool for RequireJS. And take a look at the index.html file. Yep - it's minified too. | ||
4. `grunt test` - will compile the app and run all unit tests | ||
|
||
|
||
## JS Love | ||
Some of you prefer working with plain old JavaScript. We've got ya covered. Simply run the following grunt task. | ||
`grunt jslove` - will transpile all of the CoffeeScript files to JavaScript and throw out the Coffee. | ||
|
||
## Run It | ||
|
||
## Running | ||
1. Compile the app using one of the above three options. `grunt` and `grunt dev` will run the web server and open the app in your default browser automatically. | ||
2. `grunt server` - will run the web server and open the app in your default browser. | ||
|
||
|
||
## Making Changes | ||
* `grunt` and `grunt dev` will watch for any .coffee, .less, .jade, or .html file changes. When changes are detected, the files will be linted, compiled, and ready for you to refresh the browser. | ||
|
||
## Running Tests | ||
|
||
## Testing | ||
`grunt test` - Runs unit tests using the [Karma](http://karma-runner.github.io/) Test Runner | ||
|
||
|
||
## Commentary | ||
AngularFun is a by-product of my learning AngularJS and became the reference architecture to my day job project, a very large internally and externally-facing application with extensive user interactions. | ||
|
||
I needed something that could support our Architecture Principles, including scale, stability, and maintenance. | ||
|
||
My background with using [RequireJS](http://requirejs.org/), see the [RequireJS screencasts](http://www.youtube.com/watch?v=VGlDR1QiV3A&list=PLCBD579A7ADB6313A) on my [YouTube channel](http://www.youtube.com/user/carylandholt), enabled me to get up and running with managing many individual files right away. RequireJS is a terrific dependency management technology. | ||
|
||
|
||
### Take 1 | ||
Here's an early example controller in CoffeeScript. | ||
|
||
|
@@ -90,6 +112,7 @@ There are a couple things going on here. RequireJS is loading controllers/contr | |
The controllers module was an early attempt at organizing AngularJS functionality into separate AngularJS modules (i.e. controllers, services, directives, filters, and responseInterceptors). | ||
This ultimately provided no benefit, so I got rid of them. They were just noise. | ||
|
||
|
||
### Take 2 | ||
Using only one AngularJS module and rewriting the above script without the functionality-specific AngularJS container modules we have: | ||
|
||
|
@@ -120,6 +143,7 @@ So the define function is making sure AngularJS is loaded and provides a handle | |
|
||
Even though there is a difference, there is some overlap in responsibility here. This can be observed with the mere fact that there is a gitHubService dependency referenced in the define function as well as the controller function. So the developer has to work in the RequireJS world and AngularJS world in the same file. | ||
|
||
|
||
### Take 3 | ||
|
||
So I decided to refactor the files and remove RequireJS completely, at least from the individual files. | ||
|
@@ -209,25 +233,35 @@ Here are the final index.html script references. Note that the condition will n | |
<% } %> | ||
``` | ||
|
||
|
||
### Take 4 | ||
Inspired by [tardyp](https://github.com/tardyp) and his [grunt-requiregen](https://github.com/tardyp/grunt-requiregen) plugin - what if we didn't have to do anything? | ||
|
||
So that's actually where we are. The shim file from [Take 3](#take-3) is built for you. | ||
|
||
Whew! | ||
|
||
### Give and Take | ||
After many iterations it now feels right. All [comments and questions](https://github.com/CaryLandholt/AngularFun/issues) and [Pull Requests](https://github.com/CaryLandholt/AngularFun/pulls) are always welcome. I respond to all. | ||
|
||
### Contributing | ||
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using grunt. | ||
## Contributing | ||
See [CONTRIBUTING.md](CONTRIBUTING.md) | ||
|
||
|
||
## Changelog | ||
See [CHANGELOG.md](CHANGELOG.md) | ||
|
||
|
||
## License | ||
See [LICENSE](LICENSE) | ||
|
||
|
||
[build-image]: http://img.shields.io/travis/CaryLandholt/AngularFun.svg?style=flat | ||
[build-url]: http://travis-ci.org/CaryLandholt/AngularFun | ||
|
||
[dependencies-image]: http://img.shields.io/gemnasium/CaryLandholt/AngularFun.svg?style=flat | ||
[dependencies-url]: https://gemnasium.com/CaryLandholt/AngularFun | ||
|
||
#### List of contributors | ||
* [Cary Landholt](https://github.com/CaryLandholt) | ||
* [David Bochenski](https://github.com/Bochenski) | ||
* [Jan Philipp](https://github.com/knalli) | ||
[license-image]: http://img.shields.io/badge/license-MIT-blue.svg?style=flat | ||
[license-url]: LICENSE | ||
|
||
## To-Do | ||
* Add many more unit tests :( | ||
* Add more documentation :( | ||
* Screencasts :) | ||
[version-image]: http://img.shields.io/github/tag/CaryLandholt/AngularFun.svg?style=flat | ||
[version-url]: https://github.com/CaryLandholt/AngularFun/tags |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.