Deprecating GitLab features

This page includes information about how and when to remove or make breaking changes to GitLab features.

For details about the terms used on this page, see the terminology.

When can a feature be deprecated?

Deprecations should be announced on the Deprecated feature removal schedule.

Deprecations should be announced no later than the third milestone preceding intended removal.

Do not include the deprecation announcement in the merge request that introduces a code change for the deprecation. Use a separate MR to create a deprecation entry. For steps to create a deprecation entry, see Deprecations.

Deprecation, End of Support, Removal process

How are Community Contributions to a deprecated feature handled?

Development on deprecated features is restricted to Priority 1 / Severity 1 bug fixes. Any community contributions to deprecated features are unlikely to be prioritized during milestone planning.

However, at GitLab, we give agency to our team members. So, a member of the team associated with the contribution may decide to review and merge it at their discretion.

When can a feature be removed/changed?

Generally, feature or configuration can be removed/changed only on major release. It also should be deprecated in advance.

For API removals, see the GraphQL and GitLab API guidelines.

For configuration removals, see the Omnibus deprecation policy.

For versioning and upgrade details, see our Release and Maintenance policy.

Update the deprecations and removals documentation pages

The deprecations and removals documentation is generated from the YAML files located in gitlab/data/.

To update the deprecations and removals pages when an entry is added, edited, or removed:

  1. From the command line, navigate to your local clone of the gitlab-org/gitlab project.
  2. Create, edit, or remove the YAML file under deprecations or removals.

  3. Compile the deprecation or removals documentation with the appropriate command:

    • For deprecations:

      bin/rake gitlab:docs:compile_deprecations

    • For removals:

      bin/rake gitlab:docs:compile_removals

  4. If needed, you can verify the docs are up to date with:

    • For deprecations:

      bin/rake gitlab:docs:check_deprecations

    • For removals:

      bin/rake gitlab:docs:check_removals
  5. Commit the updated documentation and push the changes.
  6. Create a merge request using the Deprecations or Removals templates.

Related Handbook pages:

When features are deprecated and removed, update the related documentation.