Deprecations and removals
When GitLab deprecates or removes a feature, use the following process to update the documentation. This process requires temporarily changing content to be “deprecated” or “removed” before it’s deleted.
If a feature is not generally available, you can delete the content outright instead of following these instructions.
Deprecate a page or topic
To deprecate a page or topic:
-
Add
(deprecated)
after the title. Use a warning to explain when it was deprecated, when it will be removed, and the replacement feature.## Title (deprecated) DETAILS: **Tier:** Premium, Ultimate **Offering:** GitLab.com, Self-managed, GitLab Dedicated WARNING: This feature was [deprecated](https://issue-link) in GitLab 14.8 and is planned for removal in 15.4. Use [feature X](link-to-docs.md) 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.
-
If the deprecation is a breaking change, add this text:
This change is a breaking change.
You can add any additional context-specific details that might help users.
-
Add the following HTML comments above and below the content. For
remove_date
, set a date three months after the release where it will be removed.<!--- start_remove The following content will be removed on remove_date: 'YYYY-MM-DD' --> ## Title (deprecated) DETAILS: **Tier:** Premium, Ultimate **Offering:** GitLab.com, Self-managed, GitLab Dedicated WARNING: This feature was [deprecated](https://issue-link) in GitLab 14.8 and is planned for removal in 15.4. Use [feature X](link-to-docs.md) instead. <!--- end_remove -->
-
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:
- Leave the page title. Remove all other content, including the history items and the word
WARNING:
. - After the title, change
(deprecated)
to(removed)
. - 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.
--- stage: Foundations group: Global Search info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments remove_date: '2022-08-02' redirect_to: '../newpath/to/file/index.md' --- # Title (removed) DETAILS: **Tier:** Premium, Ultimate **Offering:** GitLab.com, Self-managed, GitLab Dedicated This feature was [deprecated](https://issue-link) in GitLab X.Y and [removed](https://issue-link) in X.Y. Use [feature X](link-to-docs.md) instead.
- For
- Edit the
navigation.yaml
ingitlab-docs
to remove the page’s entry from the global navigation. -
Search the Deprecations and Removals page for links to the removed page. These are full URLs like:
https://docs.gitlab.com/ee/user/deprecated_page.html
. If you find any links, update the relevant YAML files:- In the
body:
section, remove links to the removed page. - In the
documentation_url:
section, if the entry links to the page, delete the link. -
Run the Rake task to update the documentation:
bin/rake gitlab:docs:compile_deprecations
- In the
This content is removed from the documentation as part of the Technical Writing team’s regularly scheduled tasks.
Remove a topic
To remove a topic:
- Leave the title and the details of the deprecation and removal. Remove all other content,
including the history items and the word
WARNING:
. - Add
(removed)
after the title. -
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.<!--- start_remove The following content will be removed on remove_date: 'YYYY-MM-DD' --> ## Title (removed) DETAILS: **Tier:** Premium, Ultimate **Offering:** GitLab.com, Self-managed, GitLab Dedicated This feature was [deprecated](https://issue-link) in GitLab X.Y and [removed](https://issue-link) in X.Y. Use [feature X](link-to-docs.md) instead. <!--- end_remove -->
-
Search the Deprecations and Removals page for links to the removed page. These are full URLs like:
https://docs.gitlab.com/ee/user/deprecated_page.html
. If you find any links, update the relevant YAML files:- In the
body:
section, remove links to the removed page. - In the
documentation_url:
section, if the entry links to the page, delete the link. -
Run the Rake task to update the documentation:
bin/rake gitlab:docs:compile_deprecations
- In the
This content is removed from the documentation as part of the Technical Writing team’s regularly scheduled tasks.
Removing version-specific upgrade pages
Version-specific upgrade pages are in the doc/update/versions/
directory.
We don’t remove version-specific upgrade pages immediately for a major milestone. This gives users time to upgrade from older versions.
For example, doc/update/versions/14_changes.md
should
be removed during the .3
milestone. Therefore 14_changes.md
are
removed in GitLab 17.3.
Instead of removing the unsupported page:
- Add a note with a date three months in the future to ensure the page is removed during the monthly maintenance task.
- Do not add
Removed
to the title.
If the X_changes.md
page contains relative links to other sections
that are removed as part of the versions cleanup, the docs-lint links
job might fail. You can replace those relative links with an archived version.
Choose the latest minor version of the unsupported version to be removed.