Versions dropdown menu v2

For gitlab-com&20 (closed)

In its first MVC, the dropdown menu introduced in https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/301 is taking its values from the current and previous values in https://gitlab.com/gitlab-com/gitlab-docs/blob/master/content/_data/versions.yaml.

This came with a lot of shortcomings.

1. The versions dropdown will get outdated in each release -- Since this file changes with each version, and we rotate the online versions, with the current implementation, we're in a state where whenever a new version is released the dropdown of a previous versions will be outdated and have dead links.
2. Versions drop-down with (latest) 11.3 at the top -- when the site is showing master (so, displaying a mixture of 11.3 and 11.4 content) is misleading. It should be clear what 'version' you on, and this is master
   1. Should we just bump master up to the top, and (latest) down one? (Keeping master above the top horizontal rule, instead?
3. Users of GitLab.com may not know whether to look the latest version or master
4. Links in drop-down take you to home page, not identical page

Example of item 1

Facts:

• We always show the latest 3 versions plus master.
• The versions dropdown is built from content/_data/versions.yml which has the versions listed.
• When a new GitLab version is to be released, a new branch is created in the gitlab-docs project which has this version's info.
• All previous versions are pulled from their respective Docker images which contain the site as it was the time it was built.

Let's see the versions as time progresses:

1. It's September 22nd and GitLab 11.4 is released. On the docs project, we create a new 11.4 branch and we update the content of versions.yml. The three versions included in the dropdown are: 11.4, 11.3, 11.2.
2. It's October 22nd and GitLab 11.5 is released. On the docs project, we create a new 11.5 branch and we update the content of versions.yml. The three versions included in the dropdown are: 11.5, 11.4, 11.3.
3. It's November 22nd and GitLab 11.6 is released. On the docs project, we create a new 11.6 branch and we update the content of versions.yml. The three versions included in the dropdown are: 11.6, 11.5, 11.4.

So, each version (which is based on a branch) will have the versions.yml from the time the branch was created. From the above example, the very last version is 11.6. If you navigate though to 11.4, this will have the dropdown as it was built in September which includes versions 11.4, 11.3, 11.2. But since we only keep the last 3 (11.6, 11.5, 11.4), navigating to 11.3 or 11.2 will yield 404.

Solution

Temp: cherry pick versions.yml from master to all 3 latest branches.

Permanent: Since the versions implementation is taken from what Docker does, their solution is to have the dropdown updated via javascript: archive.js reads https://docs.docker.com/js/archives.json (includes all online versions) which could be basically our versions.yml taken from master.

The version link always takes you to the home page

From the discussion in https://gitlab.slack.com/archives/C16HYA2P5/p1537977138000100

Still, I am not sure how does UX of the version selector work. Some users are confused as well.

E.g. situation: I am here https://docs.gitlab.com/ee/user/project/clusters/index.html#installing-applications And when I click on specific version (e.g. 11.2) Is it supposed to always redirect me to main docs page -https://docs.gitlab.com/11.2 or at the specific 11.2 version of that doc file in case if it's available?

To solve this, we need to get the dropdown links to link to the full page URL.

• This is doable by using Nanoc's <%= @item.identifier.without_ext + '.html' %> appended to the links in https://gitlab.com/gitlab-com/gitlab-docs/blob/bc09e8d46ec5d65193123b5fecb255cf45b978a6/layouts/header.html#L20-23. But then, this has some shortcomings: if a page is new, it won't exist in previous versions, so having the full URL would lead to 404. Also, what if the page existed in the old version but has since been renamed. This is difficult to solve with Nanoc's full URL solution, because we have to check if a file exists in a branch every time. https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/312

Possible other solutions and enhancements:

• If it hits a 404, redirect to the homepage or smt, that's not a good experience though.
• We could maintain data about both within the latest md file itself => Since we only care if a page exists, we can always add something like gl_version: 11.3 in the yaml frontmatter, and then deduct from this the previous 2 versions where the link would lead to 404.
• We can prep a 404 page exclusive for that case of new features, saying smt like this feature is not available in this version.
  • We could append a param to every menu option so we can differentiate and do what the above suggests.
  • For an MVC, we can edit the current 404 to include that message no matter what.
• We could display search results on our 404 page based on the terms in the URL, so if a similar page exists, it might be evident.