Consolidate the removals announcements into Docs
Problem statement
We have simplified the deprecations
workflow into Docs but we still have removals
being separately announced in the release post.
This leaves the workflow for announcing deprecations
and removals
in each milestone more complex than necessary. We should simplify by combining removals
into Docs as well.
Proposal
How this would work:
- PM/EM create raises an MR to add deprecations to Docs
- The YML file contains the following required fields:
-
breaking_change
(boolean, default: false) -
announcement_milestone
(string, "XX.X") -
announcement_date
(string, ISO format) -
removal_milestone
(string, "XX.X") -
removal_date
(string, ISO format)
-
- Milestones from 14.0 and on are displayed on the Deprecations page (currently the display shows only 14.5 and on)
- The
name
andbody
of a deprecation will be displayed in the milestone in which it was announced and in which it will be removed (currently, they are only displayed in the removal milestone). - Any deprecations with
breaking_change: true
will have an additional alert window beneath the title calling out the breaking change.
Outcome:
- PM/EM just create one deprecation MR and YML file, that they update/maintain as needed
- No longer a need to create a unique removals MR to announce a removal on the release post page
- The release post page will just point to Docs for both deprecations and removals
Tasks
-
Add a breaking_change field to the yaml template for deprecations - Default to
no
- If
yes
use the value ofremoval-milestone
field to know what milestone to mark as a breaking change
- Default to
-
Add a breaking_change field all existing deprecation files
-
Update the docs deprecations page - A single
.yml
file should be the SSOT for a feature’s- deprecation announcement
- removal announcement
- Whether or not it's a breaking change
- A single
-
Fix the docs deprecations page so that all 14.* deprecations and removals are displayed. In the meeting, we suspected some were missing from the output.
-
Update the www-gitlab-com
repo wherever necessary to describe the new process. -
Update the templates in the www-gitlab-com
repo, if necessary, to fix the checkboxes. (Check both the issue and MR templates just to be safe.)
Potential ideas for later iterations
-
Farnoosh asked if we could prevent files from being added to the folder without the rake task being run. She thinks Marcel (which? we have two) added such a task to the docs repo before, but it broke. - a filter on the deprecations page in the docs to only show deprecations / removals for a particular milestone (or major version?)
- when do we remove files from the data/deprecations folder on the docs site?
- do we have some kind of visual flag to mark breaking changes?
- the
bin/rake gitlab:docs:compile_deprecations
task really should emit output so we can tell if there are problems with any files
Related issues
- Related to #12760 (closed)
- Related to Product#3520 (closed)
Source materials
Taken from these notes from a meeting with @brhea, @fseifoddini, @aqualls.
Edited by Brian Rhea