diff --git a/doc/development/backend/ruby_style_guide.md b/doc/development/backend/ruby_style_guide.md index 2db6ac0e69d33b8c802158d525e46b66683abe3f..d320a779cbfd81aeb16400c79a3bb6f78b1fa9e2 100644 --- a/doc/development/backend/ruby_style_guide.md +++ b/doc/development/backend/ruby_style_guide.md @@ -29,7 +29,7 @@ See also: These styles are not backed by a RuboCop rule. -For every style added to this section, link the discussion from the section's [version history note](../documentation/versions.md#add-a-version-history-item) to provide context and serve as a reference. +For every style added to this section, link the discussion from the section's [history note](../documentation/versions.md#add-a-history-item) to provide context and serve as a reference. ### Instance variable access using `attr_reader` diff --git a/doc/development/documentation/drawers.md b/doc/development/documentation/drawers.md index 1dfe50a8c00666aa36267592cd56a53c86a0a426..ae3d6e1e83d13117236d7872379b801e69f5b9ef 100644 --- a/doc/development/documentation/drawers.md +++ b/doc/development/documentation/drawers.md @@ -53,7 +53,7 @@ To create this content: - To link from the drawer to other content, use absolute URLs. - Do not include: - Tier badges - - Version history text + - History text - Alert boxes - Images - SVG icons diff --git a/doc/development/documentation/experiment_beta.md b/doc/development/documentation/experiment_beta.md index f6a518bd582ba3be9f33e5950e7fd402d540a681..c66604c9fb717c3748485ddd4d401da61fb2abef 100644 --- a/doc/development/documentation/experiment_beta.md +++ b/doc/development/documentation/experiment_beta.md @@ -13,7 +13,7 @@ When you document a feature in one of these three statuses: - Add the tier badge after the page or topic title. - Do not include `(Experiment)` or `(Beta)` in the left nav. -- Ensure the version history lists the feature's status. +- Ensure the history lists the feature's status. These features are usually behind a feature flag, which follow [these documentation guidelines](feature_flags.md). @@ -49,4 +49,4 @@ When the feature is ready for production, remove: description. - The feature flag information if available. -Ensure the version history is up-to-date by adding a note about the production release. +Ensure the history is up-to-date by adding a note about the production release. diff --git a/doc/development/documentation/feature_flags.md b/doc/development/documentation/feature_flags.md index 3b8311a2a6bb0c95a4a277a25c868b7d9e391e08..95c852d1ec93d7b0120848919767c297ec11b774 100644 --- a/doc/development/documentation/feature_flags.md +++ b/doc/development/documentation/feature_flags.md @@ -38,15 +38,15 @@ even when the feature is not fully functional or otherwise documented. When you document feature flags, you must: -- [Add version history text](#add-version-history-text). +- [Add history text](#add-history-text). - [Add a note at the start of the topic](#use-a-note-to-describe-the-state-of-the-feature-flag). -## Add version history text +## Add history text When the state of a flag changes (for example, disabled by default to enabled by default), add the change to the -[version history](versions.md#add-a-version-history-item). +[history](versions.md#add-a-history-item). -Possible version history entries are: +Possible history entries are: ```markdown > - [Introduced](issue-link) in GitLab X.X [with a flag](../../administration/feature_flags.md) named `flag_name`. Disabled by default. @@ -58,7 +58,7 @@ Possible version history entries are: ## Use a note to describe the state of the feature flag -Information about feature flags should be in a `FLAG` note at the start of the topic (just below the version history). +Information about feature flags should be in a `FLAG` note at the start of the topic (just below the history). The note has three parts, and follows this structure: @@ -117,7 +117,7 @@ an administrator can [enable the feature flag](../administration/feature_flags.m The feature is not ready for production use. ``` -When the feature is enabled in production, you can update the version history: +When the feature is enabled in production, you can update the history: ```markdown > - Introduced in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. @@ -137,9 +137,9 @@ And, when the feature is done and fully available to all users: > - [Generally available](issue-link) in GitLab 14.0. Feature flag `forti_token_cloud` removed. ``` -## Simplify long version history +## Simplify long history -The version history can get long, but you can sometimes simplify or remove entries. +The history can get long, but you can sometimes simplify or remove entries. Combine entries if they happened in the same release: diff --git a/doc/development/documentation/restful_api_styleguide.md b/doc/development/documentation/restful_api_styleguide.md index 012f385edc8d94b5e4b882e8e6157d3c37e78ef7..52b5a617f0b08f4315b8292ca5d0b2acca2405c5 100644 --- a/doc/development/documentation/restful_api_styleguide.md +++ b/doc/development/documentation/restful_api_styleguide.md @@ -47,13 +47,13 @@ required attributes first in the table. ````markdown ## API name -> - Version history note. +> - History note. One or two sentence description of what endpoint does. ### Method title -> - Version history note. +> - History note. Description of the method. @@ -95,12 +95,12 @@ Example response: ``` ```` -## Version history +## History -Add [version history](versions.md#documenting-version-specific-features) +Add [history](versions.md#documenting-version-specific-features) to describe new or updated API calls. -To add version history for an individual attribute, include it in the version history +To add history for an individual attribute, include it in the history for the section. For example: ```markdown @@ -110,7 +110,7 @@ for the section. For example: ``` If the API or attribute is deployed behind a feature flag, -[include the feature flag information](feature_flags.md) in the version history. +[include the feature flag information](feature_flags.md) in the history. ## Deprecations @@ -119,7 +119,7 @@ To document the deprecation of an API endpoint, follow the steps to To deprecate an attribute: -1. Add a version history note. +1. Add a history note. ```markdown > - `widget_name` [deprecated](<link-to-issue>) in GitLab 14.7. diff --git a/doc/development/documentation/styleguide/index.md b/doc/development/documentation/styleguide/index.md index fa483e349ff160a34a2dcd428cdb253c6aec94a1..228f679c487757d3089f7a36a9e2584b8ce7de7d 100644 --- a/doc/development/documentation/styleguide/index.md +++ b/doc/development/documentation/styleguide/index.md @@ -1680,7 +1680,7 @@ Some pages won't have a tier badge, because no obvious tier badge applies. For e Tier badges are how we refer to the information that's displayed under a topic title. -Tier badges include the tier, offering, status, and version history. +Tier badges include the tier, offering, status, and history. The Markdown for tier badges should look like the following: diff --git a/doc/development/documentation/versions.md b/doc/development/documentation/versions.md index 750817446d4d349305eb26cf1339e5fcf333042f..1adee1f0999edc03c8e24a63501557fbd96e22ec 100644 --- a/doc/development/documentation/versions.md +++ b/doc/development/documentation/versions.md @@ -24,14 +24,14 @@ To view versions that are not available on `docs.gitlab.com`: ## Documenting version-specific features -When a feature is added or updated, you can include its version information -either as a **Version history** list item or as an inline text reference. +When a feature is added or updated, update the documentation with +a **History** list item or as an inline text reference. -You do not need to add version information on the pages in the `/development` directory. +You do not need to add historical information on the pages in the `/development` directory. -### Add a **Version history** item +### Add a **History** item -If all content in a topic is related, add a version history item after the topic title. +If all content in a topic is related, add a history item after the topic title. For example: ```markdown @@ -89,9 +89,9 @@ If the feature status changes, use `changed`: When features are introduced behind feature flags, you must add details about the feature flag to the documentation. For more information, see [Document features deployed behind feature flags](feature_flags.md). -### Inline version text +### Inline history 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 historical information inline with the existing text. If possible, include a link to the related issue, merge request, or epic. For example: @@ -166,7 +166,7 @@ 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. Leave the page title. Remove all other content, including the 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 @@ -204,7 +204,7 @@ This content is removed from the documentation as part of the Technical Writing 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:`. + including the history items and the word `WARNING:`. 1. Add `(removed)` after the title. 1. Add the following HTML comments above and below the topic. For `remove_date`, set a date three months after the release where it was removed. @@ -236,9 +236,9 @@ GitLab 16.0, 15.0, and 14.0 are supported. [View the list of supported versions](https://about.gitlab.com/support/statement-of-support/#version-support). -If you see version history items or inline text that refers to unsupported versions, you can remove it. +If you see history items or inline text that refers to unsupported versions, you can remove it. -In the version history, remove information about [features behind feature flags](feature_flags.md) +In the history, remove information about [features behind feature flags](feature_flags.md) only if all events related to the feature flag happened in unsupported versions. If the flag hasn't been removed, readers should know when it was introduced. diff --git a/doc/development/import_export.md b/doc/development/import_export.md index 909c31c1b629e9081f9bce1973920165eb38a5a0..2da267d41dababa102349e3f31f7196b873a4d0d 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -105,7 +105,7 @@ module Gitlab module ImportExport extend self - # For every version update, the version history in import_export.md has to be kept up to date. + # For every version update, the history in import_export.md has to be kept up to date. VERSION = '0.2.4' ``` diff --git a/doc/update/background_migrations.md b/doc/update/background_migrations.md index 764748d1ba8612d17928c7a56de2673d76698002..d0d255d1c75ab92e72f05b2ffbc72f21fd8147c4 100644 --- a/doc/update/background_migrations.md +++ b/doc/update/background_migrations.md @@ -118,7 +118,7 @@ advanced users who understand the risks of doing so. WARNING: There can be [risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features). -Refer to each feature's version history for more details. +Refer to each feature's history for more details. To pause an ongoing batched background migration, [disable the batched background migrations feature](../development/database/batched_background_migrations.md#enable-or-disable-background-migrations). @@ -175,7 +175,7 @@ Use the following database queries to see the state of the current batched backg WARNING: There can be [risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features). -Refer to this feature's version history for more details. +Refer to this feature's history for more details. FLAG: On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../administration/feature_flags.md) named `optimize_batched_migrations`. @@ -191,7 +191,7 @@ To maximize throughput of batched background migrations (in terms of the number WARNING: There can be [risks when disabling released features](../administration/feature_flags.md#risks-when-disabling-released-features). -Refer to this feature's version history for more details. +Refer to this feature's history for more details. To speed up the execution of batched background migrations, two migrations are executed at the same time. diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index ca3a788f29fea06a76bcb3c6d801f8fdbde40618..42c0e1d48cd851d6b735e11765fb7f5722437b45 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -45,7 +45,7 @@ heading to toggle the list of the milestone bars. > - Filtering by group was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/385191) in GitLab 15.9. NOTE: -Filtering roadmaps by milestone might not be available to you. Be sure to review this section's version history for details. +Filtering roadmaps by milestone might not be available to you. Be sure to review this section's history for details. When you want to explore a roadmap, there are several ways to make it easier by sorting epics or filtering them by what's important for you.