Almost half the links to QML API documents are broken

[Matthew Paul Thomas]

1. Go to any of the sub-pages of "Building blocks" <https://design.ubuntu.com/apps/building-blocks>.
2. Follow any of the links to QML API references.

What happens: 40% of the time you get a 404 page.

In particular, the number of broken QML API links on:
* <https://design.ubuntu.com/apps/building-blocks/views> is 3/3 (including bug 1461177)
* <https://design.ubuntu.com/apps/building-blocks/header> is 0/1
* <https://design.ubuntu.com/apps/building-blocks/list-items> is 1/1
* <https://design.ubuntu.com/apps/building-blocks/selection> is 1/6
* <https://design.ubuntu.com/apps/building-blocks/progress-activity> is 1/2
* <https://design.ubuntu.com/apps/building-blocks/text-input> is 1/3
* <https://design.ubuntu.com/apps/building-blocks/dialog> is 0/1.

It's quite likely that most of these links worked when the guidelines were originally published. Many, though not all, of them are links to URLs of the form developer.ubuntu.com/en/api/apps/qml/sdk-14.04/*. Most of these URLs return documents if the "14.04" is changed to "14.10" or "15.04". And bug 1463227 and bug 1466527 similarly describe broken links to sdk-14.04/ pages.

This suggests that a swathe of documents is being removed from developer.ubuntu.com every six months without any redirects being set up.

What should happen: either
* documents should no longer be removed from developer.ubuntu.com every six months, or
* the developer.ubuntu.com documents should stop including Ubuntu version numbers in their URLs, or
* the process of removing a document from developer.ubuntu.com should include setting up a redirect;
and
* the links from the "Building blocks" pages should be fixed.

[Nicholas Skaggs (nskaggs)]

Can we setup generic urls to avoid this and point to something like https://developer.ubuntu.com/en/api/apps/qml/stable or https://developer.ubuntu.com/en/api/apps/qml/development?

[David Callé (davidc3)]

We already do. eg.

https://developer.ubuntu.com/api/apps/qml/current/Ubuntu.Components.CheckBox/
https://developer.ubuntu.com/api/apps/qml/development/Ubuntu.Components.CheckBox/

[Matthew Paul Thomas (mpt)]

That's a possible first step towards a solution. But right now, those URLs don't show up in search results; only the 15.04/ URL does. <https://developer.ubuntu.com/en/search/?q=checkbox> And if you're writing something about checkboxes (whether you're writing for *.ubuntu.com or not), you will naturally link to the version you can find.

So if you want to prevent this bug from happening again, I suggest either:

* Stop generating a new version of the API reference for every release. Instead, regenerate a single set of pages based on all releases, with "Introduced in:"/"Deprecated since:"/"No longer available since:" keys atop individual documents -- or, when necessary, atop functions or parameters within documents. This would make the (re)generator code more complex. But it would mean much less work for every developer in future asking the question, "If I use this new-ish API, how much of the user base will I be forsaking?"

* Prominently link from each API page to the page for the same API in every other release where it is/was available, plus "Latest release" and "In development" as appropriate. And whenever a developer.ubuntu.com search returns an API reference document, group the release pages together into a single search result.

[Stephanie (wilson-steph1989)]

@davidc3 this has been resolved hasn't it?

[David Callé (davidc3)]

I've just checked and yes it has.

[Daniel Holbach (dholbach)]

<dholbach> davidcalle, on https://bugs.launchpad.net/developer-ubuntu-com/+bug/1466519 do we still need to do anything?
<ubot5> Ubuntu bug 1466519 in Ubuntu Developer Portal "Almost half the links to QML API documents are broken" [High,Confirmed]
<davidcalle> dholbach, nope, we are good