Proofreading and additions to upgrading guide (#37)

* add a lot to upgrading

* proofreading edits and missing links

* fix anchor link

* remove configurations from the TOC

* linting

* move stylesheets and minifying out of legacy folder

* use headers for watchman info

* line break on periods

* fix broken links

Author: Jen Weber

guides/advanced-use/configurations.md

@@ -1 +1,63 @@
 <!-- Should cover at least minification and fingerprinting -->
+<!-- Needs intro! -->
+
+### Minifying
+
+Compiled css-files are minified by `broccoli-clean-css` or `broccoli-csso`,
+if it is installed locally. You can pass minifer-specific options to them using
+the `minifyCSS:options` object in your ember-cli-build. Minification is enabled by
+default in the production-env and can be disabled using the `minifyCSS:enabled`
+switch.
+
+Similarly, the js-files are minified with `broccoli-uglify-js` in the
+production-env by default. You can pass custom options to the minifier via the
+`minifyJS:options` object in your ember-cli-build. To enable or disable JS minification
+you may supply a boolean value for `minifyJS:enabled`.
+
+For example, to disable minifying of CSS and JS, add in `ember-cli-build.js`:
+
+```js
+// ember-cli-build.js
+const EmberApp = require('ember-cli/lib/broccoli/ember-app');
+
+module.exports = function(defaults) {
+  let app = new EmberApp(defaults, {
+    minifyJS: {
+      enabled: false
+    },
+    minifyCSS: {
+      enabled: false
+    }
+  });
+
+  //...
+  return app.toTree();
+};
+```
+
+#### Exclude from minification
+
+Some files should be excluded from minification, such as copied-and-pasted third party scripts that are already minified.
+
+To exclude assets from `dist/assets` from being minified, one can pass options for
+[broccoli-uglify-sourcemap](https://github.com/ef4/broccoli-uglify-sourcemap) like so:
+
+```js
+// ember-cli-build.js
+const EmberApp = require('ember-cli/lib/broccoli/ember-app');
+
+module.exports = function(defaults) {
+  let app = new EmberApp(defaults, {
+    minifyJS: {
+      options: {
+        exclude: ["**/vendor.js"]
+      }
+    }
+  });
+
+  //...
+  return app.toTree();
+};
+```
+
+This would exclude the resulting `vendor.js` file from being minified.

guides/advanced-use/stylesheets.md

@@ -1 +1,124 @@
-<!-- Should cover similar topics as ember-cli.com -->
+<!-- Needs an intro section and editing -->
+
+Ember CLI supports plain CSS out of the box. You can add your css styles to
+`app/styles/app.css` and it will be served at `assets/application-name.css`.
+
+For example, to add bootstrap in your project you need to do the following:
+```bash
+bower install bootstrap --save
+```
+
+In `ember-cli-build.js` add the following:
+```js
+app.import('bower_components/bootstrap/dist/css/bootstrap.css');
+```
+it's going to tell [Broccoli](https://github.com/broccolijs/broccoli) that we want
+this file to be concatenated with our `vendor.css` file.
+
+To use a CSS preprocessor, you'll need to install the appropriate
+[Broccoli](https://github.com/broccolijs/broccoli) plugin. When using a
+preprocessor, Broccoli is configured to look for an `app.less`, `app.scss`, `app.sass`,
+or `app.styl` manifest file in `app/styles`. This manifest should import any
+additional stylesheets.
+
+All your preprocessed stylesheets will be compiled into one file and served at
+`assets/application-name.css`.
+
+If you would like to change this behavior, or compile to multiple output
+stylesheets, you can adjust the [Output Paths
+Configuration](#configuring-output-paths)
+
+#### CSS
+
+To use plain CSS with `app.css`:
+
+* Write your styles in `app.css` and/or organize your CSS into multiple
+  stylesheet files and import these files with `@import` from within `app.css`.
+* [CSS `@import`
+  statements](https://developer.mozilla.org/en-US/docs/Web/CSS/@import) (e.g.
+  `@import 'typography.css';`) must be valid CSS, meaning `@import` statements
+  *must* precede all other rules and so be placed at the *top* of `app.css`.
+
+To process your imports and replace them with the contents of their files,
+add in `ember-cli-build.js`:
+```js
+// ember-cli-build.js
+var EmberApp = require('ember-cli/lib/broccoli/ember-app');
+
+module.exports = function(defaults) {
+  var app = new EmberApp(defaults, {
+    minifyCSS: {
+      options: { processImport: true }
+    }
+  });
+
+  //...
+  return app.toTree();
+};
+```
+
+Which will cause the following to happen:
+
+* In the production build, the `@import` statements are replaced with the
+  contents of their files and the final minified, concatenated single CSS file
+  is built to `dist/assets/yourappname-FINGERPRINT_GOES_HERE.css`.
+* Any individual CSS files are also built and minified into `dist/assets/` in
+  case you need them as standalone stylesheets.
+* Relative pathing gets changed (how to customize?)
+
+Example `app.css` with valid `@import` usage:
+
+```css
+/* @imports must appear at top of stylesheet to be valid CSS */
+@import 'typography.css';
+@import 'forms.css';
+
+/* Any CSS rules must go *after* any @imports */
+.first-css-rule {
+  color: red;
+}
+...
+```
+
+#### CSS Preprocessors
+
+To use one of the following preprocessors, all you need to do is install the appropriate NPM module.
+The respective files will be picked up and processed automatically.
+
+#### LESS
+
+To enable [LESS](http://lesscss.org/), you'll need to add
+[ember-cli-less](https://github.com/gdub22/ember-cli-less) to
+your NPM modules.
+
+```bash
+ember install ember-cli-less
+```
+
+#### SCSS/SASS
+
+To enable [SCSS/SASS](http://sass-lang.com/), you'll need to
+install the [ember-cli-sass](https://github.com/aexmachina/ember-cli-sass) addon
+to your project *(defaults to .scss, .sass allowed via configuration)*.
+
+```bash
+ember install ember-cli-sass
+```
+
+You can configure your project to use .sass in your `ember-cli-build.js`:
+
+```js
+// ember-cli-build.js
+const EmberApp = require('ember-cli/lib/broccoli/ember-app');
+
+module.exports = function(defaults) {
+  let app = new EmberApp({
+    sassOptions: {
+      extension: 'sass'
+    }
+  });
+
+  //...
+  return app.toTree();
+};
+```

guides/api-documentation/index.md

@@ -1,6 +1,6 @@
 The API docs for Ember CLI are mainly for addon authors, advanced Ember app developers, and contributors to the CLI itself.
 
-## [https://ember-cli.com/api/](https://ember-cli.com/api/) 
+[https://ember-cli.com/api/](https://ember-cli.com/api/) 
 
 The docs are the main resource for information like build pipeline modifications, addon author APIs, advanced configurations, and more.
 

guides/basic-use/cli-commands.md

@@ -1,11 +1,11 @@
-In their day to day work, most Ember developers use only a small number of CLI commands.
-We'll cover them here, along with a quick tutorial of how to use the `--help` option.
+In their daily work, most Ember developers use only a small number of CLI commands.
+We'll cover the most common commands here, along with a quick tutorial of how to use the `--help` option. The help option reveals all available commands and options, beyond what this guide covers.
 
 ## Using the help command
 
-For any of the commands below, you can see all of the options available by using the `--help` flag.
+For any CLI commands, you can see all of the options available by using the `--help` flag.
 
-For example, `ember --help` will show a list of all available top level commands. Get more detailed help by adding `--help` to the end of any command, like how `ember generate --help` will show a full list of all the types of files you can create using the CLI.
+For example, `ember --help` will show a list of all available top level commands. `ember generate --help` will show a full list of all the types of files you can generate using the CLI.
 
 The help command is also the best way to see the aliased or shorthand versions of common commands and options. For example, here are some of the most frequently used abbreviations:
 
@@ -38,7 +38,7 @@ The help command is also the best way to see the aliased or shorthand versions o
 
 <!-- SCREENSHOT -->
 
-## Create an app
+## Create a new app
 
 ### Format:
 
@@ -76,7 +76,10 @@ To stop an Ember server, press `control-c`.
 
 `ember serve` takes all of the app's files and turns them into something that can be rendered in the browser. By default, view the app by visiting `http://localhost:4200`. It's a good idea to keep the server running as we work so that we know as soon as we've broken something. The CLI watches the project folders, and will rerender as files change.
 
-### Example
+If the local server will not start due to missing dependencies, use
+`npm install` or `yarn install` to get going again.
+
+### Example use
 
 By default, apps are served at port `4200`, but if you need to change it for some reason, you could visit your app at `http://localhost:3200` by using this command:
 
@@ -86,23 +89,24 @@ ember serve --port 3200
 
 ### Learn more
 
-<!-- link to quickstart in the guides -->
+- [Ember Quickstart Guide](https://guides.emberjs.com/release/getting-started/quick-start/#toc_create-a-new-application) for starting a local server
 
-## Generate app files
+## Generate more files
 
 ### Format
 
 ```bash
-ember generate <type of file> <the name to give it>
+ember generate <type-of-file> <name-of-your-choice>
 ```
 
 ### What it does
 
 `ember generate` creates new files within your app. For example, you can use it to create components, routes, services, models, and more. For a full list, type `ember generate --help`.
 
-The new files will contain the necessary boilerplate, they will go in the right place, and the CLI will make sure that file naming conventions are followed. For example, components must always have a dash in their names. Creating files by hand is not recommended because mistakes can lead to confusing error messages.
+The new files will contain the necessary boilerplate, they will go in the right place, and the CLI will make sure that file naming conventions are followed. For example, components must always have a dash in their names.
+To avoid mistakes that are hard to debug, always use the CLI to create files, instead of creating the files by hand.
 
-### Example
+### Example use
 
 This command will make a component named `packing-list`. There will be three files created in the app: `packing-list.hbs` which will define what it looks like, `packing-list.js` with JavaScript code to handle user interaction, and an integration test (aka rendering test) file called `packing-list-test.js`.
 
@@ -112,9 +116,9 @@ ember generate component packing-list
 
 ### Learn more
 
-<!-- link to custom blueprints -->
+- [Ember Quickstart Guide](https://guides.emberjs.com/release/getting-started/quick-start/#toc_define-a-route) for creating a route
 
-## Installing dependencies
+## Installing addons
 
 ### Format
 
@@ -124,23 +128,27 @@ ember install <addon-name>
 
 ### What it does
 
-`ember install` is used to install addons within your app. An addon is an npm package that was built for use in an Ember app. Most addons have a name that starts with `ember`. You can find a full list of addons at [EmberObserver.com](https://emberobserver.com). There are addon versions of many popular npm libraries, as well as packages that are unique to Ember. The majority are open source community addons.
+`ember install` is used to install addons within your app. An addon is an npm package that was built especially for use in an Ember app. Most addons have a name that starts with `ember`. You can find a full list of addons at [EmberObserver.com](https://emberobserver.com). There are addon versions of many popular npm libraries, as well as packages that are unique to Ember. The majority are open source community addons.
+By convention, most addons have `ember` in the name, but not all of them.
 
-To use npm packages directly, see <!-- LINK --> to learn about the options.
+To use non-addon npm packages directly, see [the Ember.js Guide](https://guides.emberjs.com/release/addons-and-dependencies/managing-dependencies/)
+to dependencies to learn about the options.
 
-### Example
+### Example use
 
-Here's an example of adding SASS support to your app using <!-- LINK TO CLI SASS -->. SASS is an alternative to writing plain CSS. This is a popular community-maintained addon.
+Here's an example of adding SASS support to your app using [ember-cli-sass](https://github.com/aexmachina/ember-cli-sass). SASS is an alternative to writing plain CSS. This is a popular community-maintained addon.
 
 ```bash
 ember install ember-cli-sass
 ```
 
 ### Learn more
 
-<!-- Link to options for plain npm packages -->
-<!-- Link to writing your own addon -->
-<!-- Link to writing your own wrapper -->
+- [Ember CLI Guide](../using-addons/) for using and choosing addons
+- [The Ember.js Guides](https://guides.emberjs.com/release/addons-and-dependencies/managing-dependencies/) section on Addons and Dependencies
+- [Writing addons](../../writing-addons/) to learn how to make your own addon
+
+<!-- Link to writing your own wrapper, once content is done -->
 
 ## Testing your app
 
@@ -152,9 +160,11 @@ ember test [options]
 
 ### What it does
 <!--alex disable failed-->
-`ember test` runs all of the tests found in the `tests` folder of the app. By default, it runs all the tests once and displays the results. We'll see things like syntax errors, linting problems, deprecations, and failed assertions in the command line output. By default, these tests are run in Headless Chrome. What headless means is, we won't see the visual output of the browser, but it's running them in a Chrome environment. This makes the test suite faster. To watch tests in the browser as they run, visit `http://localhost:4200/tests` while the local server is running.
+`ember test` runs all of the tests found in the `tests` folder of the app. By default, it runs all the tests once and displays the results. We'll see things like syntax errors, linting problems, deprecations, and failed assertions in the command line output. To instead watch tests in the browser as they run, visit `http://localhost:4200/tests` while the local server is running with `ember serve`.
+
+By default, these tests are run in Headless Chrome. What headless means is, we won't see the visual output of the browser, but it's running them in a Chrome environment. This makes the test suite faster. 
 
-### Example
+### Example use
 
 To make tests re-run as we change files, we could use the `--server` option:
 
@@ -163,6 +173,8 @@ ember test --server
 ```
 
 ### Learn more
+- [The Ember.js Guides about Testing](https://guides.emberjs.com/release/testing/)
+- [The Ember Super Rentals Tutorial](https://guides.emberjs.com/release/tutorial/ember-cli/) which shows step-by-step how to write tests and understand the results
 
 ## Building the app for deployment
 
@@ -174,13 +186,13 @@ ember build [options]
 
 ### What it does
 
-`ember build` takes all of your app files and turns them into a bundle that is minified and transpiled into browser-ready JavaScript code, styles, and html. The bundled files go into a directory called `dist`. This bundle is what can be deployed to a server. By default, it uses the `development` environment configuration.
+`ember build` takes all of your app files and turns them into a bundle that is minified and transpiled into browser-ready JavaScript code, styles, and html. The bundled files go into a directory called `dist`. This bundle is what can be deployed to a server. By default, the `build` command uses the `development` environment configuration.
 
 Although you can upload the built files to a server yourself, many Ember projects use a community addon called [ember-cli-deploy](https://github.com/ember-cli-deploy/ember-cli-deploy) to get their apps into production. `ember-cli-deploy` has a plugin system to make it easy to deploy to many cloud vendors. Search [EmberObserver for "deploy"](https://emberobserver.com/?query=deploy) to browse available options.
 
 Ember apps can be built with only three environments: development, production, and testing.
 
-### Example
+### Example use
 
 This command builds the app using the production configuration, so that means by default, it will use maximum minification for best app performance.
 
@@ -190,24 +202,7 @@ ember build --environment production
 
 ### Learn more
 
-<!-- what to link to here? something about ember-cli-build -->
-
-
-<!-- link to guides and maybe super rentals -->
-
-
-<!--
-## Table of Contents
-Basic use (explain options of each)
-    - using the "help" commmand
-    - ember new
-    - ember server
-    - ember generate
-    - ember test
-    - ember install (incl link to later section on shims for npm packages)
-    - feature flags & configurations
-    - Environmental variables
-    - File tree reference
-    - addons/dependencies
-    - Upgrading
--->
+- The [Ember.js Super Rentals Tutorial](https://guides.emberjs.com/release/tutorial/deploying/) has a section on deploying
+- Search community addons for deployment on [EmberObserver](https://emberobserver.com/?query=deploy)
+- Enable feature flags in different environments using the
+[environment config](https://guides.emberjs.com/release/configuring-ember/configuring-your-app/)

guides/basic-use/configurations.md

@@ -1,3 +1,5 @@
+<!-- This page is not yet in production. When it is ready, add it to pages.yml -->
+
 <!-- The bare minimum explanation of what to do with ember-cli-build.js -->
 
 <!--

guides/basic-use/deploying.md

@@ -132,7 +132,7 @@ The use of HTTPS certificates is best practice for web security and professional
 
 Plain old HTTP sites are likely to show your users security warnings and they are vulnerable to man-in-the-middle attacks. HTTPS certificates are available at no cost from many identity and hosting providers. However, even if you have an HTTPS certificate, you will still need a way to redirect any users who visit `http://your-ember-app.com`, for example.
 
-The following is a simple http-to-https redirect using [nginx](). Don't forget to include your ssl keys in your config.
+The following is a simple http-to-https redirect using [nginx](https://nginx.org/en/). Don't forget to include your ssl keys in your config.
 
 First, make a production build of your app. The results will be saved in the `dist` directory: