diff --git a/guides/v3.3.0/pages.yml b/guides/v3.3.0/pages.yml index 480ca62896..e19391d955 100644 --- a/guides/v3.3.0/pages.yml +++ b/guides/v3.3.0/pages.yml @@ -1,12 +1,12 @@ - title: "Guides and Tutorials" - url: 'index' + url: "index" skip_toc: true pages: - title: "Ember.js Guides" url: "" - title: "Getting Started" - url: 'getting-started' + url: "getting-started" pages: - title: "Quick Start" url: "quick-start" @@ -18,12 +18,12 @@ url: "js-primer" - title: "Tutorial" - url: 'tutorial' + url: "tutorial" pages: - title: "Creating Your App" url: "ember-cli" - title: "Planning Your App" - url: 'acceptance-test' + url: "acceptance-test" - title: "Routes and Templates" url: "routes-and-templates" - title: "The Model Hook" @@ -46,7 +46,7 @@ url: "deploying" - title: "The Object Model" - url: 'object-model' + url: "object-model" pages: - title: "Objects in Ember" url: "index" @@ -63,10 +63,10 @@ - title: "Bindings" url: "bindings" - title: "Enumerables" - url: 'enumerables' + url: "enumerables" - title: "Routing" - url: 'routing' + url: "routing" pages: - title: "Introduction" url: "index" @@ -88,7 +88,7 @@ url: "asynchronous-routing" - title: "Templates" - url: 'templates' + url: "templates" pages: - title: "Handlebars Basics" url: "handlebars-basics" @@ -114,7 +114,7 @@ url: "writing-helpers" - title: "Components" - url: 'components' + url: "components" pages: - title: "Defining a Component" url: "defining-a-component" @@ -134,13 +134,13 @@ url: "triggering-changes-with-actions" - title: "Controllers" - url: 'controllers' + url: "controllers" pages: - title: "Introduction" url: "index" - title: "Models" - url: 'models' + url: "models" pages: - title: "Introduction" url: "index" @@ -162,7 +162,7 @@ url: "customizing-serializers" - title: "Application Concerns" - url: 'applications' + url: "applications" pages: - title: "Applications and Instances" url: "applications-and-instances" @@ -176,7 +176,7 @@ url: "run-loop" - title: "Testing" - url: 'testing' + url: "testing" pages: - title: "Introduction" url: "index" @@ -232,7 +232,7 @@ url: "managing-dependencies" - title: "Configuring Ember.js" - url: 'configuring-ember' + url: "configuring-ember" pages: - title: "Configuring Your App" url: "configuring-your-app" @@ -248,13 +248,15 @@ url: "embedding-applications" - title: "Feature Flags" url: "feature-flags" + - title: "Optional Features" + url: "optional-features" - title: "Build targets" url: "build-targets" - title: "Debugging" url: "debugging" - title: "Contributing to Ember.js" - url: 'contributing' + url: "contributing" pages: - title: "Adding New Features" url: "adding-new-features" diff --git a/guides/v3.4.0/configuring-ember/optional-features.md b/guides/v3.4.0/configuring-ember/optional-features.md new file mode 100644 index 0000000000..c67d50e882 --- /dev/null +++ b/guides/v3.4.0/configuring-ember/optional-features.md @@ -0,0 +1,83 @@ +One of the ways that Ember releases guarantee stability is by following [Semantic Versioning](https://semver.org/) (SemVer). +For the Ember project this means that any feature that is to be removed must first be deprecated, +and only removed when a major version is released. +It also means that new features are introduced in a backwards compatible way. + +To give the project a path forward when a breaking change is mandatory, we've released the [`@ember/optional-features`](https://github.com/emberjs/ember-optional-features) addon. + +This addon does nothing by default, but provides a command-line interface to enable and disable breaking changes in Ember. + +## Installation + +To get started with optional features, you must install the addon: + +```bash +ember install @ember/optional-features +``` + +This will make three new commands available to Ember CLI within your project, `feature:list`, `feature:enable`, and `feature:disable`. + +## Listing features + +The optional features available to your project will depend on the Ember version your project is using. + +To see which optional features are available, you can run the following command: + +```bash +$ ember feature:list +Usage: + + To list all available features, run ember feature:list. + To enable a feature, run ember feature:enable some-feature. + To disable a feature, run ember feature:disable some-feature. + +Available features: + + application-template-wrapper (Default: true) + Wrap the top-level application template (application.hbs) with a `
` element. + More information: https://github.com/emberjs/rfcs/pull/280 + + jquery-integration (Default: true) + Adds jQuery to the Ember application. + More information: https://github.com/emberjs/rfcs/pull/294 +``` + +## Features + +Once you see a feature that you would like to toggle for your project you can run one of two commands, `ember feature:enable ` and `ember feature:disable `. + +Let us disable `jquery-integration` to see what happens: + +```bash +$ ember feature:disable jquery-integration +Disabled jquery-integration. Be sure to commit config/optional-features.json to source control! +``` + +As we can see from the warning, `@ember/optional-features` has created a file in `config/optional-features.json` to store the configuration for your project. +We commit it to our repository and we are off to the races! + +### jquery-integration + +The Ember framework comes by default with jQuery integration. +It is used for event handling, and to provide some APIs like `this.$()` in components. + +With the release of ember-source v3.4.0, an optional feature flag was introduced that allows users to opt out of jQuery. +To enable it, run the following command after setting up `@ember/optional-features`: + +```shell +ember feature:disable jquery-integration +``` + +This will remove jQuery from your `vendor.js` bundle and disable any use of jQuery in Ember itself. +Now your app will be about 30KB lighter! + +#### Caveats + +Without jQuery, any code that still relies on it will break, especially the following usages: + +- [`this.$()`](https://www.emberjs.com/api/ember/release/classes/Component/methods/$?anchor=%24) in components +- `jQuery` or `$` directly as a global, through `Ember.$()` or by importing it (`import jQuery from jquery;`) +- global acceptance test helpers like `find()` or `click()` +- `this.$()` in component tests + +Note that this also applies to all addons that your app uses, so make sure they support being used without jQuery. diff --git a/guides/v3.4.0/pages.yml b/guides/v3.4.0/pages.yml index 480ca62896..e19391d955 100644 --- a/guides/v3.4.0/pages.yml +++ b/guides/v3.4.0/pages.yml @@ -1,12 +1,12 @@ - title: "Guides and Tutorials" - url: 'index' + url: "index" skip_toc: true pages: - title: "Ember.js Guides" url: "" - title: "Getting Started" - url: 'getting-started' + url: "getting-started" pages: - title: "Quick Start" url: "quick-start" @@ -18,12 +18,12 @@ url: "js-primer" - title: "Tutorial" - url: 'tutorial' + url: "tutorial" pages: - title: "Creating Your App" url: "ember-cli" - title: "Planning Your App" - url: 'acceptance-test' + url: "acceptance-test" - title: "Routes and Templates" url: "routes-and-templates" - title: "The Model Hook" @@ -46,7 +46,7 @@ url: "deploying" - title: "The Object Model" - url: 'object-model' + url: "object-model" pages: - title: "Objects in Ember" url: "index" @@ -63,10 +63,10 @@ - title: "Bindings" url: "bindings" - title: "Enumerables" - url: 'enumerables' + url: "enumerables" - title: "Routing" - url: 'routing' + url: "routing" pages: - title: "Introduction" url: "index" @@ -88,7 +88,7 @@ url: "asynchronous-routing" - title: "Templates" - url: 'templates' + url: "templates" pages: - title: "Handlebars Basics" url: "handlebars-basics" @@ -114,7 +114,7 @@ url: "writing-helpers" - title: "Components" - url: 'components' + url: "components" pages: - title: "Defining a Component" url: "defining-a-component" @@ -134,13 +134,13 @@ url: "triggering-changes-with-actions" - title: "Controllers" - url: 'controllers' + url: "controllers" pages: - title: "Introduction" url: "index" - title: "Models" - url: 'models' + url: "models" pages: - title: "Introduction" url: "index" @@ -162,7 +162,7 @@ url: "customizing-serializers" - title: "Application Concerns" - url: 'applications' + url: "applications" pages: - title: "Applications and Instances" url: "applications-and-instances" @@ -176,7 +176,7 @@ url: "run-loop" - title: "Testing" - url: 'testing' + url: "testing" pages: - title: "Introduction" url: "index" @@ -232,7 +232,7 @@ url: "managing-dependencies" - title: "Configuring Ember.js" - url: 'configuring-ember' + url: "configuring-ember" pages: - title: "Configuring Your App" url: "configuring-your-app" @@ -248,13 +248,15 @@ url: "embedding-applications" - title: "Feature Flags" url: "feature-flags" + - title: "Optional Features" + url: "optional-features" - title: "Build targets" url: "build-targets" - title: "Debugging" url: "debugging" - title: "Contributing to Ember.js" - url: 'contributing' + url: "contributing" pages: - title: "Adding New Features" url: "adding-new-features" diff --git a/guides/v3.5.0/configuring-ember/optional-features.md b/guides/v3.5.0/configuring-ember/optional-features.md new file mode 100644 index 0000000000..c67d50e882 --- /dev/null +++ b/guides/v3.5.0/configuring-ember/optional-features.md @@ -0,0 +1,83 @@ +One of the ways that Ember releases guarantee stability is by following [Semantic Versioning](https://semver.org/) (SemVer). +For the Ember project this means that any feature that is to be removed must first be deprecated, +and only removed when a major version is released. +It also means that new features are introduced in a backwards compatible way. + +To give the project a path forward when a breaking change is mandatory, we've released the [`@ember/optional-features`](https://github.com/emberjs/ember-optional-features) addon. + +This addon does nothing by default, but provides a command-line interface to enable and disable breaking changes in Ember. + +## Installation + +To get started with optional features, you must install the addon: + +```bash +ember install @ember/optional-features +``` + +This will make three new commands available to Ember CLI within your project, `feature:list`, `feature:enable`, and `feature:disable`. + +## Listing features + +The optional features available to your project will depend on the Ember version your project is using. + +To see which optional features are available, you can run the following command: + +```bash +$ ember feature:list +Usage: + + To list all available features, run ember feature:list. + To enable a feature, run ember feature:enable some-feature. + To disable a feature, run ember feature:disable some-feature. + +Available features: + + application-template-wrapper (Default: true) + Wrap the top-level application template (application.hbs) with a `
` element. + More information: https://github.com/emberjs/rfcs/pull/280 + + jquery-integration (Default: true) + Adds jQuery to the Ember application. + More information: https://github.com/emberjs/rfcs/pull/294 +``` + +## Features + +Once you see a feature that you would like to toggle for your project you can run one of two commands, `ember feature:enable ` and `ember feature:disable `. + +Let us disable `jquery-integration` to see what happens: + +```bash +$ ember feature:disable jquery-integration +Disabled jquery-integration. Be sure to commit config/optional-features.json to source control! +``` + +As we can see from the warning, `@ember/optional-features` has created a file in `config/optional-features.json` to store the configuration for your project. +We commit it to our repository and we are off to the races! + +### jquery-integration + +The Ember framework comes by default with jQuery integration. +It is used for event handling, and to provide some APIs like `this.$()` in components. + +With the release of ember-source v3.4.0, an optional feature flag was introduced that allows users to opt out of jQuery. +To enable it, run the following command after setting up `@ember/optional-features`: + +```shell +ember feature:disable jquery-integration +``` + +This will remove jQuery from your `vendor.js` bundle and disable any use of jQuery in Ember itself. +Now your app will be about 30KB lighter! + +#### Caveats + +Without jQuery, any code that still relies on it will break, especially the following usages: + +- [`this.$()`](https://www.emberjs.com/api/ember/release/classes/Component/methods/$?anchor=%24) in components +- `jQuery` or `$` directly as a global, through `Ember.$()` or by importing it (`import jQuery from jquery;`) +- global acceptance test helpers like `find()` or `click()` +- `this.$()` in component tests + +Note that this also applies to all addons that your app uses, so make sure they support being used without jQuery. diff --git a/guides/v3.5.0/pages.yml b/guides/v3.5.0/pages.yml index 480ca62896..51428ce9cd 100644 --- a/guides/v3.5.0/pages.yml +++ b/guides/v3.5.0/pages.yml @@ -248,6 +248,8 @@ url: "embedding-applications" - title: "Feature Flags" url: "feature-flags" + - title: "Optional Features" + url: "optional-features" - title: "Build targets" url: "build-targets" - title: "Debugging"