gitlab-org--gitlab-foss/doc/development/deprecation_guidelines/index.md

stage	group	info
none	unassigned	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments

Deprecation guidelines

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

Terminology

Deprecation:

• Feature not recommended for use.
• Development restricted to Priority 1 / Severity 1 bug fixes.
• Will be removed in a future major release.
• Begins after a deprecation announcement outlining an end-of-support date.
• Ends after the end-of-support date or removal date has passed.

End of Support:

• Feature usage strongly discouraged.
• No support or fixes provided.
• No longer tested internally.
• Will be removed in a future major release.
• Begins after an end-of-support date has passed.
• Ends after all relevant code has been removed.

Removal:

• Feature usage impossible.
• Happens in a major release in line with our semantic versioning policy.
• Begins after removal date has passed.

When can a feature be deprecated?

Deprecations should be announced on the Deprecated feature removal schedule.

For steps to create a deprecation entry, see Deprecations.

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

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:

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