From 69aad84e8477b688f0d041bc754770cf9a448d37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20Sandstr=C3=B6m?= Date: Sat, 23 Jan 2021 09:39:59 +0100 Subject: [PATCH 1/3] Deprecate Auto Location --- text/0711-deprecate-auto-location.md | 139 +++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 text/0711-deprecate-auto-location.md diff --git a/text/0711-deprecate-auto-location.md b/text/0711-deprecate-auto-location.md new file mode 100644 index 0000000000..33627ca642 --- /dev/null +++ b/text/0711-deprecate-auto-location.md @@ -0,0 +1,139 @@ +--- +Stage: Accepted +Start Date: 2021-01-23 +Release Date: Unreleased +Release Versions: + ember-source: vX.Y.Z + ember-data: vX.Y.Z +Relevant Team(s): Ember.js +RFC PR: https://github.com/emberjs/rfcs/pull/711 +--- + + + +# + +## Summary + +Deprecate Ember.AutoLocation and related APIs. In next major version, +make history the default location (instead of auto). + +## Motivation + +In practice, 'auto' will almost always resolve to the 'history' location. + +By removing the 'auto' location and setting 'history' as the default we're removing +some complexity around router location, with no downside for users, since they +all get it resolved to history anyway. + +## Background + +The Ember Router can use different mechanisms to serialize its state. +The two common ones are 'history' and 'hash'. There is also a special +location called 'auto' which does feature detection, preferring 'history'. + +Basically all browsers will get 'history': +https://caniuse.com/mdn-api_history_pushstate + +The check 'auto' is basically doing this: + +```js +// Boosted from Modernizr: https://github.com/Modernizr/Modernizr/blob/master/feature-detects/history.js +// The stock browser on Android 2.2 & 2.3, and 4.0.x returns positive on history support +// Unfortunately support is really buggy and there is no clean way to detect +// these bugs, so we fall back to a user agent sniff :( + +// We only want Android 2 and 4.0, stock browser, and not Chrome which identifies +// itself as 'Mobile Safari' as well, nor Windows Phone. + +if ( + (userAgent.indexOf('Android 2.') !== -1 || userAgent.indexOf('Android 4.0') !== -1) && + userAgent.indexOf('Mobile Safari') !== -1 && + userAgent.indexOf('Chrome') === -1 && + userAgent.indexOf('Windows Phone') === -1 + ) { + return false; + } + + return Boolean(window.history && 'pushState' in window.history); +``` + +## Transition Path + +We'll begin with deprecating history, in next major release we +set history as the default. Since auto is default today, +and almost always resolve to history, most users won't need +to do a thing and they'll still get history behavior in the +next major release. + +There are two groups to consider: + +1. People who need auto-detection (hash/history switching) and +2. Those that have explicitly set location to 'auto'. + +For the first group the solution is fairly trivial. Simply +implement feature detection, via e.g. Modernizr[1], like this: + +```js +// app/router.js +export default class Router extends EmberRouter { + location = (historyFeatureDetection() ? 'history' : 'hash'); + // … +} +``` + +For the second group, they simply need to replace their explicit choice +of 'auto' for 'history' in `locationType` in environment.js (or +`location` in router.js), since history is what their 'auto' resolves +to anyway. + +### What To Deprecate (and later remove) + +- The HistoryLocation class +- The method `detect` from the `Location` interface +- Explicitly setting 'auto' as the preferred location. + +### Deprecated or already private (should also be removed) +- Remove the `create` method on Location (replaced by registry) +- `registerImplementation` method on `Location` +- `supportsHistory` exported in location/utils.ts + +## How We Teach This + +- Remove the text about auto location from guides. +- There is already good documentation about the different + location types (history, hash, none) and how to write your own. +- Slight adjustments needed for the guides, removing mentions of auto[2]. + +Overall there should be fairly little changes to how Ember is taught. Since +the vast majority of users will need to make zero code changes and will have +zero change in actual behaviour. + +## Drawbacks + +Anyone using an unsupported browser will need to do feature detection +in their own code base or opt everyone into using the hash location. + +https://caniuse.com/mdn-api_history_pushstate + +## Alternatives + +Do nothing. + +## Unresolved questions + +There are currently no unresolved questions. + +## References + +[1] https://github.com/Modernizr/Modernizr/blob/master/feature-detects/history.js +[2] https://guides.emberjs.com/release/configuring-ember/specifying-url-type/ From 7799fd432cced752bdd9a5dc7f392bf43ed2e1a0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20Sandstr=C3=B6m?= Date: Sun, 24 Jan 2021 17:30:09 +0100 Subject: [PATCH 2/3] Text adjustments --- text/0711-deprecate-auto-location.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/text/0711-deprecate-auto-location.md b/text/0711-deprecate-auto-location.md index 33627ca642..6d0f5cd134 100644 --- a/text/0711-deprecate-auto-location.md +++ b/text/0711-deprecate-auto-location.md @@ -69,13 +69,14 @@ if ( ## Transition Path -We'll begin with deprecating history, in next major release we +We'll begin with deprecating auto, in next major release we set history as the default. Since auto is default today, and almost always resolve to history, most users won't need -to do a thing and they'll still get history behavior in the -next major release. +to do a thing and they'll still get history location in the +next major release (but set directly, without auto resolving +to it). -There are two groups to consider: +There are two groups to consider though: 1. People who need auto-detection (hash/history switching) and 2. Those that have explicitly set location to 'auto'. @@ -105,7 +106,7 @@ to anyway. ### Deprecated or already private (should also be removed) - Remove the `create` method on Location (replaced by registry) - `registerImplementation` method on `Location` -- `supportsHistory` exported in location/utils.ts +- `supportsHistory` function exported in location/utils.ts ## How We Teach This From ab6020f45dfd0bc86b4b51fe54d6fe8c481d7574 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20Sandstr=C3=B6m?= Date: Fri, 29 Jan 2021 15:17:36 +0100 Subject: [PATCH 3/3] Text updates, from feedback --- text/0711-deprecate-auto-location.md | 51 +++++++++++++--------------- 1 file changed, 24 insertions(+), 27 deletions(-) diff --git a/text/0711-deprecate-auto-location.md b/text/0711-deprecate-auto-location.md index 6d0f5cd134..09a9a28664 100644 --- a/text/0711-deprecate-auto-location.md +++ b/text/0711-deprecate-auto-location.md @@ -9,18 +9,7 @@ Relevant Team(s): Ember.js RFC PR: https://github.com/emberjs/rfcs/pull/711 --- - - -# +# Deprecate AutoLocation ## Summary @@ -41,7 +30,12 @@ The Ember Router can use different mechanisms to serialize its state. The two common ones are 'history' and 'hash'. There is also a special location called 'auto' which does feature detection, preferring 'history'. -Basically all browsers will get 'history': +When the special 'auto' location was added (and made default), less than +half of browsers supported the (then) new history location API. For seamless +upgrade to history API when available, Ember created the special auto location. + +These days (many years later), basically all browsers will get 'history', +since the History Location API is very widely supported, even by IE 11: https://caniuse.com/mdn-api_history_pushstate The check 'auto' is basically doing this: @@ -69,20 +63,23 @@ if ( ## Transition Path -We'll begin with deprecating auto, in next major release we -set history as the default. Since auto is default today, -and almost always resolve to history, most users won't need -to do a thing and they'll still get history location in the -next major release (but set directly, without auto resolving -to it). +We'll begin with deprecating auto (explicitly or implicitly set). + +In next major release we change the default to 'history'. +Since auto is default today, and almost always resolve to history, +most users can change to 'history' and it's done. + +We also need to update the template in ember-cli blueprint, +so that 'history' will be the default value for `locationType` +in environment.js. -There are two groups to consider though: +There are two groups to consider: 1. People who need auto-detection (hash/history switching) and -2. Those that have explicitly set location to 'auto'. +2. those with location set to 'auto' (this will be most people). -For the first group the solution is fairly trivial. Simply -implement feature detection, via e.g. Modernizr[1], like this: +The first group can implement feature detection, +via e.g. Modernizr[1], like this: ```js // app/router.js @@ -92,14 +89,14 @@ export default class Router extends EmberRouter { } ``` -For the second group, they simply need to replace their explicit choice +For the second group, they need to replace their choice of 'auto' for 'history' in `locationType` in environment.js (or -`location` in router.js), since history is what their 'auto' resolves -to anyway. +`location` in router.js), since history is what 'auto' mostly +resolves to anyway. ### What To Deprecate (and later remove) -- The HistoryLocation class +- The AutoLocation class - The method `detect` from the `Location` interface - Explicitly setting 'auto' as the preferred location.