• Deprecate a page or topic
• Remove a page
• Remove a topic
• Removing version-specific upgrade pages

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:

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:

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