move intro and jquery integration to configuring ember section

Author: locks

guides/v3.3.0/optional-features/introduction.md renamed to guides/v3.3.0/configuring-ember/optional-features.md

@@ -1,4 +1,7 @@
-Because major releases of Ember are not supposed to make breaking changes without prior deprecation, the project has been extremely conservative about changing behaviors that don't have a clear deprecation path. As a result, we've had several quirks of the framework linger into the 3.x series.
+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.
 
@@ -37,10 +40,9 @@ Available features:
   jquery-integration (Default: true)
     Adds jQuery to the Ember application.
     More information: https://github.com/emberjs/rfcs/pull/294
-
 ```
 
-## Enabling or disabling a feature
+## 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 <feature>` and `ember feature:disable <feature>`.
 
@@ -53,3 +55,29 @@ Disabled template-only-glimmer-components. Be sure to commit config/optional-fea
 
 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.0.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.

guides/v3.3.0/optional-features/removing-jquery.md

@@ -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,19 +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: "Optional Features"
-  url: "optional-features"
-  pages:
-    - title: "Removing jQuery"
-      url: "removing-jquery"
-
 - title: "Contributing to Ember.js"
-  url: 'contributing'
+  url: "contributing"
   pages:
     - title: "Adding New Features"
       url: "adding-new-features"

guides/v3.3.0/pages.yml

@@ -1,4 +1,7 @@
-Because major releases of Ember are not supposed to make breaking changes without prior deprecation, the project has been extremely conservative about changing behaviors that don't have a clear deprecation path. As a result, we've had several quirks of the framework linger into the 3.x series.
+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.
 
@@ -37,10 +40,9 @@ Available features:
   jquery-integration (Default: true)
     Adds jQuery to the Ember application.
     More information: https://github.com/emberjs/rfcs/pull/294
-
 ```
 
-## Enabling or disabling a feature
+## 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 <feature>` and `ember feature:disable <feature>`.
 
@@ -53,3 +55,29 @@ Disabled template-only-glimmer-components. Be sure to commit config/optional-fea
 
 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.0.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.