Deprecating GitLab features

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

Breaking Change Policy

Any change counts as a breaking change if customers need to take action to ensure their GitLab workflows aren't disrupted.

A breaking change could come from sources such as:

• An intentional product change
• A configuration update
• A third-party deprecation
• Or many other sources

For many of our users, GitLab is a tier zero system. It is critical in creating, releasing, operating, and scaling users' businesses. The consequence of a breaking change can be serious.

Product and Engineering Managers are responsible and accountable for customer impacts due to the changes they make to the platform. The burden is on GitLab, not the customer, to own change management.

We aim to eliminate all breaking changes from GitLab. If you have exhausted the alternatives and believe you have a strong case for why a breaking change should be allowed, you can follow the process below to seek an exception.

How do I get approval to move forward with a breaking change?

By default, no breaking change is allowed unless the breaking change implementation plan has been granted explicit approval by following the process below.

1. Open an issue using the Breaking Change Exception template and fill in all of the required sections.
2. If your breaking change meets any of the below criteria, please call it out in the request. It doesn't guarantee the request will be approved but it helps make a good argument. Most breaking changes that are approved will fall into at least one of these categories:
   1. The impact of the breaking change has been fully mitigated via an automated migration that requires no action from the customer.
   2. The breaking change will have negligible customer impact as measured by actual product usage tracking across GitLab Self-Managed, GitLab.com, and GitLab Dedicated. For instance if it impacts less than 1% of the GitLab customer base.
   3. The breaking change is being implemented due to a significant security risk- Severity 1 or 2.
3. Once the issue is ready for review, follow the instructions in the template for who to tag to get the approval process started.
4. Wait until you get approval before publicly sharing the news or confirming your proposed timeline. The time from initial submission to approval or denial will vary, so submit a minimum of six months in advance of the proposed removal time frame.

What details are part of the request template?

• Executive Summary
• Impact Assessment
• Rollout & Communication Plan
  • Internal Communication
  • Customer Communication

Request template

After you have an approved breaking change, what's next?

1. Create a public deprecation issue that will serve as a source of truth for customers in regards to the change.
2. Ensure the change is added to the deprecations docs page by following the guidance below.
3. Follow the Rollout & Communications plan that was approved in your request.

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:

1. From the command line, go to your local clone of the gitlab-org/gitlab project.

2. Create, edit, or remove the YAML file under data/deprecations.

3. Compile the deprecations and removals documentation:

   shellCopy

   bin/rake gitlab:docs:compile_deprecations
   

4. If needed, you can verify the documentation is up to date with:

   shellCopy

   bin/rake gitlab:docs:check_deprecations
   

5. Commit the updated documentation and push the changes.

6. Create a merge request using the Deprecations and Removals template.

Related Handbook pages:

• https://handbook.gitlab.com/handbook/marketing/blog/release-posts/#deprecations-removals-and-breaking-changes
• https://handbook.gitlab.com/handbook/marketing/blog/release-posts/#update-the-deprecations-doc

Update the breaking change windows documentation

The breaking change windows documentation is generated from the YAML files located in gitlab/data/deprecations.

A deprecation is included in the breaking change windows page when all of the following are true:

• removal_milestone matches the target milestone (for example, 19.0).
• breaking_change is true.
• gitlab_com is not false. If the field is absent, it defaults to true. Set gitlab_com: false for breaking changes that do not affect GitLab.com (for example, changes that only affect self-managed instances).

Window assignment

All matching deprecations are assigned to the primary window by default, regardless of the window value in the YAML file.

A contingency window is available as a fallback. To move a breaking change to the contingency window, set window: 2 in its YAML file. The contingency window section is only shown on the page when at least one deprecation is assigned to it.

How to update the page

1. From the command line, go to your local clone of the gitlab-org/gitlab project.

2. Create, edit, or remove the YAML file under data/deprecations.

3. Compile the breaking change windows documentation:

   shellCopy

   bin/rake gitlab:docs:compile_windows
   

4. Update the deprecations documentation:

   shellCopy

   bin/rake gitlab:docs:compile_deprecations
   

5. If needed, you can verify the documentation is up to date with:

   shellCopy

   bin/rake gitlab:docs:check_windows
   

6. Commit the updated documentation and push the changes.

7. Create a merge request.

YAML fields used by the breaking change windows page

Field	Required	Description
title	Yes	The title that appears as a link to the deprecation item.
removal_milestone	Yes	Must match the target milestone.
breaking_change	Yes	Must be true.
gitlab_com	No	Set to false to exclude from the page. Defaults to true.
window	No	Set to 2 to assign to the contingency window. Any other value (or absent) assigns to the primary window.
impact	No	Shown in the table. Can be a string or array.
scope	No	Shown in the table. Can be a string or array.
check_impact	No	URL shown in the table. Only rendered if a value is present.

Update the related documentation

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

API deprecations and breaking changes

Our APIs have special rules regarding deprecations and breaking changes.

REST API v4

REST API v4 cannot have breaking changes made to it unless the API feature was previously marked as experimental or beta.

See What to do instead of a breaking change?

GraphQL API

The GraphQL API has a requirement for a longer deprecation cycle than the standard cycle before a breaking change can be made.

See the GraphQL deprecation process.

Webhook breaking changes

We cannot make breaking changes to webhook payloads.

For a list of what constitutes a breaking webhook payload change and what to do instead, see the Webhook breaking changes guide.

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.

Other guidelines

For configuration removals, see the Omnibus deprecation policy.

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