Fix compilation of deprecations doc, and test it in CI

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

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

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

@@ -147,6 +147,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}'
 
@@ -453,6 +460,12 @@
       changes: *docs-patterns
       when: on_success
 
+.docs:rules:deprecations:
+  rules:
+    - <<: *if-default-refs
+      changes: *docs-deprecations-patterns
+      when: on_success
+
 ##################
 # GraphQL rules  #
 ##################

data/deprecations/templates/_deprecation_template.md.erb

@@ -2,10 +2,9 @@
 stage: none
 group: none
 info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
-description: "View features that are currently deprecated"
 ---
 
-# Deprecated features by planned removal milestone
+# Deprecated feature removal schedule
 
 <!--
 This page is automatically generated from the YAML files in `/data/deprecations` by the rake task
@@ -16,15 +15,16 @@ Do not edit this page directly.
 To add a deprecation, use the example.yml file in `/data/deprecations/templates` as a template,
 then run `bin/rake gitlab:docs:compile_deprecations`.
 -->
+<% if milestones.any? %>
+  <%- milestones.each do |milestone| %>
+## <%= milestone %>
+    <%- deprecations.select{|d| d["removal_milestone"] == milestone}.each do |deprecation| %>
+### <%= deprecation["name"]%>
 
-<% if milestones.any? -%>
-  <% milestones.each do |milestone| %>
-### <%= milestone %>
-    <% deprecations.select{|d| d["removal_milestone"] == milestone}.each do |deprecation| %>
-#### <%= deprecation["name"] %>
-<%= deprecation["body"]%>
-    <% end %>
-  <% end %>
-<% else -%>
-## There are no deprecated features for this version of GitLab
+<%= deprecation["body"] -%>
+    <%- end -%>
+  <%- end -%>
+<%- else -%>
+
+Deprecated features scheduled for removal will be listed here, sorted by GitLab milestone.
 <% end -%>

data/deprecations/templates/example.yml

@@ -10,8 +10,8 @@
 #
 # Please delete this line and above before submitting your merge request.
 
-- name: # The name of the feature to be deprecated
-  removal_milestone: # XX.YY format - the milestone when this feature is planned to be removed
+- name: "Feature name" # The name of the feature to be deprecated
+  removal_milestone: "XX.YY" # the milestone when this feature is planned to be removed
   body: | # Do not modify this line, instead modify the lines below.
     <!-- START OF BODY COMMENT
 

doc/deprecations/index.md → doc/update/deprecations.md

@@ -2,10 +2,9 @@
 stage: none
 group: none
 info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"
-description: "View features that are currently deprecated"
 ---
 
-# Deprecated features by planned removal milestone
+# Deprecated feature removal schedule
 
 <!--
 This page is automatically generated from the YAML files in `/data/deprecations` by the rake task
@@ -17,4 +16,4 @@ To add a deprecation, use the example.yml file in `/data/deprecations/templates`
 then run `bin/rake gitlab:docs:compile_deprecations`.
 -->
 
-## There are no deprecated features for this version of GitLab
+Deprecated features scheduled for removal will be listed here, sorted by GitLab milestone.

lib/tasks/gitlab/docs/compile_deprecations.rake

@@ -4,28 +4,26 @@ namespace :gitlab do
   namespace :docs do
     desc "Generate deprecation list from individual files"
     task :compile_deprecations do
-      require_relative '../../../../tooling/deprecations/docs/renderer'
+      require_relative '../../../../tooling/deprecations/docs'
 
-      source_files = Rake::FileList.new("data/deprecations/**/*.yml") do |fl|
-        fl.exclude(/example\.yml/)
-      end
+      File.write(Deprecations::Docs.path, Deprecations::Docs.render)
 
-      deprecations = source_files.map do |file|
-        YAML.load_file(file)
+      puts "Deprecations compiled to #{Deprecations::Docs.path}"
     end
 
-      deprecations.sort_by! { |d| -d["removal_milestone"].to_f }
-
-      milestones = deprecations.map { |d| d["removal_milestone"].to_f }.uniq
+    desc "Check that the deprecation doc is up to date"
+    task :check_deprecations do
+      require_relative '../../../../tooling/deprecations/docs'
 
-      contents = Deprecations::Docs::Renderer
-        .render(deprecations: deprecations, milestones: milestones)
+      contents = Deprecations::Docs.render
+      doc = File.read(Deprecations::Docs.path)
 
-      File.write(
-        File.expand_path("doc/deprecations/index.md", "#{__dir__}/../../../.."),
-        contents)
-
-      puts "Deprecations compiled to doc/deprecations/index.md"
+      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`.')
+        abort
+      end
     end
   end
 end

tooling/deprecations/docs.rb

+# frozen_string_literal: true
+require 'erb'
+
+module Deprecations
+  module Docs
+    module_function
+
+    def path
+      Rails.root.join("doc/update/deprecations.md")
+    end
+
+    def render
+      deprecations_yaml_glob = Rails.root.join("data/deprecations/**/*.yml")
+
+      source_files = Rake::FileList.new(deprecations_yaml_glob) do |fl|
+        fl.exclude(/example\.yml$/)
+      end
+
+      deprecations = source_files.flat_map do |file|
+        YAML.load_file(file)
+      end
+
+      deprecations = VersionSorter.rsort(deprecations) { |d| d["removal_milestone"] }
+
+      milestones = deprecations.map { |d| d["removal_milestone"] }.uniq
+
+      template = Rails.root.join("data/deprecations/templates/_deprecation_template.md.erb")
+
+      load_template(template)
+        .result_with_hash(deprecations: deprecations, milestones: milestones)
+    end
+
+    def load_template(filename)
+      ERB.new(File.read(filename), trim_mode: '-')
+    end
+  end
+end

tooling/deprecations/docs/renderer.rb

-# frozen_string_literal: true
-require 'erb'
-
-module Deprecations
-  module Docs
-    module Renderer
-      module_function
-
-      def render(**variables)
-        template = File.expand_path("data/deprecations/templates/_deprecation_template.md.erb", "#{__dir__}/../../..")
-
-        load_template(template).result_with_hash(variables)
-      end
-
-      def load_template(filename)
-        ERB.new(File.read(filename), trim_mode: '-')
-      end
-    end
-  end
-end