From f185e4bf9e07de2fd82a60373da20f46a8353b79 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Thu, 8 Nov 2018 09:10:15 +1000 Subject: [PATCH 1/4] Adjust how we do version text in docs --- doc/development/documentation/styleguide.md | 29 ++++++++++++++++----- 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 9d8d5afedad..e58ed1a8fd4 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -604,22 +604,39 @@ The following are recommended verbs for specific uses. ## GitLab versions and tiers -- Every piece of documentation that comes with a new feature should declare the - GitLab version that feature got introduced. Right below the heading add a - blockquote: +Tagged and released versions of GitLab documentation are available: + +- In the [documentation archives](https://docs.gitlab.com/archives/). +- At the `/help` URL for any GitLab installation. + +Because documentation is intended to describe the current state of the project at a particular point in time, +it is unnecessary to add specific text to the documentation describing what version a particular feature was introduced. +The version relevant to a feature can be assumed by the feature's presence in that version of the documentation. + +Discussing specific versions in GitLab documentation should be reserved **only** for the following cases: + +- A feature was introduced before online versions were available. Currently, that means before 11.2. +- A specific topic requires information that might be relevant to bridge the gap between specific versions. + For example, `If upgrading from a version of GitLab before x.y, follow the additional instructions below.` +- A feature was introduced in a patch release, so it's important to call out which patch the feature became available in. + +#### Text for documentation requiring version text + +- For features that need to declare the GitLab version that the feature was introduced. Text similar + to the following should be added immediately below the heading as a blockquote: ```md > Introduced in GitLab 8.3. ``` -- Whenever possible, every feature should have a link to the issue, MR or epic - (in that order) that introduced it. The above quote would be then transformed to: +- Whenever possible, version text should have a link to the issue, merge request, or epic + (in order or preference) that introduced the feature. For example: ```md > [Introduced]() in GitLab 8.3. ``` -- If the feature is only available in GitLab Enterprise Edition, don't forget to mention +- If the feature is only available in GitLab Enterprise Edition, mention the [paid tier](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers) the feature is available in: From 5d4c926d22292c4de8550a5ebcdb554c5f62a24f Mon Sep 17 00:00:00 2001 From: Evan Read Date: Tue, 15 Jan 2019 09:47:56 +1000 Subject: [PATCH 2/4] Change the guidance for version text --- doc/development/documentation/styleguide.md | 36 ++++++++------------- 1 file changed, 13 insertions(+), 23 deletions(-) diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index e58ed1a8fd4..445f62b8d1a 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -609,31 +609,23 @@ Tagged and released versions of GitLab documentation are available: - In the [documentation archives](https://docs.gitlab.com/archives/). - At the `/help` URL for any GitLab installation. -Because documentation is intended to describe the current state of the project at a particular point in time, -it is unnecessary to add specific text to the documentation describing what version a particular feature was introduced. -The version relevant to a feature can be assumed by the feature's presence in that version of the documentation. +The version introducing a new feature is added to the top of the topic in the documentation to provide +a helpful link back to how the feature was developed. -Discussing specific versions in GitLab documentation should be reserved **only** for the following cases: - -- A feature was introduced before online versions were available. Currently, that means before 11.2. -- A specific topic requires information that might be relevant to bridge the gap between specific versions. - For example, `If upgrading from a version of GitLab before x.y, follow the additional instructions below.` -- A feature was introduced in a patch release, so it's important to call out which patch the feature became available in. - -#### Text for documentation requiring version text +### Text for documentation requiring version text - For features that need to declare the GitLab version that the feature was introduced. Text similar to the following should be added immediately below the heading as a blockquote: ```md - > Introduced in GitLab 8.3. + > Introduced in GitLab 11.3. ``` - Whenever possible, version text should have a link to the issue, merge request, or epic (in order or preference) that introduced the feature. For example: ```md - > [Introduced]() in GitLab 8.3. + > [Introduced]() in GitLab 11.3. ``` - If the feature is only available in GitLab Enterprise Edition, mention @@ -641,21 +633,19 @@ Discussing specific versions in GitLab documentation should be reserved **only** the feature is available in: ```md - > [Introduced]() in [GitLab Starter](https://about.gitlab.com/pricing/) 10.3. + > [Introduced]() in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. ``` -### Early versions of EE +### Removing version text -If the feature was created before GitLab 9.2 (before [different EE tiers were introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1851)): +Over time, version text will reference a progressively older version of GitLab. In cases where version text +refers to versions of GitLab more than two major versions back, consider removing the text. -- Declare it as "Introduced in GitLab Enterprise Edition X.Y". -- Note which tier the feature is available in. +For example, if the current major version is 11.x, version text referencing versions of GitLab 9.x +and older are candidates for removal. -For example: - -```md -> [Introduced]() in GitLab Enterprise Edition 9.0. Available in [GitLab Premium](https://about.gitlab.com/pricing/). -``` +NOTE: **Note:** +This guidance applies to any text that mentions a GitLab version, not just "Introduced in... " text. ## Product badges From f7be93a871b7050f1a88df6cf74a032c684f4f01 Mon Sep 17 00:00:00 2001 From: Evan Read Date: Mon, 21 Jan 2019 09:58:07 +1000 Subject: [PATCH 3/4] Adjust guidance based on feedback --- doc/development/documentation/styleguide.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 445f62b8d1a..19dd5b1153e 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -639,13 +639,14 @@ a helpful link back to how the feature was developed. ### Removing version text Over time, version text will reference a progressively older version of GitLab. In cases where version text -refers to versions of GitLab more than two major versions back, consider removing the text. +refers to versions of GitLab more than four major versions back, consider removing the text. -For example, if the current major version is 11.x, version text referencing versions of GitLab 9.x +For example, if the current major version is 11.x, version text referencing versions of GitLab 7.x and older are candidates for removal. NOTE: **Note:** This guidance applies to any text that mentions a GitLab version, not just "Introduced in... " text. +Other text includes deprecation notices and version-specific how-to information. ## Product badges From c15adde9542466fe3aafa91a14526e01aac361eb Mon Sep 17 00:00:00 2001 From: Evan Read Date: Thu, 2 May 2019 09:55:41 +1000 Subject: [PATCH 4/4] Final review feedback applied --- doc/development/documentation/styleguide.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 19dd5b1153e..5caca846cc9 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -621,8 +621,8 @@ a helpful link back to how the feature was developed. > Introduced in GitLab 11.3. ``` -- Whenever possible, version text should have a link to the issue, merge request, or epic - (in order or preference) that introduced the feature. For example: +- Whenever possible, version text should have a link to the issue, merge request, or epic that introduced the feature. + An issue is preferred over a merge request, and a merge request is preferred over an epic. For example: ```md > [Introduced]() in GitLab 11.3. @@ -639,7 +639,7 @@ a helpful link back to how the feature was developed. ### Removing version text Over time, version text will reference a progressively older version of GitLab. In cases where version text -refers to versions of GitLab more than four major versions back, consider removing the text. +refers to versions of GitLab four or more major versions back, consider removing the text. For example, if the current major version is 11.x, version text referencing versions of GitLab 7.x and older are candidates for removal.