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.

note
A separate process exists for GraphQL docs and REST API docs.

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. 

    ## 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.

  2. 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.

  3. 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 -->

  4. 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 history items and the word WARNING:.
  2. After the title, change (deprecated) to (removed).
  3. 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: Data Stores
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.
  4. Edit the navigation.yaml in gitlab-docs to remove the page’s entry from the global navigation.

  5. 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

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:

  1. Leave the title and the details of the deprecation and removal. Remove all other content, including the history items and the word WARNING:.
  2. Add (removed) after the title.

  3. 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 -->

  4. 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

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:

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.