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
@sam.white
What the first iteration will look like:**- GitLab's documentation will become the Single Source of Truth for deprecations
- 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
- 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
- Release posts will include a list of features that are newly deprecated in the current milestone
Potential requirements for future iterations:
- Add a link to the Deprecation Issue for deprecation items on the deprecation page
- Add a link to documentation or migration instructions for deprecation items on the deprecation page
- Allow for better sorting/filtering/grouping of the deprecation items on the deprecation page
To Do:
-
1 - gitlab-org/gitlab!66770 (merged) @sam.white @csouthard -
2 - gitlab-org/gitlab-docs!1989 (merged) @sam.white @csouthard -
3 - Add a CI job for generating the docs file @marcel.amirault (gitlab-org/gitlab!69358 (merged)) -
4 - www-gitlab-com!84265 (merged) @sam.white @csouthard -
5 - Write a script that the release post manager can run to bring deprecations over from docs @csouthard -
6 - Set up a sample environment showing how this will look in tandem with release post page @sam.white @csouthard and review with stakeholders @adawar @fseifoddini -
7 - Review deprecations issue template to add relevant updates @fseifoddini @DarrenEastman -
8 Sweep videos referenced in product handbook and update as needed in release post-GitLab the Product pages @DarrenEastman @fseifoddini -
9 - Conduct AMA for product managers, TWs and EMs and rollout out to team @sam.white @csouthard @fseifoddini -
10 - Add any necessary technical documentation to the handbook release post page @NicoleSchwartz @oregand
Edited by Farnoosh Seifoddini