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.

Minimize the impact of breaking changes

Minimizing the impact to our customers ahead of a breaking change will ensure that disruptions will be minimized as much as possible. Product and Engineering teams should work closely together to understand 1) who would be most impacted and 2) whether tooling may help our users to migrate.

It is strongly recommended that teams create an issue to track the work for each of the following:

Measure product usage of the feature impacted by the breaking change.
Assess how many customers will be impacted by the breaking change.
Create tooling for users to manually migrate their own data or workflows.
Allow them to manually enable the breaking change so that they can control when it takes effect.
Automate the migration process as much as possible for users who do not take any manual steps to migrate.
(Optional) Create UI controls for instance admins to disable the breaking change, providing flexibility to Self-Managed / Dedicated customers to plan for their migration path. Optional as this depends on the breaking change.

Planning

Each breaking change should have a:

Rollout plan (DRI: Engineering)
- Is there a % roll out on GitLab.com?
- During that major milestone, when should the roll out begin?
Migration plan (DRI: Engineering)
- Are we instrumenting usage? If so, how are we using that data to inform what users will be impacted?
- How do we quickly and safely migrate them?
Communication plan (DRI: Product)
- Are customers aware of the upcoming changes?
- Do they know when the changes will go into effect?
- Do they know what actions to take?

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, go 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 documentation is 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 breaking change windows documentation

The breaking change windows documentation is generated based on the window value in the YAML files located in gitlab/data/deprecations.

To update the breaking change windows page when a YAML file is added, edited, or removed:

From the command line, go to your local clone of the gitlab-org/gitlab project.
Create, edit, or remove the YAML file under data/deprecations.
Compile the breaking change windows documentation:
```
bin/rake gitlab:docs:compile_windows
```
If needed, you can verify the documentation is up to date with:
```
bin/rake gitlab:docs:check_windows
```
Commit the updated documentation and push the changes.
Create a merge request.

Update the related documentation

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