Merge pull request #4 from bguiz/feature/getting-started

bholloway · bholloway · commit a163f44acba5 · 2015-01-23T14:02:14.000+11:00
=BG= add getting started instructions &amp;&amp; more detailed installation instructions
diff --git a/about/intro.md b/about/intro.md
@@ -2,72 +2,54 @@
 
 Angularity is a philosophy of development.
 
-Our focus is maintaining uniformity of development across groups of corporate developers who hold varying experience levels.
+Our focus is maintaining uniformity of development across groups of developers who hold varying experience levels.
 
-Our contributors hold a collective vision of best-practice Angular-js development and have condensed this into a set of tools and resources known as **Angularity**.
+Our contributors hold a collective vision of best-practice AngularJS development and have condensed this into a set of tools and resources known as **Angularity**.
 
 ## Features
 
-Primarily Angularity is a javascript build tool build on [`node-js`](http://nodejs.org/). Its features include:
+Primarily Angularity is a [`node.js`](http://nodejs.org/) build tool. Its features include:
 
 * Single `npm global install` for all projects.
-
-* [`Ecmascript-6`](http://en.wikipedia.org/wiki/ECMAScript#ECMAScript_Harmony_.286th_Edition.29) syntax (using [`es6ify`](http://thlorenz.github.io/es6ify/)). Code import and ES-6 specific features.
-
+* [`ECMAScript 6`](http://en.wikipedia.org/wiki/ECMAScript#ECMAScript_Harmony_.286th_Edition.29) syntax (using [`es6ify`](http://thlorenz.github.io/es6ify/)), including code import and other ES6 specific features.
 * [`jsHint`](http://www.jshint.com/about/) linting.
-
 * [`SASS`](http://sass-lang.com/) 3.2 (using [`libsass`](http://libsass.org/)).
-
 * [`Bourbon`](http://bourbon.io/) mixin library for SASS.
-
 * [`Bower`](http://bower.io/) for web dependencies.
-
 * Bower or node packages for shared code.
-
 * Javascript unit testing (using [`Karma`](http://karma-runner.github.io/0.12/index.html) and [`Jasmine 2.0`](http://jasmine.github.io/2.0/introduction.html)).
-
-* Sourcemaps for javascript (from Ecmascript-6 through minification).
-
-* Sourcemaps for CSS.
-
+* Source maps for Javascript (from ECMAScript 6 through minification).
+* Source maps for CSS.
 * Release versioning *[experimental]*.
 
-At its heart, none of these features are specifically tied to [`Angular-js`](https://angularjs.org/). However much of the material you will find on this site is geared to Angular development.
+At its heart, none of these features are specifically tied to [`AngularJS`](https://angularjs.org/). However much of the material you will find on this site is geared to Angular development.
 
 ## Suitability
 
-### You should use *angularity* when...
+### You should use *Angularity* when...
 
 * You have several development teams and need uniformity of development.
-
-* You develop with [`Angular-js`](https://angularjs.org/) and are open to working with [`Ecmascript-6`](http://en.wikipedia.org/wiki/ECMAScript#ECMAScript_Harmony_.286th_Edition.29), especially ES-6 Classes.
-
+* You develop with [`AngularJS`](https://angularjs.org/) and are open to working with [`ECMAScript 6`](http://en.wikipedia.org/wiki/ECMAScript#ECMAScript_Harmony_.286th_Edition.29), especially ES6 Classes.
 * You use [`SASS`](http://sass-lang.com/), or are prepared to switch, and there are sufficient SASS mixins for you in the [`Bourbon`](http://bourbon.io/) library.
-
-* You intend to `minify` or obfuscate your javascript.
-
+* You intend to minify or obfuscate your Javascript.
 * You deploy to a [`Content Delivery Network (CDN)`](http://en.wikipedia.org/wiki/Content_delivery_network) and need to version your releases.
-
-* You your browser support list permits [`Ecmascript 5.1`](http://kangax.github.io/compat-table/es5/).
-
+* You your browser support list permits [`ECMAScript 5.1`](http://kangax.github.io/compat-table/es5/).
 * You would like your build tool to be an `npm global install`.
 
-### You should avoid *angularity* when...
-
-* You don't want to work with [`Ecmascript-6`](http://en.wikipedia.org/wiki/ECMAScript#ECMAScript_Harmony_.286th_Edition.29), are avoiding [`Traceur`](https://github.com/google/traceur-compiler) and its runtime, and can live without Object Orientated code.
+### You should avoid *Angularity* when...
 
+* You don't want to work with [`ECMAScript 6`](http://en.wikipedia.org/wiki/ECMAScript#ECMAScript_Harmony_.286th_Edition.29), are avoiding [`Traceur`](https://github.com/google/traceur-compiler) and its runtime, and can live without Object Orientated code.
 * You want to use a CSS preprocessor other than [`SASS`](http://sass-lang.com/).
-
 * You would like to use [`Compass`](http://compass-style.org/) with your SASS.
-
 * You need to support [`PhantomJS`](http://phantomjs.org/) 1.x, `Internet Exporer 8` or lower.
 
-### You should fork *angularity* when...
+### You should fork *Angularity* when...
 
 * You want different build steps to those provided.
-
 * You want features that are not on our roadmap.
 
-Angularity is about uniformity. Per-project customisation is very small. If you develop a wide variety of applications you may ultimately find a conventional build (with something like [`Gulp`](http://gulpjs.com/)) will work better for you.
+Angularity is about uniformity.
+Per-project customisation should be minimal.
+If you develop a wide variety of applications you may ultimately find a conventional build (with something like [`Gulp`](http://gulpjs.com/)) will work better for you.
 
-[Roadmap &#x27F6;](roadmap.md)
+[Roadmap &#x27F6;](roadmap.md)
diff --git a/about/roadmap.md b/about/roadmap.md
@@ -7,45 +7,32 @@ Regarding `documentation`.
 The following items are listed in priority order but will necessarily be completed before version 1.0.0 release of the build tool.
 
 * Getting started guide.
-
 * Troubleshooting guide.
-
 * Quick reference for development style, including comparison of ES5 and ES6 use cases.
-
 * Manual for the build tool, including how it works.
 
 ## Build tool
 
-Regarding `node-angularity`, the angularity build tool.
+Regarding `node-angularity`, the Angularity build tool.
 
 ### Version 1.0.0
 
-* Ecmascript-5 development using `common-js` syntax *[Under consideration]*.
- 
+* ECMAScript 5 development using `common-js` syntax *[Under consideration]*.
 * Per-project configuration of `Karma` browser list and other selected unit testing settings.
-
 * Refinement of release versioning, including per-project `CDN` settings.
-
 * Generation of an `index.aspx` page in the release bundle and potentially other hooks to easily deploy on .NET systems.
 
 ### Version 1.x.0
 
 * Build blocking on `js-hint` *[Under consideration]*.
-
 * Generation of API documentation using [`JSdoc`](https://github.com/jsdoc3/jsdoc).
-
 * Incremental compilation.
-
-* Basic or experiemental support for [`Protractor`](https://docs.angularjs.org/guide/e2e-testing) end-to-end testing with local server or [`SauceLabs`](https://saucelabs.com/).
-
+* Basic or experimental support for [`Protractor`](https://docs.angularjs.org/guide/e2e-testing) end-to-end testing with local server or [`SauceLabs`](https://saucelabs.com/).
 * Continuous Integration (`CI`) testing for the system itself *[Under consideration]*.
 
 ### Version 2.x.0
 
 * `Karma` testing with [`PhantomJS 2.0`](http://ariya.ofilabs.com/2014/07/towards-phantomjs-2.html).
-
 * Enhanced code-style enforcement using [`eslint (v0.10.0)`](https://github.com/eslint/eslint/wiki/Release-goals#v0100).
-
 * Full support for [`Protractor`](https://docs.angularjs.org/guide/e2e-testing) with private [`Grid2`](https://code.google.com/p/selenium/wiki/Grid2) solution.
-
-* Test console (HTML page) with real-time red/green indication for your unit tests *[under consideration]*.
+* Test console (HTML page) with real-time red/green indication for your unit tests *[under consideration]*.
diff --git a/getting-started/installation.md b/getting-started/installation.md
@@ -13,11 +13,11 @@ On **Windows** platform choose to **checkout Windows-style, commit Unit-style**
 [![](installation-git-1.png)]()
 [![](installation-git-2.png)]()
 
-## Install node
+## Install node.js
 
 [`http://nodejs.org/download/`](http://nodejs.org/download/)
 
-Ensure that you choose the correct binary for your system. Meaning that 64bit systems should choose the 64bit binary.
+Ensure that you choose the correct binary for your system. Meaning that 64 bit systems should choose the 64 bit binary.
 
 [![](installation-node.png)]()
 
@@ -30,28 +30,84 @@ to reboot. Once you can see node in the console `echo %PATH%` then you are ready
 
 Unless you just installed `node` you may be running npm older than **npm 2.0.0**. In that case it is worth updating.
 
-`npm install npm -g`.
+    npm install -g npm
 
 On windows you may have some difficulty and should follow the troubleshooting
 [instructions](https://github.com/npm/npm/wiki/Troubleshooting#upgrading-on-windows) from the outset.
 
 Be aware however that npm 2 has [**breaking changes**](http://blog.npmjs.org/post/98131109725/npm-2-0-0) for existing
 projects.
 
-## Install Bower
+## Installation
 
-Bower is a popular Frontend package manager that makes it easier to consume libraries for web development.
+You will need to install bower, and update npm.
 
-`npm install bower -g`
+    npm install -g bower
+    npm install -g npm
 
-See more info on the [Bower website](http://bower.io).
+Next, we will install angularity.
+Decide whether you wish to use the last stable release,
+the latest commit,
+and if you wish to contribute to the project,
+and follow the appropriate set of instructions below.
 
-## Install angularity
+###  Stable
 
-Angularity is a **global** install.
+The default installation is fairly straightforward.
+Installing `npm` simply updates it,
+and Angularity expects bower to be available globally.
 
-`npm install angularity -g`
+    npm install -g angularity
 
-You are now ready to start an angularity project.
+If you wish to install a particular release of angularity,
+you can install from github instead of the npm registry, like so:
 
-[Project Setup &#x27F6;](project-setup.md)
+    npm install -g angularity/node-angularity#0.0.18
+
+(replace `0.0.18` with the tag you wish to use)
+
+###  Latest
+
+For those who wish to live on the bleeding edge,
+you will need to symlink the global npm package to
+somewhere.
+
+Assuming `CODE` is a folder where you place your code checkouts,
+and `NODE` is a folder where NodeJs is installed
+
+    npm install -g angularity
+    cd ${CODE}
+    git clone git@github.com:angularity/node-angularity.git
+    mv node-angularity angularity
+    cd ${NODE}/lib/node_modules
+    mv angularity angularity.backup
+    ln -s ${CODE}/angularity angularity
+    cd ${CODE}/angularity
+    npm install
+
+###  Contributor
+
+If you wish to develop or contribute to the Angularity project,
+set up your git checkout to do so.
+
+Firstly, fork the project on github:
+[https://github.com/angularity/node-angularity/fork](https://github.com/angularity/node-angularity/fork)
+
+Then run these commands to clone your forked repository,
+and then link it from NodeJs' global folder.
+
+    npm install -g angularity
+    cd ${CODE}
+    git clone git@github.com:${GITHUB_USERNAME}/node-angularity.git
+    mv node-angularity angularity
+    cd ${NODE}/lib/node_modules
+    mv angularity angularity.backup
+    ln -s ${CODE}/angularity angularity
+    cd ${CODE}/angularity
+    git remote add upstream git@github.com:angularity/node-angularity.git
+    npm install
+
+Be sure to keep your fork in sync with the main repository
+before you start working on any patch.
+This [how to on Github](https://help.github.com/articles/syncing-a-fork/)
+is most helpful.
diff --git a/getting-started/project-setup.md b/getting-started/project-setup.md
@@ -1,3 +1,115 @@
 # Project setup
 
-Documentation will be forthcomming soon.
+## Running angularity
+
+Ensure that angularity has been installed correctly and is accessible from the command line:
+
+    which angularity
+    #should output the path where it is located
+
+If you wish to run angularity directly from the project folder,
+instead of from the command line after a global `npm` installation,
+you can do this instead:
+
+    cd angularity # where you have the project checked out
+    node bin/cli.js
+
+### `.angularity` config
+
+Upon your running angularity,
+you might encounter a warning that looks like this:
+
+```bash
+Error validating .angularity field(s): serverHttpPort consoleWidth
+```
+
+This is caused by a stale configuration file,
+you can choose to either edit the file to fix the values,
+or simply delete it and run angularity again:
+
+```bash
+rm ${HOME}/.angularity
+angularity
+```
+
+Upon which you should see the following output:
+
+```bash
+default settings are being written to a global configuration.
+To change your defaults edit your /home/YOUR_USER_NAME/.angularity file
+```
+
+## First run
+
+You will be given some options to pick from when you run Angularity.
+On the very first run, it is advisable to choose
+
+- `Install WebStorm Tools`.
+- Next pick `External Tools`.
+- Next pick `continue`
+
+This makes makes the Webstorm IDE aware of
+a number of tasks exposed by Angularity.
+Be sure to completely quit Webstorm and open it again,
+if it is already running.
+
+## Scaffold a new project
+
+Angularity will generate a scaffold for a new project
+which can be opened in the Webstorm IDE.
+To do this, run Angularity from the command line,
+where you wish to create a project in a subdirectory
+of the current working directory.
+
+```bash
+cd ${CODE}
+angularity
+```
+
+- Pick `Generate Project`
+- Next, pick `minimal-es6`, if you wish to develop using ES6 Javascript
+- Or, pick `minimal-es5`, if you wish to develop using ES5 Javascript
+- Next, type the name of your project
+- Next, choose the directory where the project will be created,
+  or accept the suggested one
+
+Now wait for a while while dependencies are installed,
+and then Angularity should finish generating the project,
+and fire up the Webstorm IDE with this project opened.
+
+## Webstorm tools
+
+### Tools --> Angularity
+
+This menu exposes certain tasks via a menu that you could run on the command line.
+It is simply a matter of convenience.
+
+- build
+- build nominify
+- watch
+- watch nominify
+- release
+- test
+
+### Debugging
+
+There is no difference in debugging an Angularity app,
+from debugging other Javascript applications.
+The only thing that you should be aware of,
+is that minification doesn't lend itself well to debugging,
+especially for AngularJs apps.
+That is what Angularity provides the
+`build nominify` and `watch nominify` tasks for.
+
+Here is a quick run down for those who have not used Webstorm debuigging before.
+
+In the top right hand corner, there should be a green bug icon.
+Click this (or use the `Shift+F9` keyboard shortcut),
+to run the project in debug mode.
+
+If this is the first time, you will need to install Jetbrains IDE Support plugin
+in your browser.
+Here is the [Chrome or Chromium plugin](https://chrome.google.com/webstore/detail/jetbrains-ide-support/hmhgeddbohgjknpmjagkdomcpobmllji)
+
+Once installed, the browser should open, and display the default app.
+
diff --git a/guide/composition.md b/guide/composition.md
diff --git a/index.md b/index.md
