## Problem statement As of [14.4 release post](https://about.gitlab.com/releases/2021/10/22/gitlab-14-4-released/#release-deprecations), we simplified the `deprecations` workflow into [Docs](https://docs.gitlab.com/ee/update/deprecations), which removed the manual and error-prone re-announcement process from the release post. But we still have `removals` being [separately announced on the release post page](https://about.gitlab.com/releases/2021/09/22/gitlab-14-3-released/#release-removals). This still leaves [the workflow](https://about.gitlab.com/handbook/marketing/blog/release-posts/#deprecations-removals-and-breaking-changes) for announcing `deprecations` and `removals` in each milestone more complex than necessary. The presentation to users is also disjointed/confusing, with `deprecations` in Docs, and `removals` on the release post page. ## Proposal We should simplify by combining `removals` into Docs as well. The yml deprecation file PMs create in their initial deprecation announcement can contain the information necessary for making the removal announcement. We'll upgrade the design of the Docs pages to clearly communicate `deprecations`, `removals`, and which are `breaking changes`. **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` and `body` 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 - Internal and external users will have one SSOT for reference, with a full history **Note:** We will also migrate any deprecations/removals 14.0 onward into Docs, so there is a clean transition point. 13.11 and earlier, deprecations/removals will remain in release posts. 14.0 onward, they're only in Docs and linked to from release post. **To be determined:** - Will deprecations and removals be on one or two Docs pages - How will full history be managed, e.g. do all deps/removals for 13.0 get their own Docs page, same with 14.0, and so on ## 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 https://gitlab.com/gitlab-com/www-gitlab-com/-/issues/12760 - Related to https://gitlab.com/gitlab-com/Product/-/issues/3520 ## Source materials Taken from [these notes](https://docs.google.com/document/d/10IZqk9zo3WvyV0Ue9HmpJUuPSZNXZqC_hWu2KzD9KH0/edit) from a meeting with @brhea, @fseifoddini, @aqualls ## Helpful References Upgrading GitLab versions: https://docs.gitlab.com/ee/update/#upgrade-paths