[DOC release] Add note about router service event and property update…

… timing

packages/@ember/-internals/routing/lib/services/router.ts

@@ -439,6 +439,10 @@ export default class RouterService extends Service {
     }
     ```
 
+    The exact timing to fire `routeDidChange` is after the Route's
+    [didTransition](/ember/release/classes/Route/events/didTransition?anchor=didTransition)
+    action fired.
+
     @event routeDidChange
     @param {Transition} transition
     @public
@@ -469,6 +473,9 @@ RouterService.reopen(Evented, {
      * `blog.index` when you visit `/blog`
      * `blog.post` when you visit `/blog/some-post-id`
 
+     This property is updated after Route's [didTransition](/ember/release/classes/Route/events/didTransition?anchor=didTransition)
+     action and before `routeDidChange` being fired.
+
      @property currentRouteName
      @type String
      @public
@@ -497,6 +504,9 @@ RouterService.reopen(Evented, {
      * `/blog` when you visit `/blog`
      * `/blog/some-post-id` when you visit `/blog/some-post-id`
 
+     This property is updated after Route's [didTransition](/ember/release/classes/Route/events/didTransition?anchor=didTransition)
+     action and before `routeDidChange` being fired.
+
      @property currentURL
      @type String
      @public
@@ -580,7 +590,9 @@ RouterService.reopen(Evented, {
 
     This property is guaranteed to change whenever a route transition
     happens (even when that transition only changes parameters
-    and doesn't change the active route).
+    and doesn't change the active route). It is updated after Route's
+    [didTransition](/ember/release/classes/Route/events/didTransition?anchor=didTransition)
+    action and before `routeDidChange` being fired.
 
     Usage example:
     ```app/components/header.js

packages/ember/tests/routing/router_service_test/currenturl_lifecycle_test.js

@@ -12,6 +12,39 @@ let ROUTE_NAMES = ['index', 'child', 'sister', 'brother', 'loading'];
 let InstrumentedRoute = Route.extend({
   routerService: injectService('router'),
 
+  init() {
+    this._super(...arguments);
+    let service = get(this, 'routerService');
+    service.on('routeWillChange', transition => {
+      results.push([
+        service.get('currentRouteName'),
+        `${this.routeName} routeWillChange: ${transition.from && transition.from.name} - ${
+          transition.to.name
+        }`,
+        service.get('currentURL'),
+      ]);
+    });
+    service.on('routeDidChange', transition => {
+      results.push([
+        service.get('currentRouteName'),
+        `${this.routeName} routeDidChange: ${transition.from && transition.from.name} - ${
+          transition.to.name
+        }`,
+        service.get('currentURL'),
+      ]);
+    });
+  },
+
+  activate() {
+    let service = get(this, 'routerService');
+    results.push([service.get('currentRouteName'), 'activate', service.get('currentURL')]);
+  },
+
+  redirect() {
+    let service = get(this, 'routerService');
+    results.push([service.get('currentRouteName'), 'redirect', service.get('currentURL')]);
+  },
+
   beforeModel() {
     let service = get(this, 'routerService');
     results.push([service.get('currentRouteName'), 'beforeModel', service.get('currentURL')]);
@@ -29,6 +62,23 @@ let InstrumentedRoute = Route.extend({
     let service = get(this, 'routerService');
     results.push([service.get('currentRouteName'), 'afterModel', service.get('currentURL')]);
   },
+
+  actions: {
+    willTransition(transition) {
+      let service = get(this, 'routerService');
+      results.push([
+        service.get('currentRouteName'),
+        `${this.routeName} willTransition: ${transition.from && transition.from.name} - ${
+          transition.to.name
+        }`,
+        service.get('currentURL'),
+      ]);
+    },
+    didTransition() {
+      let service = get(this, 'routerService');
+      results.push([service.get('currentRouteName'), 'didTransition', service.get('currentURL')]);
+    },
+  },
 });
 
 moduleFor(
@@ -105,15 +155,26 @@ moduleFor(
         });
     }
 
-    ['@test RouterService#currentURL is not set during lifecycle hooks'](assert) {
+    ['@test RouterService#currentURL is not set during model lifecycle hooks until routeDidChange'](
+      assert
+    ) {
       assert.expect(2);
 
       return this.visit('/')
         .then(() => {
           assert.deepEqual(results, [
+            [null, 'parent.index routeWillChange: null - parent.index', null],
             [null, 'beforeModel', null],
             [null, 'model', null],
+            [null, 'activate', null],
+            [null, 'parent.loading routeWillChange: null - parent.loading', null],
+            [null, 'parent.index routeWillChange: null - parent.loading', null],
             ['parent.loading', 'afterModel', '/'],
+            ['parent.loading', 'redirect', '/'],
+            ['parent.loading', 'activate', '/'],
+            ['parent.loading', 'didTransition', '/'],
+            ['parent.index', 'parent.loading routeDidChange: null - parent.index', '/'],
+            ['parent.index', 'parent.index routeDidChange: null - parent.index', '/'],
           ]);
 
           results = [];
@@ -122,9 +183,27 @@ moduleFor(
         })
         .then(() => {
           assert.deepEqual(results, [
+            ['parent.index', 'parent.index willTransition: parent.index - parent.child', '/'],
+            ['parent.index', 'parent.child routeWillChange: parent.index - parent.child', '/'],
+            ['parent.index', 'parent.loading routeWillChange: parent.index - parent.child', '/'],
+            ['parent.index', 'parent.index routeWillChange: parent.index - parent.child', '/'],
             ['parent.index', 'beforeModel', '/'],
             ['parent.index', 'model', '/'],
+            ['parent.index', 'activate', '/'],
+            ['parent.index', 'parent.child routeWillChange: parent.index - parent.loading', '/'],
+            ['parent.index', 'parent.loading routeWillChange: parent.index - parent.loading', '/'],
+            ['parent.index', 'parent.index routeWillChange: parent.index - parent.loading', '/'],
             ['parent.loading', 'afterModel', '/child'],
+            ['parent.loading', 'redirect', '/child'],
+            ['parent.loading', 'activate', '/child'],
+            ['parent.loading', 'didTransition', '/child'],
+            ['parent.child', 'parent.child routeDidChange: parent.index - parent.child', '/child'],
+            [
+              'parent.child',
+              'parent.loading routeDidChange: parent.index - parent.child',
+              '/child',
+            ],
+            ['parent.child', 'parent.index routeDidChange: parent.index - parent.child', '/child'],
           ]);
         });
     }