Skip to content

Announce deprecations in release-notes and collect and maintain deprecations in the docs

Related to: #2733 (closed) #2785 (closed) &1553

The problem:

The current deprecation/removal/breaking communication/process in the release post change is unclear, repetitive and error prone.

The solution:

As an effort to improve this experience for the next annual release, we will be adding deprecation notes to our Docs and link to it from the release post, so we can keep adding deprecation notices throughout all the milestones following the annual major release until the release of the next major release. Each release post will point to the deprecation page in the Docs. Removal, Breaking Changes, and Upgrades will remain in in the release post.

The benefit:

  • Make the PM release post process easier - since deprecation notices will be announced once and will remain in a dedicated section without the need to repeat the same post for 2 or more milestones
  • This will give our users an early notification of upcoming changes that they can proactively take action to fix
  • This will serve as a reminder (checklist) to make sure to remove the code when the next annual release comes

What the first iteration will look like:** @sam.white

  1. GitLab's documentation will become the Single Source of Truth for deprecations
  2. GitLab's documentation will have a new page that lists out all features that are currently deprecated but have not yet been removed from the product
  3. Release posts will include a static sentence with a link that points readers to view the deprecation page in the documentation for a complete list of features that are currently deprecated
  4. Release posts will include a list of features that are newly deprecated in the current milestone

Potential requirements for future iterations:

  1. Add a link to the Deprecation Issue for deprecation items on the deprecation page
  2. Add a link to documentation or migration instructions for deprecation items on the deprecation page
  3. Allow for better sorting/filtering/grouping of the deprecation items on the deprecation page

To Do:

Edited by Farnoosh Seifoddini