Permalink
Browse files

docs(README.md): minor typo/wording/style improvements

Closes #384
1 parent 970dfae commit 9ca17826290e8c7159eb1a2b93494a30ad083a43 @gkalpak gkalpak committed Nov 21, 2016
Showing with 89 additions and 88 deletions.
  1. +89 −88 README.md
View
@@ -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,40 +11,39 @@ 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 <your-project-name>
```
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.
@@ -56,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
@@ -109,32 +106,34 @@ 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:
```
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:
```
@@ -145,32 +144,34 @@ npm run test-single-run
<a name="e2e-testing"></a>
### 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
@@ -180,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].
@@ -204,91 +205,91 @@ 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.
-
+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

0 comments on commit 9ca1782

Please sign in to comment.