Remove the Removals page
This issue has tracked many changes and ideas. For now, it's primarily about the Removals page.
Proposal
Remove the Removals page and associated yaml files.
Right now, people don't understand that you need an entry on both the Deprecation and Removals pages, and the timing doesn't make sense. (You open a deprecation item now, but have to remember to open a removal item later.) Having two pages is also a source of confusion for customers.
When we make this change, we will also need to update:
- This tool
- The release post template, for past and for future releases:
- Deprecations should use the
announcement_milestone
(as they currently do) - Removals need to use the
removal_milestone
on the yaml files in the deprecations folder
- Deprecations should use the
We'll also need to update the handbook and potentially the release post template:
- https://about.gitlab.com/handbook/product/gitlab-the-product/#deprecations-removals-and-breaking-changes
- https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations-removals-and-breaking-changes
Other possible fixes to the deprecations/removals process
-
Instead of having writers, devs, and PMs run a script to generate a deprecations.md file, generate the page as part of the docs build. - ISSUE FOR THIS WORK: #1341
- Reason: This extra step requires you to pull the branch locally any time you want to make a small change to a deprecation notice. You must also have the right dependencies installed, and these dependencies can conflict with the GDK and docs site dependencies.
Other ideas
-
Use icon or badge to indicate breaking change. (Or otherwise de-emphasize the repetitive text)
- Reason: The giant orange box that's repeated again and again is distracting. And you can filter by breaking change. We just need some small indicator, maybe red circle with line through it, by items that are breaking. (With hover text)
-
Update title for page to
Release notes
or something that encompasses everything.- Reason: Similar to calling everything
changes
, we want this page to be the SSoT for important details for each release. (In addition to the release post.)
- Reason: Similar to calling everything
-
Change
removal_milestone
toeffective_milestone
. - This change is still being debated and can be addressed in a follow-up issue. For now, can update the yaml template to better explain what this milestone is.- Reason: Right now, we have deprecations, removals, and "important changes." When everything is on one page, we can consider everything that's there "a change that PM wants customers to know about." So rather than setting a date for "removing" a feature, let's tell customers when the change is effective. (This is just a simple name change.)
Done
This work was done as part of this effort:
- Sort the page by "Effective/removal" version, rather than "Announced in" version. (Going to use
GitLab x.y
instead ofRemoved in GitLab x.y
orChanged in GitLab x.y
)- Reason: The "announced in" information is on the release post. The docs are a view into the same information, but based on when the change takes effect. It's interesting to see when the change was announced, but it's more interesting to know when the change will affect you.
- The What's new since tool has been updated to not include the removals.
Handbook updates
As part of these changes, we need to update the pages that explain the process:
- https://about.gitlab.com/handbook/product/gitlab-the-product/#deprecations-removals-and-breaking-changes
- https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations-removals-and-breaking-changes
It might be good to put all of this information on its own page.
Also, this page needs a close edit: https://docs.gitlab.com/ee/development/deprecation_guidelines/
Release post automation
A script for creating the release post relies on specific markup in the page template. We'll need to make sure to test and adjust that when making any changes to the template. See gitlab-com/www-gitlab-com!124921 (merged).