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. Remove the page’s entry from the global navigation by editing navigation.yaml in gitlab-docs.

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

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.