From 5ee1d43e531e8fb8da654989be3167bc2640ba73 Mon Sep 17 00:00:00 2001
From: Marcel Amirault <mamirault@gitlab.com>
Date: Fri, 9 Feb 2024 16:27:29 +0000
Subject: [PATCH] Create breaking change warning for markdown anchors

---
 data/deprecations/16-9-markdown-anchors.yml | 26 +++++++++++++++++++++
 doc/update/deprecations.md                  | 23 ++++++++++++++++++
 2 files changed, 49 insertions(+)
 create mode 100644 data/deprecations/16-9-markdown-anchors.yml

diff --git a/data/deprecations/16-9-markdown-anchors.yml b/data/deprecations/16-9-markdown-anchors.yml
new file mode 100644
index 0000000000000..aa673a5302a7d
--- /dev/null
+++ b/data/deprecations/16-9-markdown-anchors.yml
@@ -0,0 +1,26 @@
+- title: "Autogenerated Markdown anchor links with dash (`-`) characters"
+  # The milestones for the deprecation announcement, and the removal.
+  removal_milestone: "17.0"
+  announcement_milestone: "16.9"
+  # Change breaking_change to false if needed.
+  breaking_change: true
+  # The stage and GitLab username of the person reporting the change,
+  # and a link to the deprecation issue
+  reporter: digitalmoksha
+  stage: plan
+  issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/440733
+  impact: low # Can be one of: [critical, high, medium, low]
+  scope: project # Can be one or a combination of: [instance, group, project]
+  resolution_role: Developer # Can be one of: [Admin, Owner, Maintainer, Developer]
+  manual_task: true # Can be true or false. Use this to denote whether a resolution action must be performed manually (true), or if it can be automated by using the API or other automation (false).
+  body: |  # (required) Don't change this line.
+    GitLab automatically creates anchor links for all headings, so you can link to
+    a specific place in a Markdown document or wiki page. But in some edge cases,
+    the autogenerated anchor is created with fewer dash (`-`) characters than many users expect.
+    For example, with a heading with `## Step - 1`, most other Markdown tools and linters would expect `#step---1`.
+    But GitLab generates an anchor of `#step-1`, with consecutive dashes compressed down to one.
+
+    In GitLab 17.0, we will align our autogenerated anchors to the industry standard by no longer stripping consecutive dashes.
+    If you have Markdown documents and link to headings that could have multiple dashes in 17.0,
+    you should update the heading to avoid this edge case. With the example above, you
+    can change `## Step - 1` to `## Step 1` to ensure in-page links continue to work.
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md
index 6ff2b1345f7f7..8f31a7bc1753f 100644
--- a/doc/update/deprecations.md
+++ b/doc/update/deprecations.md
@@ -317,6 +317,29 @@ Because Cloud Native Buildpacks do not support automatic testing, the Auto Test
 
 <div class="deprecation breaking-change" data-milestone="17.0">
 
+### Autogenerated Markdown anchor links with dash (`-`) characters
+
+<div class="deprecation-notes">
+- Announced in GitLab <span class="milestone">16.9</span>
+- Removal in GitLab <span class="milestone">17.0</span> ([breaking change](https://docs.gitlab.com/ee/update/terminology.html#breaking-change))
+- To discuss this change or learn more, see the [deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/issues/440733).
+</div>
+
+GitLab automatically creates anchor links for all headings, so you can link to
+a specific place in a Markdown document or wiki page. But in some edge cases,
+the autogenerated anchor is created with fewer dash (`-`) characters than many users expect.
+For example, with a heading with `## Step - 1`, most other Markdown tools and linters would expect `#step---1`.
+But GitLab generates an anchor of `#step-1`, with consecutive dashes compressed down to one.
+
+In GitLab 17.0, we will align our autogenerated anchors to the industry standard by no longer stripping consecutive dashes.
+If you have Markdown documents and link to headings that could have multiple dashes in 17.0,
+you should update the heading to avoid this edge case. With the example above, you
+can change `## Step - 1` to `## Step 1` to ensure in-page links continue to work.
+
+</div>
+
+<div class="deprecation breaking-change" data-milestone="17.0">
+
 ### Block usage of ref and sha together in `GET /projects/:id/ci/lint`
 
 <div class="deprecation-notes">
-- 
GitLab