Add back the CI job that makes sure deprecations doc is in sync

.gitlab/ci/docs.gitlab-ci.yml

@@ -76,3 +76,16 @@ ui-docs-links lint:
   needs: []
   script:
     - bundle exec haml-lint -i DocumentationLinks
+
+docs-lint deprecations:
+  variables:
+    SETUP_DB: "false"
+  extends:
+    - .default-retry
+    - .rails-cache
+    - .default-before_script
+    - .docs:rules:deprecations
+  stage: lint
+  needs: []
+  script:
+    - bundle exec rake gitlab:docs:check_deprecations

.gitlab/ci/rules.gitlab-ci.yml

@@ -165,6 +165,13 @@
   - ".markdownlint.yml"
   - "scripts/lint-doc.sh"
 
+.docs-deprecations-patterns: &docs-deprecations-patterns
+  - "doc/deprecations/index.md"
+  - "data/deprecations/*.yml"
+  - "data/deprecations/templates/_deprecation_template.md.erb"
+  - "lib/tasks/gitlab/docs/compile_deprecations.rake"
+  - "tooling/deprecations/docs.rb"
+
 .bundler-patterns: &bundler-patterns
   - '{Gemfile.lock,*/Gemfile.lock,*/*/Gemfile.lock}'
 
@@ -530,6 +537,11 @@
       changes: *docs-patterns
       when: on_success
 
+.docs:rules:deprecations:
+  rules:
+    - <<: *if-default-refs
+      changes: *docs-deprecations-patterns
+
 ##################
 # GraphQL rules  #
 ##################

data/deprecations/templates/_deprecation_template.md.erb

@@ -17,15 +17,23 @@ sole discretion of GitLab Inc.
 <!-- vale off -->
 
 <!--
+DO NOT EDIT THIS PAGE DIRECTLY
+
 This page is automatically generated from the YAML files in `/data/deprecations` by the rake task
 located at `lib/tasks/gitlab/docs/compile_deprecations.rake`.
 
-Do not edit this page directly.
+For deprecation authors (usually Product Managers and Engineering Managers):
+
+- To add a deprecation, use the example.yml file in `/data/deprecations/templates` as a template.
+- For more information about authoring deprecations, check the the deprecation item guidance:
+  https://about.gitlab.com/handbook/marketing/blog/release-posts/#creating-a-deprecation-entry
 
-To add a deprecation, use the example.yml file in `/data/deprecations/templates` as a template.
+For deprecation reviewers (Technical Writers only):
 
-To update this doc, run `bin/rake gitlab:docs:compile_deprecations`.
-To verify this doc is up to date, run `bin/rake gitlab:docs:check_deprecations`
+- To update the deprecation doc, run: `bin/rake gitlab:docs:compile_deprecations`
+- To verify the deprecations doc is up to date, run: `bin/rake gitlab:docs:check_deprecations`
+- For more information about updating the deprecation doc, see the deprecation doc update guidance:
+  https://about.gitlab.com/handbook/marketing/blog/release-posts/#update-the-deprecations-doc
 -->
 <% if milestones.any? -%>
   <%- milestones.each do |milestone| %>

doc/update/deprecations.md

@@ -17,15 +17,23 @@ sole discretion of GitLab Inc.
 <!-- vale off -->
 
 <!--
+DO NOT EDIT THIS PAGE DIRECTLY
+
 This page is automatically generated from the YAML files in `/data/deprecations` by the rake task
 located at `lib/tasks/gitlab/docs/compile_deprecations.rake`.
 
-Do not edit this page directly.
+For deprecation authors (usually Product Managers and Engineering Managers):
+
+- To add a deprecation, use the example.yml file in `/data/deprecations/templates` as a template.
+- For more information about authoring deprecations, check the the deprecation item guidance:
+  https://about.gitlab.com/handbook/marketing/blog/release-posts/#creating-a-deprecation-entry
 
-To add a deprecation, use the example.yml file in `/data/deprecations/templates` as a template.
+For deprecation reviewers (Technical Writers only):
 
-To update this doc, run `bin/rake gitlab:docs:compile_deprecations`.
-To verify this doc is up to date, run `bin/rake gitlab:docs:check_deprecations`
+- To update the deprecation doc, run: `bin/rake gitlab:docs:compile_deprecations`
+- To verify the deprecations doc is up to date, run: `bin/rake gitlab:docs:check_deprecations`
+- For more information about updating the deprecation doc, see the deprecation doc update guidance:
+  https://about.gitlab.com/handbook/marketing/blog/release-posts/#update-the-deprecations-doc
 -->
 
 ## 14.4

lib/tasks/gitlab/docs/compile_deprecations.rake

@@ -21,7 +21,7 @@ namespace :gitlab do
       if doc == contents
         puts "Deprecations doc is up to date."
       else
-        format_output('Deprecations doc is outdated! Please update it by running `bundle exec rake gitlab:docs:compile_deprecations`.')
+        format_output('Deprecations doc is outdated! You (or your technical writer) can update it by running `bin/rake gitlab:docs:compile_deprecations`.')
         abort
       end
     end