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.
REST API docs have a separate deprecation style. The GraphQL API has a separate deprecation process, and style for the deprecation reason.
Features not actively being developed
When a feature is no longer actively developed, but not deprecated, add the following note under the topic title and version history:
{{< alert type="note" >}}
This feature is not under active development, but
[community contributions](https://about.gitlab.com/community/contribute/) are welcome.
{{< /alert >}}
Deprecate a page or topic
To deprecate a page or topic:
Add
(deprecated)
after the title. Use a warningalert
to explain when it was deprecated, when it will be removed, and the replacement feature.title: Title (deprecated) --- {{< details >}} - Tier: Premium, Ultimate - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated {{< /details >}} {{< alert type="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. {{< /alert >}}
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.title: Title (deprecated) --- <!--- start_remove The following content will be removed on remove_date: 'YYYY-MM-DD' --> {{< details >}} - Tier: Premium, Ultimate - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated {{< /details >}} {{< alert type="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. {{< /alert >}} <!--- 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
details
andalert
shortcodes.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: Title (removed) --- {{< details >}} - Tier: Premium, Ultimate - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated {{< /details >}} 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
indocs-gitlab-com
to remove the page’s entry from the global navigation.Search the Deprecations and Removals page for links to the removed page. The links use full URLs like:
https://docs.gitlab.com/user/deprecated_page/
. 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
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
details
andalert
shortcodes.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.title: Title (removed) ---- <!--- start_remove The following content will be removed on remove_date: 'YYYY-MM-DD' --> {{< details >}} - Tier: Premium, Ultimate - Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated {{< /details >}} 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. The links use full URLs like:
https://docs.gitlab.com/user/deprecated_page/
. 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
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.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support