Get the Guides links to work with post 2.16 package restructure

[jenweber]

Deadline: released together with 2.16 on Monday

Right now, legacy URLs (like from the Guides) pass through a fancy function that turns them into the right kind of links for the ember-api-docs. We need to modify that function to support the 2.16 packages.

So there are 2 parts that need to be addressed. One is, how do we catch that it needs to be parsed (so checking if the version is 2.16 or higher for the link) and then mapping it to the right package. Todd is finishing up the final details about how the packages are documented, which influences the links, but I think we could scaffold it out without knowing the final details. Todd will eventually have a table of info to convert from old classes to new modules

New format of sample URL, WIP http://localhost:4200/ember/2.16/classes/@ember%2Fcomponent%2Ftext-area

Old format:
http://localhost:4200/ember/2.11/classes/Ember.Component

WIP screenshot

Todos

• Make legacy redirects /classes/Ember.Component.html default to the latest pre-176 release (2.15.3) Fix legacy redirects #376
• Add better error handling for bad urls.
• Support legacy links with element hashes, such as /classes/Ember.Component.html#method_didReceiveAttrs
• Map legacy classes/modules to new 176 counterparts using https://github.com/ember-cli/ember-rfc176-data/ and change redirect version back to the true current release.

[toddjordan]

So, 2.16's been deployed, but this is still an open issue.

Links that work:

• Links to previous releases, such as: https://emberjs.com/api/ember/2.11/classes/Ember.Component

Links that do not yet work

• Links to unspecified releases, such as: https://emberjs.com/api/ember/release/classes/Ember.Component
• Legacy links from the old api site, such as http://emberjs.com/api/classes/Ember.Route.html

[jenweber]

Missing maps:

• on()
• http://emberjs.com/api/classes/Ember.Debug.html#method_registerDeprecationHandler
• http://emberjs.com/api/classes/Ember.Object.html#method_incrementProperty
• http://emberjs.com/api/classes/Ember.Enumerable.html
• http://emberjs.com/api/classes/Ember.Object.html#method_reopen and reopenClass
• http://emberjs.com/api/classes/Ember.Helper.html#method_helper
• http://emberjs.com/api/classes/Ember.String.html#method_htmlSafe
• http://emberjs.com/api/classes/Ember.Test

Ember.Computed.methodName references throughout guides should be updated. At risk of perceived churn, when there's not any.

Pages like https://www.emberjs.com/api/ember-data/2.16/classes/DS/methods/attr?anchor=attr too deeply nested

[jenweber]

New idea for routing:

1. Create a "latest" route at the root of routing, so you get "http://emberjs.com/api/latest"
2. In that route, use getLastVersion
3. Catch transitions in a redirect
4. Use the results of getLastVersion to modify the transition object, adding the version in.
5. Redirect to the new, versioned route

We replace guides links etc with a URL structured like "http://emberjs.com/api/latest/path/without/version"

The classes query continues to do its thing for pre-2.16 work. The new "latest" route is a more maintainable way to map changes as the docs evolve.

[toddjordan]

previously, we talked about having an indicator in place of the version number, so when you type https://emberjs.com/api/ember/release/modules/@ember%2Fapplication it redirects you to https://emberjs.com/api/ember/2.16/modules/@ember%2Fapplication.

You could also use lts, e.g. https://emberjs.com/api/ember/lts/modules/@ember%2Fapplication

you would put it after project because the versions diverge.

We had some discussion on the text and decision was to use release and lts because it matched release terminology, and we could potentially expand later to use beta and canary. current or latest could mean any release type, since they all have "currents".

I think this may have been working at some point, and just needs to be fixed. My memory could be faulty though.

Currently we use getLastVersion in these redirects, but we would need to add some mapping code that takes into account: https://github.com/ember-cli/ember-rfc176-data/blob/master/mappings.json

[toddjordan]

redirects to classes should now work, such as http://emberjs.com/api/classes/Ember.Debug.html now work. still some work to do on links with #method_myMethod will work on that over the weekend.