Merge pull request #1 from ember-learn/master

aklkv · web-flow · commit ecabac83e88d · 2018-10-03T23:02:58.000-07:00
bringing changes from base repo
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,17 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+
+[*]
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,18 @@
+---
+language: node_js
+node_js:
+  - 6
+
+sudo: false
+dist: trusty
+
+cache:
+  directories:
+    - $HOME/.npm
+
+before_install:
+  - npm config set spin false
+
+script:
+  - npm run lint:md
+  - npm test
diff --git a/README.md b/README.md
@@ -25,7 +25,7 @@ You will need the following things properly installed on your computer.
 To see what a local copy of the Guides markdown looks like:
 
 * Clone the [Ember CLI Guides](https://github.com/ember-learn/cli-guides-app) App repository
-* link the `ember-cli-guides-source` repository by running `npm link` inside this repository, then `npm link @ember-learn/cli-guides` in the guides-app
+* link the `cli-guides-source` repository by running `npm link` inside this repository, then `npm link @ember-learn/cli-guides` in the guides-app
 * `npm install` and `ember serve` in the guides app
 * Visit your app at [http://localhost:4200](http://localhost:4200).
 * Visit your tests at [http://localhost:4200/tests](http://localhost:4200/tests).
diff --git a/guides/advanced-use/asset-pipeline.md b/guides/advanced-use/asset-pipeline.md
@@ -1 +1 @@
-<!-- Cover very very basic Broccoli info. Link to Oli's tutorials. See the Ember Times Readers questions for a great writeup of what broccoli is -->
+<!-- Cover very very basic Broccoli info. Link to Oli's tutorials. See the Ember Times Readers questions for a great writeup of what broccoli is -->
diff --git a/guides/advanced-use/blueprints.md b/guides/advanced-use/blueprints.md
@@ -1 +1 @@
-<!-- cover what blueprints are and how to modify them. Can be ported from the existing site -->
+<!-- cover what blueprints are and how to modify them. Can be ported from the existing site -->
diff --git a/guides/advanced-use/configurations.md b/guides/advanced-use/configurations.md
@@ -1 +1 @@
-<!-- Should cover at least minification and fingerprinting -->
+<!-- Should cover at least minification and fingerprinting -->
diff --git a/guides/advanced-use/file-layout.md b/guides/advanced-use/file-layout.md
@@ -1 +1 @@
-<!-- A place to talk about the resolver (see ember-cli.com), module imports, and eventually, Module Unification when it becomes a thing -->
+<!-- A place to talk about the resolver (see ember-cli.com), module imports, and eventually, Module Unification when it becomes a thing -->
diff --git a/guides/advanced-use/stylesheets.md b/guides/advanced-use/stylesheets.md
@@ -1 +1 @@
-<!-- Should cover similar topics as ember-cli.com -->
+<!-- Should cover similar topics as ember-cli.com -->
diff --git a/guides/api-documentation/index.md b/guides/api-documentation/index.md
@@ -4,4 +4,4 @@ The API docs for Ember CLI are mainly for addon authors, advanced Ember app deve
 
 The docs are the main resource for information like build pipeline modifications, addon author APIs, advanced configurations, and more.
 
-The API documentation is built from the code comments in the main CLI codebase, [ember-cli on GitHub](https://github.com/ember-cli/ember-cli). If you spot an issue in the documentation, please open an issue or pull request on that repository. 
+The API documentation is built from the code comments in the main CLI codebase, [ember-cli on GitHub](https://github.com/ember-cli/ember-cli). If you spot an issue in the documentation, please open an issue or pull request on that repository.
diff --git a/guides/basic-use/configurations.md b/guides/basic-use/configurations.md
@@ -1 +1 @@
-<!-- The bare minimum explanation of what to do with ember-cli-build.js -->
+<!-- The bare minimum explanation of what to do with ember-cli-build.js -->
diff --git a/guides/basic-use/deploying.md b/guides/basic-use/deploying.md
@@ -1 +1 @@
-<!-- should show ember build, link to ember-cli-deploy, Guides tutorial -->
+<!-- should show ember build, link to ember-cli-deploy, Guides tutorial -->
diff --git a/guides/basic-use/index.md b/guides/basic-use/index.md
@@ -34,7 +34,8 @@ If Watchman is not installed, a notice is displayed when invoking various comman
 
 ### Installing for Windows
 
-<!-- copy over from ember-cli.com -->
+Windows Vista and newer Windows versions are fully supported, although there are steps you can take to improve your experience.
+You can find more information about this in our section on [Windows support](../reference/windows/)
 
 ## Getting help
 
diff --git a/guides/basic-use/upgrading.md b/guides/basic-use/upgrading.md
@@ -21,10 +21,10 @@ ember --version
 ## Upgrading an Ember app itself
 
 There are automated Ember CLI tools available to help upgrade Ember apps, including codemods that help with syntax changes. Visit
-[ember-cli-update](https://github.com/ember-cli/ember-cli-update for the latest instructions.
+[ember-cli-update](https://github.com/ember-cli/ember-cli-update) for the latest instructions.
 
 <!-- Needs a section that describes a common upgrade experience, explains deprecations, links to Deprecations site, and hints that upgrades to get new features or jump major versions require changes to the codebase. Common misconception is that you can just jump versions in package.json. Pull in info from https://ember-cli.com/user-guide/#upgrading  -->
 
 ## Upgrading Addon Dependencies
 
-<!-- very brief guidance on how to approach addons, and a note that sometimes deprecation warnings come from outdated addons rather than your app -->
+<!-- very brief guidance on how to approach addons, and a note that sometimes deprecation warnings come from outdated addons rather than your app -->
diff --git a/guides/basic-use/using-addons.md b/guides/basic-use/using-addons.md
@@ -38,4 +38,4 @@ Here are just a few examples of popular community-maintained addons unique to Em
 - [liquid-fire](https://www.emberobserver.com/addons/liquid-fire), for animating things like route transitions to provide a smooth, native-app-like experience.
 - and so many more!
 
-Open Source projects like these addons rely on community members helping out. Some addons are sponsored by companies, but many are maintained on 100% volunteer time. If something doesn't work the way you expect, could be better documented, has a bug, or could be added as a new feature, please speak up and pitch in!
+Open Source projects like these addons rely on community members helping out. Some addons are sponsored by companies, but many are maintained on 100% volunteer time. If something doesn't work the way you expect, could be better documented, has a bug, or could be added as a new feature, please speak up and pitch in!
diff --git a/guides/basic-use/using-npm-packages.md b/guides/basic-use/using-npm-packages.md
@@ -1,2 +1,2 @@
 <!--Help Wanted--> 
-<!--should cover ember-auto-import, importing from node modules, etc--> 
+<!--should cover ember-auto-import, importing from node modules, etc--> 
diff --git a/guides/reference/common-issues.md b/guides/reference/common-issues.md
@@ -1 +1 @@
-<!-- copy over from ember-cli.com -->
+<!-- copy over from ember-cli.com -->
diff --git a/guides/reference/dev-tools.md b/guides/reference/dev-tools.md
@@ -1 +1,148 @@
-<!-- Copy over code editor content -->
+<!-- Copy over code editor content -->
+
+### Visual Studio Code
+If you are using [VSCode](https://code.visualstudio.com/) with `ember-cli`, there's an [official
+extension pack](https://marketplace.visualstudio.com/items?itemName=emberjs.emberjs#overview) 
+maintained by the Ember Learning team that adds multiple ember plugins that can help in 
+Ember development. If you already have VSCode installed on your machine, you can 
+[click here](vscode:extension/emberjs.emberjs) to view this extension pack inside VSCode. Alternatively, you can 
+also search for `emberjs.emberjs` inside the [extensions view](https://code.visualstudio.com/docs/editor/extension-gallery).
+
+### Atom
+
+If you are using [Atom](https://atom.io) with `ember-cli`, there are some
+packages available specific to Ember development.
+
+`Atom -> Preferences -> Install`
+
+* [ember-cli-helper](https://atom.io/packages/ember-cli-helper) - ember-cli integration in Atom
+* [ember-tabs](https://atom.io/packages/ember-tabs) - Makes atom.io work better with Ember pods
+* [atom-ember-components](https://atom.io/packages/atom-ember-components) - See all controllers and components that are rendering your component. Currently only works with pods structure.
+
+### Emacs
+
+If you are using [Emacs](https://www.gnu.org/software/emacs/) with `ember-cli`,
+Emacs creates temporary backup, autosave, and lockfiles that interfere with
+broccoli watcher, so they need to either be moved out of the way or disabled.
+To do that, ensure your emacs configuration contains the following:
+
+```bash
+(setq backup-directory-alist `((".*" . ,temporary-file-directory)))
+(setq auto-save-file-name-transforms `((".*" ,temporary-file-directory t)))
+(setq create-lockfiles nil)
+```
+
+An [ember-mode](https://github.com/madnificent/ember-mode) package is also
+available. It has shortcuts for quickly navigating files in ember projects,
+running generators, and running build, serve, and test tasks. It also includes
+support for linking build errors to files and minibuffer notifications of
+`ember serve` status. It can be installed from [MELPA](http://melpa.org/). To
+use MELPA, ensure your configuration contains the following:
+
+```bash
+(require 'package)
+(add-to-list 'package-archives
+             '("melpa" . "http://melpa.org/packages/") t)
+(package-initialize)
+```
+
+Then ember-mode can be installed from the package menu at `M-x
+package-list-packages`. After it is installed, add a file named
+`.dir-locals.el` to the root of your ember projects with the contents:
+
+```bash
+((nil . ((mode . ember))))
+```
+
+to enable it inside those projects.
+
+
+### Sublime Text
+
+If you are using [Sublime Text](http://www.sublimetext.com) with `ember-cli`,
+by default it will try to index all files in your `tmp` directory for its
+GoToAnything functionality.  This will cause your computer to come to a
+screeching halt @ 90%+ CPU usage, and can significantly increase build times.
+Simply remove these directories from the folders Sublime Text watches:
+
+`Sublime Text -> Preferences -> Settings - User`
+
+```js
+// folder_exclude_patterns and file_exclude_patterns control which files
+// are listed in folders on the side bar. These can also be set on a per-
+// project basis.
+"folder_exclude_patterns": [".svn", ".git", ".hg", "CVS", "tmp/class-*", "tmp/es_*", "tmp/jshinter*", "tmp/replace_*", "tmp/static_compiler*", "tmp/template_compiler*", "tmp/tree_merger*", "tmp/coffee_script*", "tmp/concat-tmp*", "tmp/export_tree*", "tmp/sass_compiler*"]
+```
+
+### WebStorm
+If you are using [WebStorm](https://www.jetbrains.com/webstorm/) with
+`ember-cli`, you will need to modify your `.gitignore` file, enable
+`ECMAScript6` settings, and mark certain directories.
+
+First, add the following line to `.gitignore`:
+```bash
+.idea
+```
+
+Next, from the WebStorm menu:
+
+`File > Settings -> Languages & Frameworks -> JavaScript -> ECMAScript6`
+
+Click 'OK' to close the Settings modal window.
+
+Next, in Webstorm's Project window right-click on each of the following
+directories, go to 'Mark Directory As' and mark as indicated:
+
+Mark as `Excluded`:
+```bash
+/tmp
+/dist
+```
+
+Mark as `Resource Root`:
+```bash
+/
+/bower_components
+/bower_components/ember-qunit/lib
+/public
+```
+
+Mark as `Test Sources Root`:
+```bash
+/tests
+```
+
+### Intellij-emberjs
+
+[This plugin](https://github.com/Turbo87/intellij-emberjs) provides excellent
+Ember.js support for all JetBrains IDEs that support JavaScript, including
+WebStorm.
+
+In order to install it, go to:
+
+`File | Settings... | Plugins | Browse repositories...`
+
+Search for `Ember.js` and click the Install button.
+
+### Vim
+
+If you are using [Vim](http://www.vim.org/) with `ember-cli`, Vim creates
+temporary backups and autosaves which interfere with broccoli, so they need to
+either be moved out of the way or disabled. To do that, ensure your .vimrc
+contains the following:
+
+```bash
+set backupdir=~/.vim/backup//
+set directory=~/.vim/swap//
+set undodir=~/.vim/undo//
+```
+
+And make sure to create the directories: 
+```bash
+mkdir -p ~/.vim/backup; mkdir -p ~/.vim/swap; mkdir -p ~/.vim/undo
+```
+
+Some useful Vim plugins for working with Ember.js:
+
+- [ember_tools](https://github.com/AndrewRadev/ember_tools.vim) - Provides various tools for navigation and code reformatting, similar to rails.vim for Rails.
+- [projectionist](https://github.com/tpope/vim-projectionist) - Powerful project navigation, provided you write your own code projections. Here's [an example](https://gist.github.com/AndrewRadev/3524ee46bca8ab349329)
diff --git a/guides/reference/faq.md b/guides/reference/faq.md
@@ -1 +1 @@
-<!-- Do I need to use the CLI, why broccoli instead of webpack, node version compatibility? -->
+<!-- Do I need to use the CLI, why broccoli instead of webpack, node version compatibility? -->
diff --git a/guides/reference/index.md b/guides/reference/index.md
@@ -1 +1 @@
-<!-- Brief description of what goes in the reference section. Mostly edge case stuff -->
+<!-- Brief description of what goes in the reference section. Mostly edge case stuff -->
diff --git a/guides/reference/windows.md b/guides/reference/windows.md
@@ -1 +1,83 @@
-<!-- Port over info from existing site -->
+Windows Vista and newer Windows versions are fully supported.
+
+To get started ensure the following dependencies are installed:
+
+* Node.js - [https://nodejs.org/en/](https://nodejs.org/en/)
+* Git - [https://git-scm.com/](https://git-scm.com/)
+* Chrome - [https://www.google.com/chrome/](https://www.google.com/chrome/)
+
+### Performance
+
+Although supported, Windows performance, at least by default, isn't as good as
+on Linux or MacOS. On a positive note, this story continues to improve. Both
+Microsoft, and the Ember CLI team continue to work on improving these developer
+ergonomics.
+
+#### What causes the build slowdown?
+
+The two primary reasons are:
+
+* Lack of enabled-by-default symlinks
+* Generally slower FS operations on NTFS
+
+#### For the best possible Windows experience
+
+* Use Windows Subsystem Linux [Installation
+  Guide](https://msdn.microsoft.com/en-us/commandline/wsl/install_guide)
+
+#### Improving your Windows experience
+
+Ensure Search and Defender ignore your project's `tmp` directory:
+
+```bash
+npm install -g ember-cli-windows
+```
+
+Then, to start the automatic configuration, run:
+
+```bash
+ember-cli-windows
+```
+
+*Make sure you use an elevated PowerShell.* <!-- Needs Instructions -->
+If there was an error, try executing Set-ExecutionPolicy Unrestricted -scope Process first.
+
+[Read more about this from the Microsoft DX Open Source team](http://felixrieseberg.com/improved-ember-cli-performance-with-windows/)
+
+### Enabling symlinks
+
+To create symlinks the account running Ember CLI must have the
+`SeCreateSymbolicLinkPrivilege`. Users in the Administrators group have this
+permission already. However, if UAC (User Access Control) is enabled, users in
+the Administrators group must run their shell using Run As Administrator
+because UAC strips away certain permissions from the Administrators +group,
+including `SeCreateSymbolicLinkPrivilege`.
+
+![Run As Administrator]({{ site.url }}/assets/images/common-issues/run-as-admin.png)
+
+If the user account is not part of the Administrators group you will need to
+add the `SeCreateSymbolicLinkPrivilege` to allow the creation of symlinks. To
+do this open the `Local Security Policy` by typing Local Security Policy in the
+Windows `Run` Box.
+
+Under `Local Policies` -> `User Rights Assignment` find the `Create symbolic
+links` policy and double click it to add a new user or group. Once your user or
+group has been added, your user should be able to create symlinks. Keep in mind
+if your user is part of the Administrators group and UAC is enabled you will
+still need to start your shell using `Run as Administrator`.
+
+![Enabling Symlinks]({{ site.url }}/assets/images/common-issues/enabling-symlinks.png)
+
+### Issues With npm: `EEXISTS`, Path too Long, etc
+
+There were always two major issues with running Node.js on Windows: first and
+foremost, the operating system maintains a maximum length for path names, which
+clashes with Node's traditional way of nesting modules in `node_modules`. The
+second issue was a bit more subtle: The npm installer had a set of steps it
+executed for each package and it would immediately start executing them as soon
+as it decided to act on a package resulting in hard-to-debug race conditions.
+
+`npm` 3 is a nearly complete rewrite of `npm`, fixing both issues. Windows users of
+Ember Cli might want to make the switch to `npm` 3 to benefit from its
+flat module installation (solving most issues involving long path names) as well
+as its multi-stage installer.
diff --git a/guides/writing-addons/dependencies.md b/guides/writing-addons/dependencies.md
@@ -1 +1 @@
-<!-- Should cover where to put dependencies in package.json, how to export specific assets -->
+<!-- Should cover where to put dependencies in package.json, how to export specific assets -->
diff --git a/guides/writing-addons/deploying.md b/guides/writing-addons/deploying.md
@@ -1 +1 @@
-<!-- This section should at least give people some clues about how to do a local production build, try it out locally, and then link to resources on publishing to npm -->
+<!-- This section should at least give people some clues about how to do a local production build, try it out locally, and then link to resources on publishing to npm -->
diff --git a/guides/writing-addons/documenting.md b/guides/writing-addons/documenting.md
@@ -1 +1 @@
-<!-- Should mention that many authors use the dummy app for their documentation. Should link to ember-cli-addon-docs, with clear indication of its status as a community project -->
+<!-- Should mention that many authors use the dummy app for their documentation. Should link to ember-cli-addon-docs, with clear indication of its status as a community project -->
diff --git a/guides/writing-addons/index.md b/guides/writing-addons/index.md
@@ -42,4 +42,4 @@ If we want other people to be able to use our addon, we need to specify a name,
 
 #### `config/ember-try.js`
 
-This is a place to configure which versions of Ember that the test suite should check for compatibility. See the [ember-try](https://github.com/ember-cli/ember-try) repository on GitHub for more information.
+This is a place to configure which versions of Ember that the test suite should check for compatibility. See the [ember-try](https://github.com/ember-cli/ember-try) repository on GitHub for more information.
diff --git a/guides/writing-addons/testing.md b/guides/writing-addons/testing.md
@@ -1 +1 @@
-<!-- Should cover ember-try, tests, and using the dummy app in testing. See ember-styleguide and popular addons for inspiration -->
+<!-- Should cover ember-try, tests, and using the dummy app in testing. See ember-styleguide and popular addons for inspiration -->
diff --git a/guides/writing-addons/tutorial.md b/guides/writing-addons/tutorial.md
@@ -290,4 +290,4 @@ Lastly, be sure to provide a few notes about how others can contribute to the pr
 
 ## Advanced addon configuration
 
-<!-- Help wanted! -->
+<!-- Help wanted! -->
diff --git a/guides/writing-addons/wrappers.md b/guides/writing-addons/wrappers.md
@@ -1 +1 @@
-<!-- Supplemental information to help someone write an Ember wrapper. Do not repeat content from the tutorial. -->
+<!-- Supplemental information to help someone write an Ember wrapper. Do not repeat content from the tutorial. -->
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-<!-- Cover very very basic Broccoli info. Link to Oli's tutorials. See the Ember Times Readers questions for a great writeup of what broccoli is -->`
	`1`	`+<!-- Cover very very basic Broccoli info. Link to Oli's tutorials. See the Ember Times Readers questions for a great writeup of what broccoli is -->`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-<!-- cover what blueprints are and how to modify them. Can be ported from the existing site -->`
	`1`	`+<!-- cover what blueprints are and how to modify them. Can be ported from the existing site -->`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-<!-- Should cover at least minification and fingerprinting -->`
	`1`	`+<!-- Should cover at least minification and fingerprinting -->`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-<!-- A place to talk about the resolver (see ember-cli.com), module imports, and eventually, Module Unification when it becomes a thing -->`
	`1`	`+<!-- A place to talk about the resolver (see ember-cli.com), module imports, and eventually, Module Unification when it becomes a thing -->`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-<!-- Should cover similar topics as ember-cli.com -->`
	`1`	`+<!-- Should cover similar topics as ember-cli.com -->`
Original file line number	Diff line number	Diff line change
`@@ -4,4 +4,4 @@ The API docs for Ember CLI are mainly for addon authors, advanced Ember app deve`
`4`	`4`
`5`	`5`	`The docs are the main resource for information like build pipeline modifications, addon author APIs, advanced configurations, and more.`
`6`	`6`
`7`		`-The API documentation is built from the code comments in the main CLI codebase, [ember-cli on GitHub](https://github.com/ember-cli/ember-cli). If you spot an issue in the documentation, please open an issue or pull request on that repository.`
	`7`	`+The API documentation is built from the code comments in the main CLI codebase, [ember-cli on GitHub](https://github.com/ember-cli/ember-cli). If you spot an issue in the documentation, please open an issue or pull request on that repository.`
Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-<!-- The bare minimum explanation of what to do with ember-cli-build.js -->`
	`1`	`+<!-- The bare minimum explanation of what to do with ember-cli-build.js -->`