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"