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 Update the deprecations doc.

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?

Features or configuration can only be removed/changed in a major release.

They must 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.

Requesting a breaking change in a minor release

GitLab self-managed packages are semantically versioned and follow our maintenance policy. This process applies to features and APIs that are generally available, not beta or experimental.

This maintenance policy is in place to allow our customers to prepare for disruptive changes by establishing a clear and predictable pattern that is widely used in the software industry. For many of our customers, GitLab is a business-critical application and surprising changes can cause damages and erode trust.

Introducing breaking changes in minor releases is against policy because it can disrupt our customers and introduces an element of randomness that requires customers to check for breaking changes every minor release to ensure that their business is not impacted. This does not align with our goal to make it as easy as possible for customers to do business with GitLab and is strongly discouraged.

Breaking changes are deployed to GitLab.com after they are merged into the codebase and do not respect the minor release cadence. Special care must be taken to inform the Customer Support and Customer Success teams so that we can offer fast resolution to any customers that may be impacted by unexpected breaking changes.

Breaking our own policies, in particular shipping breaking changes in minor releases, is only reserved for situations in which GitLab establishes that delaying a breaking change would overall have a significantly more negative impact to customers than shipping it in a minor release. The most important lens for evaluating if an exception is granted is customer results.

Introducing a breaking change in a minor release requires a PM and EM to follow the process below to request an exception:

Open a new issue in the product issue tracker using the Breaking Change Exception template
Title should follow the format Breaking change exception: Description
Provide an impact assessment for the breaking change
1. How many customers are impacted?
2. Can we get the same outcome without a breaking-change? (i.e. no removal)
3. Can the breaking-change wait till the next major release, or the next scheduled upgrade stop, for example Database scenarios)?
4. What is the alternative for customers to do the same job the change will break?
5. How difficult is it for customers to migrate to the alternative? Is there a migration plan?
Provide a communication plan and establish a clear timeline, including the targeted minor release.
Notify Support and Customer Success so they can share information with relevant customers.
Obtain approval from the VP of Development, VP of Product Management, and VP of Customer Support for this area
Obtain approval from the CPO and CTO

Update the deprecations and removals documentation

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

To update the deprecations and removals page when a YAML file is added, edited, or removed:

From the command line, navigate to your local clone of the gitlab-org/gitlab project.
Create, edit, or remove the YAML file under data/deprecations.
Compile the deprecations and removals documentation:
```
bin/rake gitlab:docs:compile_deprecations
```
If needed, you can verify the docs are up to date with:
```
bin/rake gitlab:docs:check_deprecations
```
Commit the updated documentation and push the changes.
Create a merge request using the Deprecations and Removals template.

Related Handbook pages:

Update the related documentation

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