diff options
Diffstat (limited to 'doc/development/documentation/versions.md')
| -rw-r--r-- | doc/development/documentation/versions.md | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md new file mode 100644 index 00000000000..0f2bdca4c73 --- /dev/null +++ b/doc/development/documentation/versions.md @@ -0,0 +1,232 @@ +--- +info: For assistance with this Style Guide page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-other-projects-and-subjects. +stage: none +group: unassigned +description: 'Writing styles, markup, formatting, and other standards for GitLab Documentation.' +--- + +# Documenting product versions + +The GitLab product documentation includes version-specific information, +including when features were introduced and when they were updated or removed. + +## View older documentation versions + +Previous versions of the documentation are available on `docs.gitlab.com`. +To view a previous version, select the **Versions** button in the top right. + +To view versions that are not available on `docs.gitlab.com`: + +- View the [documentation archives](https://docs.gitlab.com/archives/). +- Go to the GitLab repository and select the version-specific branch. For example, + the [13.2 branch](https://gitlab.com/gitlab-org/gitlab/-/tree/13-2-stable-ee/doc) has the + documentation for GitLab 13.2. + +## Documenting version-specific features + +When a feature is added or updated, you can include its version information +either as a **Version history** bullet or as an inline text reference. + +You do not need to add version information on the pages in the `/development` directory. + +### Add a **Version history** item + +If all content in a topic is related, add a version history item after the topic heading. +For example: + +```markdown +## Feature name + +> [Introduced](<link-to-issue>) in GitLab 11.3. + +This feature does something. +``` + +The item text must include these words in order. Capitalization doesn't matter. + +- `introduced`, `enabled`, `deprecated`, `changed`, `moved`, `recommended`, `removed`, or `renamed` +- `in` or `to` +- `GitLab` + +If possible, include a link to the related issue, merge request, or epic. +Do not link to the pricing page. Do not include the subscription tier. + +#### Introducing a new feature + +If you use `introduced`, start the sentence with the feature name or a gerund: + +```markdown +> - Notifications for expiring tokens [introduced](<link-to-issue>) in GitLab 11.3. +> - Creating an issue from an issue board [introduced](<link-to-issue>) in GitLab 13.1. +``` + +#### Moving subscription tiers + +If a feature is moved to another subscription tier, use `moved`: + +```markdown +> - [Moved](<link-to-issue>) from GitLab Ultimate to GitLab Premium in 11.8. +> - [Moved](<link-to-issue>) from GitLab Premium to GitLab Free in 12.0. +``` + +### Inline version text + +If you're adding content to an existing topic, you can add version information +inline with the existing text. If possible, include a link to the related issue, +merge request, or epic. For example: + +```markdown +The voting strategy [in GitLab 13.4 and later](<link-to-issue>) requires the primary and secondary +voters to agree. +``` + +## Deprecations and removals + +When features are deprecated and removed, update the related documentation. + +API documentation follows these guidelines, but the GraphQL docs use +a [separate process](../api_graphql_styleguide.md#deprecating-schema-items). + +### Deprecate a page or topic + +To deprecate a page or topic: + +1. Add `(deprecated)` after the title. Use a warning to explain when it was deprecated, + when it will be removed, and the replacement feature. + + ```markdown + ## Title (deprecated) **(ULTIMATE SELF)** + + WARNING: + This feature was [deprecated](<link-to-issue>) in GitLab 14.8 + and is planned for removal in 15.4. Use [feature X](<link-to-issue>) instead. + ``` + + If you're not sure when the feature will be removed or no + replacement feature exists, you don't need to add this information. + +1. If the deprecation is a breaking change, add this text: + + ```markdown + This change is a breaking change. + ``` + + You can add any additional context-specific details that might help users. + +1. Open a merge request to add the word `(deprecated)` to the left nav, after the page title. + +### Remove a page + +Mark content as removed during the release the feature was removed. +The title and a removed indicator remains until three months after the removal. + +To remove a page: + +1. Leave the page title. Remove all other content, including the version history items and the word `WARNING:`. +1. After the title, change `(deprecated)` to `(removed)`. +1. Update the YAML metadata: + - For `remove_date`, set the value to a date three months after + the release when the feature was removed. + - For the `redirect_to`, set a path to a file that makes sense. If no obvious + page exists, use the docs home page. + + ```markdown + --- + stage: Enablement + group: Global Search + info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments + remove_date: '2022-08-02' + redirect_to: '../newpath/to/file/index.md' + --- + + # Title (removed) **(ULTIMATE SELF)** + + This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in GitLab 14.8 + and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in 15.0. + Use [feature X](<link-to-issue>) instead. + ``` + +1. Remove the page's entry from the global navigation by editing [`navigation.yaml`](https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml) in `gitlab-docs`. + +This content is removed from the documentation as part of the Technical Writing team's +[regularly scheduled tasks](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks). + +### Remove a topic + +To remove a topic: + +1. Leave the title and the details of the deprecation and removal. Remove all other content, + including the version history items and the word `WARNING:`. +1. Add `(removed)` after the title. +1. Add the following HTML comments above and below the topic. + For the `remove_date`, set a date three months after the release where it was removed. + + ```markdown + <!--- start_remove The following content will be removed on remove_date: '2023-08-22' --> + + ## Title (removed) **(ULTIMATE SELF)** + + This feature was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in GitLab 14.8 + and [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/351963) in 15.0. + Use [feature X](<link-to-issue>) instead. + + <!--- end_remove --> + ``` + +This content is removed from the documentation as part of the Technical Writing team's +[regularly scheduled tasks](https://about.gitlab.com/handbook/engineering/ux/technical-writing/#regularly-scheduled-tasks). + +## Which versions are removed + +GitLab supports the current major version and two previous major versions. +For example, if 14.0 is the current major version, all major and minor releases of +GitLab 14.0, 13.0 and 12.0 are supported. + +[View the list of supported versions](https://about.gitlab.com/support/statement-of-support.html#version-support). + +If you see version history items or inline text that refers to unsupported versions, you can remove it. + +Historical feature information is available in [release posts](https://about.gitlab.com/releases/) +or by searching for the issue or merge request where the work was done. + +## Promising features in future versions + +Do not promise to deliver features in a future release. For example, avoid phrases like, +"Support for this feature is planned." + +We cannot guarantee future feature work, and promises +like these can raise legal issues. Instead, say that an issue exists. +For example: + +- Support for improvements is tracked `[in this issue](LINK)`. +- You cannot do this thing, but `[an issue exists](LINK)` to change this behavior. + +You can say that we plan to remove a feature. + +### Legal disclaimer for future features + +If you **must** write about features we have not yet delivered, put this exact disclaimer near the content it applies to. + +```markdown +DISCLAIMER: +This page contains information related to upcoming products, features, and functionality. +It is important to note that the information presented is for informational purposes only. +Please do not rely on this information for purchasing or planning purposes. +As with all projects, the items mentioned on this page are subject to change or delay. +The development, release, and timing of any products, features, or functionality remain at the +sole discretion of GitLab Inc. +``` + +It renders on the GitLab documentation site as: + +DISCLAIMER: +This page contains information related to upcoming products, features, and functionality. +It is important to note that the information presented is for informational purposes only. +Please do not rely on this information for purchasing or planning purposes. +As with all projects, the items mentioned on this page are subject to change or delay. +The development, release, and timing of any products, features, or functionality remain at the +sole discretion of GitLab Inc. + +If all of the content on the page is not available, use the disclaimer once at the top of the page. + +If the content in a topic is not ready, use the disclaimer in the topic. |