Version for GitLab.com users
The problem
We deploy the master branch of the /doc paths at docs.gitlab.com/ (hourly), which, for much of the month, is out of sync with GitLab.com, and also with the latest GitLab version.
However, we have multiple GitLab versions docs at docs.gitlab.com/XX.Y/ and a Versions menu for accessing them.
We need to
- update what default version is displayed at
/
and when - add an ability to view the current GitLab.com version (and consider taking into account Feature Flag or Canary visibility in a future iteration)
- update our documentation deployment processes to enable the above and automate as much as possible
Proposal
NOTE: This has been updated due to the new GitLab.com new deployment process and the fact that we're planning to automatically include docs.gitlab.com/XX.Y/ links in the UI.
Consider this diagram of the release process as you consider the proposal below.
- MVC: Automatically begin deploying the new pre-release minor version to docs.gitlab.com/XX.Y on the day before the first Monday of the month, so it is online in time for the first Monday, when users get the new GitLab version on GitLab.com. (For this month:
/12.2/
docs path online July 30 - i.e prior to Aug 1 GitLab 12.2.0-pre deployment.) (Note: These are dates inherited from the previous month's release and may change.) - Display this version at
/
from the following 22nd (its release) to the 21st. - Move the display of master branch content from
/
to/dev
. - Show "(GitLab.com)" next to the pre-release version number in the dropdown.
For further consideration:
- How to accommodate users seeing features that are behind a feature flag for other users. https://gitlab.com/gitlab-org/gitlab-ce/issues/56813
- Cookie based approach (cookie dropped from GitLab.com use) to automatically bring those users to the pre-release version if they've just been on gitlab.com, and maybe also indicate their feature flag or canary status.
Prior alternative plans
#### Option 1-
Keep the default branch as-is
-
Deploy another version for docs.gitlab.com based on the RC deployed in GitLab.com
-
Show another version menu with the future version, in its latest RC
Something like:
Option 2
-
Keep the default branch as-is
-
Direct GitLab.com users to https://gitlab.com/help, if we go for https://gitlab.com/gitlab-org/gitlab-ce/issues/53045:
Something like: