| _go to_ | making a browser go to location | "navigate to", "open" |
| _go to_ | making a browser go to location | "navigate to", "open" |
## GitLab versions and tiers
## GitLab versions
Tagged and released versions of GitLab documentation are available:
To help users be aware of recent product improvements or additions, we add
GitLab version information to our documentation.
- In the [documentation archives](https://docs.gitlab.com/archives/).
The GitLab Technical Writing team determines which versions of GitLab's
- At the `/help` URL for any GitLab installation.
documentation to display on this site based on GitLab's
[Statement of Support](https://about.gitlab.com/support/statement-of-support.html#we-support-the-current-major-version-and-the-two-previous-major-versions).
The version introducing a new feature is added to the top of the topic in the
### View older GitLab documentation versions
documentation to provide a link back to how the feature was developed.
TIP: **Tip:**
If you're using an older version of GitLab whose version-specific information
Whenever you have documentation related to the `gitlab.rb` file, you're working
isn't available from `docs.gitlab.com`, use one of the following methods to view a
with a self-managed installation. The section or page is therefore likely to
tagged and released set of documentation for your installed version:
apply only to self-managed instances. If so, the relevant "`TIER` ONLY"
[Product badge](#product-badges) should be included at the highest applicable
- In the [documentation archives](https://docs.gitlab.com/archives/).
heading level.
- At the `/help` URL of your GitLab instance.
- In the documentation repository based on the respective branch (for example,
the [13.2 branch](https://gitlab.com/gitlab-org/gitlab/-/tree/13-2-stable-ee/doc)).
### Where to put version text
### Text for documentation requiring version text
When a feature is added or updated, you can include its version information
either as a **Version history** item or as an inline text reference.
When a feature is new or updated, you can add version information as a bulleted
Version text shouldn't include information about the tier in which the feature
item in the **Version history**, or as an inline reference with related text.
is available. This information is provided by the [product badge](#product-tier-badges)
displayed for the page or feature.
#### Version text in the **Version History**
#### Version text in the **Version History**
If all content in a section is related, add version text following the header for
If all content in a section is related, add version text following the header
the section. Each entry should be on a single line. To render correctly, it must be on its
for the section. The version information must be surrounded by blank lines, and
own line and surrounded by blank lines.
each entry should be on its own line.
Features should declare the GitLab version that introduced a feature in a blockquote
Add the version history information as a blockquote:
following the header:
```markdown
```markdown
## Feature name
## Feature name
...
@@ -1693,68 +1699,53 @@ following the header:
...
@@ -1693,68 +1699,53 @@ following the header:
This feature does something.
This feature does something.
```
```
Whenever possible, version text should have a link to the _completed_ issue,
Whenever possible, version text should have a link to the completed issue, merge
merge request, or epic that introduced the feature. An issue is preferred over
request, or epic that introduced the feature. An issue is preferred over a merge
a merge request, and a merge request is preferred over an epic. For example:
request, and a merge request is preferred over an epic. For example:
```markdown
```markdown
> [Introduced](<link-to-issue>) in GitLab 11.3.
> [Introduced](<link-to-issue>) in GitLab 11.3.
```
```
If the feature is only available in GitLab Enterprise Edition, mention
If you're adding information about new features or changes in a release, update
the [paid tier](https://about.gitlab.com/handbook/marketing/strategic-marketing/tiers/)
the blockquote to use a bulleted list:
the feature is available in:
```markdown
> [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3.
```
If listing information for multiple version as a feature evolves, add the
information to a block-quoted bullet list. For example:
```markdown
```markdown
> - [Introduced](<link-to-issue>) in GitLab 11.3.
> - [Introduced](<link-to-issue>) in GitLab 11.3.
> - Enabled by default in GitLab 11.4.
> - Enabled by default in GitLab 11.4.
```
```
If a feature is moved to another tier:
```markdown
> - [Introduced](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5.
> - [Moved](<link-to-issue>) to [GitLab Starter](https://about.gitlab.com/pricing/) in 11.8.
> - [Moved](<link-to-issue>) to GitLab Core in 12.0.
```
If a feature is deprecated, include a link to a replacement (when available):
If a feature is deprecated, include a link to a replacement (when available):
```markdown
```markdown
> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>).
> - [Deprecated](<link-to-issue>) in GitLab 11.3. Replaced by [meaningful text](<link-to-appropriate-documentation>).
```
```
You can also describe the replacement in surrounding text, if available.
You can also describe the replacement in surrounding text, if available. If the
deprecation isn't obvious in existing text, you may want to include a warning,
If the deprecation is not obvious in existing text, you may want to include a
such as:
warning such as:
```markdown
```markdown
DANGER: **Deprecated:**
DANGER: **Deprecated:**
This feature was [deprecated](link-to-issue) in GitLab 12.3
This feature was [deprecated](link-to-issue) in GitLab 12.3 and replaced by
and replaced by [Feature name](link-to-feature-documentation).
[Feature name](link-to-feature-documentation).
```
```
In the first major GitLab version after the feature was deprecated, be sure to
remove information about that deprecated feature.
#### Inline version text
#### Inline version text
If you're adding content to an existing topic, you can add version information
If you're adding content to an existing topic, you can add version information
inline with the existing text.
inline with the existing text.
In this case, add `([introduced/deprecated](<link-to-issue>) in GitLab X.X)`.
In this case, add `([introduced/deprecated](<link-to-issue>) in GitLab X.X)`.
If applicable, include the paid tier: `([introduced/deprecated](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4)`
Including the issue link is encouraged, but isn't a requirement. For example:
Including the issue link is encouraged, but isn't a requirement. For example:
```markdown
```markdown
The voting strategy (in GitLab 13.4 and later) requires
The voting strategy in GitLab 13.4 and later requires the primary and secondary
the primary and secondary voters to agree.
voters to agree.
```
```
#### End-of-life for features or products
#### End-of-life for features or products
...
@@ -1772,51 +1763,36 @@ This feature is in its end-of-life process. It is [deprecated](link-to-issue)
...
@@ -1772,51 +1763,36 @@ This feature is in its end-of-life process. It is [deprecated](link-to-issue)
for use in GitLab X.X, and is planned for [removal](link-to-issue) in GitLab X.X.
for use in GitLab X.X, and is planned for [removal](link-to-issue) in GitLab X.X.
```
```
After the feature or product is officially deprecated and removed, remove
information about the product or feature from the GitLab documentation based on
the GitLab version where it's actually removed.
### Versions in the past or future
### Versions in the past or future
When describing functionality available in past or future versions, use:
When describing functionality available in past or future versions, use:
-_Earlier_, and not _older_ or _before_.
-Earlier, and not older or before.
-_Later_, and not _newer_ or _after_.
-Later, and not newer or after.
For example:
For example:
- Available in GitLab 12.3 and earlier.
- Available in GitLab 13.1 and earlier.
- Available in GitLab 12.4 and later.
- Available in GitLab 12.4 and later.
- In GitLab 11.4 and earlier, ...
- In GitLab 12.2 and earlier, ...
- In GitLab 10.6 and later, ...
- In GitLab 11.6 and later, ...
### Importance of referencing GitLab versions and tiers
Mentioning GitLab versions and tiers is important to all users and contributors
### Removing versions after each major release
to quickly have access to the issue or merge request that introduced the change.
Also, they can know what features they have in their GitLab
instance and version, given that the note has some key information.
`[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7`
Whenever a major GitLab release occurs, we will remove all version references
links to the issue that introduced the feature, says which GitLab tier it
to now-unsupported versions of GitLab. Note that this includes the removal of
belongs to, says the GitLab version that it became available in, and links to
specific instructions for users of non-supported GitLab versions. For example,
the pricing page in case the user wants to upgrade to a paid tier to use that
if we're currently supporting GitLab versions 11.x through 13.x, special
feature.
instructions for users of GitLab 10.2 and earlier to complete a task should be
removed.
For example, if you're a regular user and you're looking at the documentation
To view information about the history of a feature, users can view GitLab
for a feature you haven't used before, you can immediately see if that feature
[release posts](https://about.gitlab.com/releases/), or search for the issue or
is available to you or not. Alternatively, if you've been using a certain
merge request where the work was done.
feature for a long time and it changed in some way, it's important to be able to
determine when it changed and what's new in that feature.
This is even more important as we don't have a perfect process for shipping
documentation. Unfortunately, we still see features without documentation, and
documentation without features. So, for now, we cannot rely 100% on the
documentation site versions.
Over time, version text will reference a progressively older version of GitLab.
In cases where version text refers to versions of GitLab four or more major
versions back, you can consider removing the text if it's irrelevant or confusing.
For example, if the current major version is 12.x, version text referencing
versions of GitLab 8.x and older are candidates for removal if necessary for
clearer or cleaner documentation.
## Products and features
## Products and features
...
@@ -1846,7 +1822,7 @@ When entering a product or feature name that includes a space (such as
...
@@ -1846,7 +1822,7 @@ When entering a product or feature name that includes a space (such as
GitLab Community Edition), don't split the product or feature name across lines.
GitLab Community Edition), don't split the product or feature name across lines.
```
```
### Product badges
### Product tier badges
When a feature is available in paid tiers, add the corresponding tier to the
When a feature is available in paid tiers, add the corresponding tier to the
header or other page element according to the feature's availability:
header or other page element according to the feature's availability:
...
@@ -1872,6 +1848,11 @@ lowest tier that has information on the documentation page.
...
@@ -1872,6 +1848,11 @@ lowest tier that has information on the documentation page.
If sections of a page apply to higher tier levels, they can be separately
If sections of a page apply to higher tier levels, they can be separately
labeled with their own tier markup.
labeled with their own tier markup.
Whenever you have documentation related to the `gitlab.rb` file, you're working
with a self-managed installation. The section or page probably applies only to
self-managed instances. If so, include the relevant "`TIER` ONLY"
[product badge](#product-tier-badges) at the highest applicable heading level.
#### Product badge display behavior
#### Product badge display behavior
When using the tier markup with headers, the documentation page will display the
When using the tier markup with headers, the documentation page will display the
