diff --git a/README.md b/README.md index 5ac193a343..8d52ba48b7 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,7 @@ -# angular-seed — the seed for AngularJS apps +# `angular-seed` — the seed for AngularJS apps -This project is an application skeleton for a typical [AngularJS](http://angularjs.org/) web app. -You can use it to quickly bootstrap your angular webapp projects and dev environment for these -projects. +This project is an application skeleton for a typical [AngularJS][angularjs] web app. You can use it +to quickly bootstrap your angular webapp projects and dev environment for these projects. The seed contains a sample AngularJS application and is preconfigured to install the Angular framework and a bunch of development and testing tools for instant web development gratification. @@ -12,28 +11,27 @@ The seed app doesn't do much, just shows how to wire two controllers and views t ## Getting Started -To get you started you can simply clone the angular-seed repository and install the dependencies: +To get you started you can simply clone the `angular-seed` repository and install the dependencies: ### Prerequisites -You need git to clone the angular-seed repository. You can get git from -[http://git-scm.com/](http://git-scm.com/). +You need git to clone the `angular-seed` repository. You can get git from [here][git]. -We also use a number of node.js tools to initialize and test angular-seed. You must have node.js and -its package manager (npm) installed. You can get them from [http://nodejs.org/](http://nodejs.org/). +We also use a number of Node.js tools to initialize and test `angular-seed`. You must have Node.js +and its package manager (npm) installed. You can get them from [here][node]. -### Clone angular-seed +### Clone `angular-seed` -Clone the angular-seed repository using [git][git]: +Clone the `angular-seed` repository using git: ``` git clone https://github.com/angular/angular-seed.git cd angular-seed ``` -If you just want to start a new project without the angular-seed commit history then you can do: +If you just want to start a new project without the `angular-seed` commit history then you can do: -```bash +``` git clone --depth=1 https://github.com/angular/angular-seed.git ``` @@ -41,11 +39,14 @@ The `depth=1` tells git to only pull down one commit worth of historical data. ### Install Dependencies -We have two kinds of dependencies in this project: tools and angular framework code. The tools help +We have two kinds of dependencies in this project: tools and Angular framework code. The tools help us manage and test the application. -* We get the tools we depend upon via `npm`, the [node package manager][npm]. -* We get the angular code via `bower`, a [client-side code package manager][bower]. +* We get the tools we depend upon via `npm`, the [Node package manager][npm]. +* We get the Angular code via `bower`, a [client-side code package manager][bower]. +* In order to run the end-to-end tests, you will also need to have the + [Java Development Kit (JDK)][jdk] installed on your machine. Check out the section on + [end-to-end testing](#e2e-testing) for more info. We have preconfigured `npm` to automatically run `bower` so we can simply do: @@ -53,27 +54,26 @@ We have preconfigured `npm` to automatically run `bower` so we can simply do: npm install ``` -Behind the scenes this will also call `bower install`. You should find that you have two new -folders in your project. +Behind the scenes this will also call `bower install`. After that, you should find out that you have +two new folders in your project. * `node_modules` - contains the npm packages for the tools we need -* `app/bower_components` - contains the angular framework files +* `app/bower_components` - contains the Angular framework files *Note that the `bower_components` folder would normally be installed in the root folder but -angular-seed changes this location through the `.bowerrc` file. Putting it in the app folder makes -it easier to serve the files by a webserver.* +`angular-seed` changes this location through the `.bowerrc` file. Putting it in the `app` folder +makes it easier to serve the files by a web server.* ### Run the Application -We have preconfigured the project with a simple development web server. The simplest way to start +We have preconfigured the project with a simple development web server. The simplest way to start this server is: ``` npm start ``` -Now browse to the app at `http://localhost:8000/index.html`. - +Now browse to the app at [`localhost:8000/index.html`][local-app-url]. ## Directory Layout @@ -106,18 +106,19 @@ e2e-tests/ --> end-to-end tests scenarios.js --> end-to-end scenarios to be run by Protractor ``` + ## Testing -There are two kinds of tests in the angular-seed application: Unit tests and end-to-end tests. +There are two kinds of tests in the `angular-seed` application: Unit tests and end-to-end tests. ### Running Unit Tests -The angular-seed app comes preconfigured with unit tests. These are written in -[Jasmine][jasmine], which we run with the [Karma Test Runner][karma]. We provide a Karma -configuration file to run them. +The `angular-seed` app comes preconfigured with unit tests. These are written in [Jasmine][jasmine], +which we run with the [Karma][karma] test runner. We provide a Karma configuration file to run them. -* the configuration is found at `karma.conf.js` -* the unit tests are found next to the code they are testing and are named as `..._test.js`. +* The configuration is found at `karma.conf.js`. +* The unit tests are found next to the code they are testing and have an `_test.js` suffix (e.g. + `view1_test.js`). The easiest way to run the unit tests is to use the supplied npm script: @@ -125,13 +126,14 @@ The easiest way to run the unit tests is to use the supplied npm script: npm test ``` -This script will start the Karma test runner to execute the unit tests. Moreover, Karma will sit and -watch the source and test files for changes and then re-run the tests whenever any of them change. +This script will start the Karma test runner to execute the unit tests. Moreover, Karma will start +watching the source and test files for changes and then re-run the tests whenever any of them +changes. This is the recommended strategy; if your unit tests are being run every time you save a file then you receive instant feedback on any changes that break the expected code functionality. -You can also ask Karma to do a single run of the tests and then exit. This is useful if you want to -check that a particular version of the code is operating as expected. The project contains a +You can also ask Karma to do a single run of the tests and then exit. This is useful if you want to +check that a particular version of the code is operating as expected. The project contains a predefined script to do this: ``` @@ -139,34 +141,37 @@ npm run test-single-run ``` -### End to end testing + +### Running End-to-End Tests -The angular-seed app comes with end-to-end tests, again written in [Jasmine][jasmine]. These tests -are run with the [Protractor][protractor] End-to-End test runner. It uses native events and has +The `angular-seed` app comes with end-to-end tests, again written in [Jasmine][jasmine]. These tests +are run with the [Protractor][protractor] End-to-End test runner. It uses native events and has special features for Angular applications. -* the configuration is found at `e2e-tests/protractor-conf.js` -* the end-to-end tests are found in `e2e-tests/scenarios.js` +* The configuration is found at `e2e-tests/protractor-conf.js`. +* The end-to-end tests are found in `e2e-tests/scenarios.js`. Protractor simulates interaction with our web app and verifies that the application responds -correctly. Therefore, our web server needs to be serving up the application, so that Protractor -can interact with it. +correctly. Therefore, our web server needs to be serving up the application, so that Protractor can +interact with it. + +**Before starting Protractor, open a separate terminal window and run:** ``` npm start ``` -In addition, since Protractor is built upon WebDriver we need to install this. The angular-seed -project comes with a predefined script to do this: +In addition, since Protractor is built upon WebDriver, we need to ensure that it is installed and +up-to-date. The `angular-seed` project is configured to do this automatically before running the +end-to-end tests, so you don't need to worry about it. If you want to manually update the WebDriver, +you can run: ``` npm run update-webdriver ``` -This will download and install the latest version of the stand-alone WebDriver tool. - -Once you have ensured that the development web server hosting our application is up and running -and WebDriver is updated, you can run the end-to-end tests using the supplied npm script: +Once you have ensured that the development web server hosting our application is up and running, you +can run the end-to-end tests using the supplied npm script: ``` npm run protractor @@ -176,8 +181,8 @@ This script will execute the end-to-end tests against the application being host development server. **Note:** -Under the hood, Protractor uses the [Selenium Standalone Server][selenium], which in turn requires -the [Java Development Kit (JDK)][jdk] to be installed on your local machine. Check this by running +Under the hood, Protractor uses the [Selenium Standalone Server][selenium], which in turn requires +the [Java Development Kit (JDK)][jdk] to be installed on your local machine. Check this by running `java -version` from the command line. If JDK is not already installed, you can download it [here][jdk-download]. @@ -185,123 +190,106 @@ If JDK is not already installed, you can download it [here][jdk-download]. ## Updating Angular -Previously we recommended that you merge in changes to angular-seed into your own fork of the project. -Now that the angular framework library code and tools are acquired through package managers (npm and -bower) you can use these tools instead to update the dependencies. - -You can update the tool dependencies by running: - -``` -npm update -``` - -This will find the latest versions that match the version ranges specified in the `package.json` file. - -You can update the Angular dependencies by running: +Since the Angular framework library code and tools are acquired through package managers (npm and +bower) you can use these tools to easily update the dependencies. Simply run the preconfigured +script: ``` -bower update +npm run update-deps ``` -This will find the latest versions that match the version ranges specified in the `bower.json` file. +This will call `npm update` and `bower update`, which in turn will find and install the latest +versions that match the version ranges specified in the `package.json` and `bower.json` files +respectively. ## Loading Angular Asynchronously -The angular-seed project supports loading the framework and application scripts asynchronously. The -special `index-async.html` is designed to support this style of loading. For it to work you must -inject a piece of Angular JavaScript into the HTML page. The project has a predefined script to help -do this. +The `angular-seed` project supports loading the framework and application scripts asynchronously. +The special `index-async.html` is designed to support this style of loading. For it to work you must +inject a piece of Angular JavaScript into the HTML page. The project has a predefined script to help +do this: ``` npm run update-index-async ``` -This will copy the contents of the `angular-loader.js` library file into the `index-async.html` page. -You can run this every time you update the version of Angular that you are using. +This will copy the contents of the `angular-loader.js` library file into the `index-async.html` +page. You can run this every time you update the version of Angular that you are using. ## Serving the Application Files -While angular is client-side-only technology and it's possible to create angular webapps that -don't require a backend server at all, we recommend serving the project files using a local -webserver during development to avoid issues with security restrictions (sandbox) in browsers. The -sandbox implementation varies between browsers, but quite often prevents things like cookies, xhr, -etc to function properly when an html page is opened via `file://` scheme instead of `http://`. - +While Angular is client-side-only technology and it is possible to create Angular web apps that +do not require a backend server at all, we recommend serving the project files using a local +web server during development to avoid issues with security restrictions (sandbox) in browsers. The +sandbox implementation varies between browsers, but quite often prevents things like cookies, XHR, +etc to function properly when an HTML page is opened via the `file://` scheme instead of `http://`. ### Running the App during Development -The angular-seed project comes preconfigured with a local development webserver. It is a node.js -tool called [http-server][http-server]. You can start this webserver with `npm start` but you may choose to -install the tool globally: +The `angular-seed` project comes preconfigured with a local development web server. It is a Node.js +tool called [http-server][http-server]. You can start this web server with `npm start`, but you may +choose to install the tool globally: ``` sudo npm install -g http-server ``` -Then you can start your own development web server to serve static files from a folder by -running: +Then you can start your own development web server to serve static files from a folder by running: ``` http-server -a localhost -p 8000 ``` -Alternatively, you can choose to configure your own webserver, such as apache or nginx. Just +Alternatively, you can choose to configure your own web server, such as Apache or Nginx. Just configure your server to serve the files under the `app/` directory. - ### Running the App in Production This really depends on how complex your app is and the overall infrastructure of your system, but -the general rule is that all you need in production are all the files under the `app/` directory. +the general rule is that all you need in production are the files under the `app/` directory. Everything else should be omitted. -Angular apps are really just a bunch of static html, css and js files that just need to be hosted +Angular apps are really just a bunch of static HTML, CSS and JavaScript files that need to be hosted somewhere they can be accessed by browsers. -If your Angular app is talking to the backend server via xhr or other means, you need to figure -out what is the best way to host the static files to comply with the same origin policy if -applicable. Usually this is done by hosting the files by the backend server or through -reverse-proxying the backend server(s) and webserver(s). +If your Angular app is talking to the backend server via XHR or other means, you need to figure out +what is the best way to host the static files to comply with the same origin policy if applicable. +Usually this is done by hosting the files by the backend server or through reverse-proxying the +backend server(s) and web server(s). ## Continuous Integration ### Travis CI -[Travis CI][travis] is a continuous integration service, which can monitor GitHub for new commits -to your repository and execute scripts such as building the app or running tests. The angular-seed +[Travis CI][travis] is a continuous integration service, which can monitor GitHub for new commits to +your repository and execute scripts such as building the app or running tests. The `angular-seed` project contains a Travis configuration file, `.travis.yml`, which will cause Travis to run your tests when you push to GitHub. -You will need to enable the integration between Travis and GitHub. See the Travis website for more -instruction on how to do this. - -### CloudBees - -CloudBees have provided a CI/deployment setup: - - - - -If you run this, you will get a cloned version of this repo to start working on in a private git repo, -along with a CI service (in Jenkins) hosted that will run unit and end to end tests in both Firefox and Chrome. +You will need to enable the integration between Travis and GitHub. See the +[Travis website][travis-docs] for instructions on how to do this. ## Contact -For more information on AngularJS please check out http://angularjs.org/ +For more information on AngularJS please check out [angularjs.org][angularjs]. + -[bower]: http://bower.io -[git]: http://git-scm.com/ -[http-server]: https://github.com/nodeapps/http-server -[jasmine]: https://jasmine.github.io -[jdk]: https://en.wikipedia.org/wiki/Java_Development_Kit -[jdk-download]: http://www.oracle.com/technetwork/java/javase/downloads/index.html -[karma]: https://karma-runner.github.io -[node]: https://nodejs.org +[angularjs]: https://angularjs.org/ +[bower]: http://bower.io/ +[git]: https://git-scm.com/ +[http-server]: https://github.com/indexzero/http-server +[jasmine]: https://jasmine.github.io/ +[jdk]: https://wikipedia.org/wiki/Java_Development_Kit +[jdk-download]: http://www.oracle.com/technetwork/java/javase/downloads +[karma]: https://karma-runner.github.io/ +[local-app-url]: http://localhost:8000/index.html +[node]: https://nodejs.org/ [npm]: https://www.npmjs.org/ -[protractor]: https://github.com/angular/protractor +[protractor]: http://www.protractortest.org/ [selenium]: http://docs.seleniumhq.org/ [travis]: https://travis-ci.org/ +[travis-docs]: https://docs.travis-ci.com/user/getting-started diff --git a/package.json b/package.json index 48c7f62418..13dc019a9c 100644 --- a/package.json +++ b/package.json @@ -19,6 +19,9 @@ "scripts": { "postinstall": "bower install", + "update-deps": "npm update", + "postupdate-deps": "bower update", + "prestart": "npm install", "start": "http-server -a localhost -p 8000 -c-1 ./app",