ember-cli 4.0.0-beta.4 → 4.1.0

package/docs/architecture.md

@@ -1,316 +0,0 @@
-## Architecture
-
-![embercli architecture](./assets/architecture/Ember-CLI%20architecture.png)
-
-## Overview
-- **cli** parses args and calls the respective **command**
-- **command** calls a sequence of **tasks**
-- **tasks** do the actual work
-
-## The different components of ember-cli
-### cli()
-cli is a small function that gets everything going.
-
-Usage:
-``` JavaScript
-let cli = require('./cli');
-
-cli({
-  cliArgs: argv, // Required
-  inputStream: inputStream, // Required
-  outputStream: outputStream // Required
-})
-.then(...);
-```
-
-## UI
-In ember-cli we pass a `UI` instance around. Instead of calling
-`console.log` or writing things directly to `process.stdout` we access
-those through this wrapper. This makes our code testing friendly
-because it lets us simulate user input and it lets us verify if the output
-matches the expected output in tests.
-
-`ui.prompt(options).then(...)` can be used to get user input. It wraps the [inquirer node
-package](https://github.com/SBoudrias/Inquirer.js). See its documentation for
-usage instructions. Note: Navigation with
-arrow keys doesn't work properly on windows, only use prompt types with
-text input.
-
-`ui.write()` can be used to write something to the output stream. It's just
-`this.outputStream.write(data);` internally.
-
-`ui.inputStream`, `ui.outputStream` can be used for things that require a
-stream. Also nice for testing, e.g. simulating input.
-
-### Commands
-Located in `lib/commands/`. They get picked up by `requireAsHash()`
-automatically.
-
-The CLI constructs command instances with dependencies including ui,
-analytics, commands, project, etc. The plan is for these to eventually
-be constructed and wired up via a dependency injection container.
-
-The following file structure is expected (Demonstrated on the imaginary
-command `develop-ember-cli`):
-
-``` JavaScript
-// e.g. commands/develop-ember-cli.js
-
-let Command = require('../models/command');
-
-module.exports = Command.extend({
-  name: 'develop-ember-cli',    // Optional, default is the filename
-                                // Powered by some magic in getCallerFile()
-  key: 'developEmberCLI',       // Optional, default is the camelized name
-  description: 'Explanation',   // Optional
-  aliases: ['d', 'go-tomster'], // Optional, default is an empty array
-  works: 'everywhere',          // 'insideProject', 'outsideProject' or 'everywhere'
-                                // Optional, default is 'insideProject'
-
-  availableOptions: [           // Optional, default is an empty array
-    {
-      name: 'package-name',     // Required
-      key: 'packageName'        // Optional, default is the camelized name
-      description: '...',       // Optional
-      type: String,             // Required
-      default: 'ember-cli',     // Optional, default is undefined
-      required: false           // Optional, default is false
-    },
-    ...
-  ],
-
-  anonymousOptions: [
-    '<option-1>',
-    '<option-2>',
-    ...
-  ],
-
-  run(options) { // Required
-    // options === { packageName, ... }
-
-    // Run tasks and return a promise
-  },
-
-  printDetailedHelp() { // Optional
-    this.ui.write('Detailed help...');
-  }
-});
-```
-
-For more information on possible option types, see the [documentation for the
-nopt library](https://github.com/npm/nopt).
-
-Best practice is to use the `run()` function only to execute tasks. The real
-work should be done in these tasks, then.
-
-The promise returned by `run()` should either
-
-- resolve to `undefined`
-- reject with an `Error` instance if the error is unhandled
-- or reject with `undefined` if it was handled. In this case the command
-should log something via the `ui` first.
-
-`requireAsHash()` assembles from the files in `commands/` a hash that looks
-like this:
-
-``` JavaScript
-{
-  DevelopEmberCLI: require('commands/develop-ember-cli'),
-  ...
-}
-```
-
-#### Usage instructions formatting
-```
-ember serve <arg-option (Default: something)>
-  --port (Default: 4200) Description 1
-  --important-option (Required) Description 2
-```
-
-##### Formatting colors
-- white: `ember serve`
-- yellow: `<arg-option `, `>`
-- cyan: `--port`, `--important-option`
-- cyan: `(Default: something)`, `(Default: 4200)`
-- white: `Description 1`, `Description 2`
-- cyan: `(Required)`
-
-### Tasks
-Located in `lib/tasks`. They get picked up by `requireAsHash()` automatically.
-
-Tasks do the real work. They should also do only one thing: For example there
-are separate `bower-install` and `npm-install` tasks, not just one unified
-`install` task. And they should not call other tasks: For example
-`install-blueprint` shouldn't call `npm-install` directly. That's because the
-task sequence is determined by the command and thus should be declared there.
-
-The command constructs task instances with dependencies including ui,
-analytics, project, etc. The plan is for these to eventually
-be constructed and wired up via a dependency injection container.
-
-A task's `run` method has to return a promise which resolves or rejects
-depending on whether it ran through successfully or not.
-
-The promise of a task should either
-- fulfill to `undefined`
-- reject with an `Error` instance if the error is unhandled
-- or reject with `undefined` if it was handled. In this case the task should
-log something via the `ui` first.
-
-So, tasks don't have a return value per design.
-
-The file format of a task looks like this:
-``` JavaScript
-// tasks/npm-install.js
-
-let Task = require('../task');
-
-module.exports = Task.extend({
-  run(options) {
-    // return promise
-  }
-});
-```
-
-`requireAsHash()` assembles from the files in `tasks/` a hash that looks like this:
-``` JavaScript
-{
-  NpmInstall: require('tasks/npm-install'),
-  ...
-}
-```
-
-## Style guide
-- Everything async (except require)
-- Short files
-- Tests, tests, tests
-- Recommended line length <= 80 characters
-- No `console.log`, we've our own logging system
-- HTML and CSS: Double quotes, JavaScript: Single quotes
-- Naming conventions
-  - Dasherized (`some-thing`)
-    - file, folder and package names
-    - CSS classes
-    - HTML tags and attributes
-    - Model relationships
-  - Camel case (`someThing`)
-    - JavaScript (and JSON) properties and variables
-  - Pascal case (`SomeThing`)
-    - JavaScript class names
-  - Acronyms:
-    - Okay: `url`, `id`, `rootURL` (property) or `URL`, `URLParser` (class)
-    - Wrong: `Url`,`rootUrl`
-    - We stick with how it's done in ember -> `rootURL`
-- No comma separated assignment statements (`let cool = 123, supercool = 456;`)
-- Line break at the end of every file
-- Make constructors take an options object to avoid order-dependence
-
-This list only contains style decisions not already covered by ESLint (e.g.
-mandatory semicolons and other rules are omitted).
-
-### Indentation
-
-#### Multi-line return statement
-``` JavaScript
-// Correct
-return someFunction(
-    someArgument,
-    otherArgument
-  );
-
-// Wrong
-return someFunction(
-  someArgument,
-  otherArgument
-);
-```
-
-``` JavaScript
-// Correct
-return returnsAPromise()
-  .then(...)
-  .catch(...);
-
-// Wrong
-return retursAPromise().then(...)
-.catch(...);
-```
-
-### Custom errors
-Custom error classes should end with the suffix "Error".
-
-``` JavaScript
-function CustomError() {
-  this.stack = (new Error()).stack;
-}
-
-CustomError.prototype = Object.create(Error.prototype);
-CustomError.prototype.name = 'CustomError';
-```
-
-Also a `message` property should be set: Either in the constructor or as a property on `CustomError.prototype`.
-
-
-### Dependencies
-When requiring modules, we should be aware of their effect on startup
-time. If they introduce a noticeable penalty, and are not needed except
-for some task/command we should require them lazily. Obviously a few
-small modules won't make a difference, but eagerly requiring npm + bower
-and all of lodash will add a second to startup time.
-
-The following example eagerly requires npm, but only truly requires it
-when that task is invoked, not for `ember help` `ember version` or even
-`ember server`. This introduces a 200ms-300ms startup penalty.
-
-```js
-let npm = require('npm');
-
-module.exports = Task.extend({
-  run() {
-    npm.install() // or something
-  }
-});
-```
-
-If a dependency (like bower or npm) turns out to have high startup cost,
-we should require them lazily. This also allows us to inject
-alternative dependencies at construction time. Some future DI
-refactoring can likely automate this process.
-
-example:
-
-```js
-module.exports = Task.extend({
-  init() {
-    this.npm = this.npm || require('npm');
-  },
-  run() {
-    this.npm.install() // or something
-  }
-});
-```
-
-### Sync vs async
-Since [JavaScript uses an event loop](https://nodejs.org/about/), the use of
-blocking and compute intensive operations is discouraged. The general
-recommendation is to use asynchronous operations.
-
-However, there are exceptions. Node's own `require` statement is synchronous. It
-is mainly used at program startup and only for a handful of files. Consequently,
-although it being synchronous, using it is harmless. Same thing goes for
-synchronous file globs in combination with `require` at startup.
-
-The use of asynchronous code is mainly important for file walking operations
-during runtime. For example for globbing a large amount of files or recursive
-copying/deleting of folder structures. These operations generally take a long
-time to complete and would if implemented synchronously disrupt progress
-animations or delay server responses.
-
-An advantage of asynchronous operations is that libraries can use it to
-offer increased reliability. For example the popular file deletion library
-rimraf uses `setTimeout` and a limited amount of retries after increasing
-time intervals to [mitigate EBUSY errors on
-windows](https://github.com/isaacs/rimraf/blob/master/rimraf.js#L20-L27).
-Also, libraries can use asynchronicity to offload work onto worker threads. By
-providing an asynchronous API, fixes and optimizations can be implemented
-transparently without breaking API compatibility.

package/docs/assets/architecture/Ember-CLI architecture.xml

@@ -1 +0,0 @@
-<mxfile userAgent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.89 Safari/537.36" type="google"><diagram>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</diagram></mxfile>

package/docs/assets/architecture/README.md

@@ -1,5 +0,0 @@
-# Steps to update architecture diagram
-1. Open xml file in https://www.draw.io
-2. Make necessary changes
-3. Commit the updated diagram in xml and png format.
-4. Point the architecture.md file to the updated diagram

package/docs/brocfile-transition.md

@@ -1,46 +0,0 @@
-# Brocfile Transition
-
-## Why
-
-Broccoli historically assumed its brocfile was like a main file. Originally, we loaded the required config on-demand when the brocfile was invoked, unfortunately as the addon story evolved, we required this data before the brocfile was even invoked (or for tasks where no brocfile invocation was needed). This created a problem, and the quickest solution lead us to the current state of affairs, where we end up duplicating much internal state to satisfy both parts of the system.
-
-This change occurred in an effort to unify both sides, rather then duplicating state, we can now pass that state in as an argument. Since the behavior of this file is a superset of a typical Brocfile, we opted to also change the name.
-
-With this change, we are in a good position to fix more bugs, remove some much needed tech-debt, and continue to improve the internals without causing uneeded pain in userland.
-
-Happy Hacking!
-
-## How
-
-Transitioning your Brocfile is fairly straight forward. Simply take the contents of your Brocfile and place it in the body of the function in the new `ember-cli-build.js` file.  Instead of using `module.exports` to return the tree simply have the function return the tree.  Ensure you pass the `defaults` to the EmberApp constructor along with any options you were passing to `EmberApp` in the Brocfile.  Internally these two objects will be merged from right to left.
-
-Two steps:
-
-1. Remove `Brocfile.js` and add contents into `ember-cli-build.js`
-2. Pass `defaults` into the `EmberApp` constructor
-
-## Before (Brocfile.js)
-
-```
-var EmberApp = require('ember-cli/lib/broccoli/ember-app');
-var app = new EmberApp();
-app.import("file1.js");
-app.import("file2.js");
-module.exports = app.toTree();
-```
-
-## After (ember-cli-build.js)
-```
-var EmberApp = require('ember-cli/lib/broccoli/ember-app');
-
-module.exports = function (defaults) {
-    var app = new EmberApp(defaults, {
-        // Any other options
-    });
-
-    app.import("file1.js");
-    app.import("file2.js");
-
-    return app.toTree();
-};
-```

package/docs/build/api.js

@@ -1,44 +0,0 @@
-YUI.add("yuidoc-meta", function(Y) {
-   Y.YUIDoc = { meta: {
-    "classes": [
-        "Addon",
-        "AmdTransformAddon",
-        "Blueprint",
-        "Builder",
-        "CLI",
-        "Command",
-        "DefaultPackager",
-        "EmberAddon",
-        "EmberApp",
-        "HardwareInfo",
-        "HistorySupportAddon",
-        "Instrumentation",
-        "NodeModulesList",
-        "NpmTask",
-        "PackageInfo",
-        "PackageInfoCache",
-        "PerBundleAddonCache {",
-        "Project",
-        "ServeFilesAddon",
-        "TestsServerAddon",
-        "WatcherAddon",
-        "WindowsSymlinkChecker"
-    ],
-    "modules": [
-        "ember-cli",
-        "is-lazy-engine"
-    ],
-    "allModules": [
-        {
-            "displayName": "ember-cli",
-            "name": "ember-cli"
-        },
-        {
-            "displayName": "is-lazy-engine",
-            "name": "is-lazy-engine",
-            "description": "Indicate if a given object is a constructor function or class or an instance of an Addon."
-        }
-    ],
-    "elements": []
-} };
-});