Merge branch 'add-deprecation-docs' into 'master'

Add deprecations page in docs

See merge request gitlab-org/gitlab!66770

data/deprecations/templates/_deprecation_template.md.erb

+---
+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
+
+<!--
+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.
+
+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"] %>
+<%= deprecation["body"]%>
+    <% end %>
+  <% end %>
+<% else -%>
+## There are no deprecated features for this version of GitLab
+<% end -%>

data/deprecations/templates/example.yml

+# This is a template for a feature deprecation
+# A deprecation typically occurs when a feature or capability is planned to be removed in a future release.
+# Deprecations should be announced at least two releases prior to removal.  Any breaking changes should only be done in major releases.
+#
+# Below is an example of what a single entry should look like, it's required attributes,
+# and what types we expect those attribute values to be.
+#
+# For more information please refer to the handbook documentation here:
+# {{LINK TBD}}
+#
+# 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
+  body: | # Do not modify this line, instead modify the lines below.
+    <!-- START OF BODY COMMENT
+
+    This area supports markdown.
+
+    It is recommended to copy and paste the release post entry content here.
+
+    You can shorten it if needed, but remember that the entry itself has already been reviewed by Tech Writing so don't feel like you need to reword anything.
+
+    Delete this entire comment and replace it with your markdown content.
+
+    END OF BODY COMMENT -->
+  stage: # (optional - may be required in the future) String value of the stage that the feature was created in. e.g., Growth
+  tiers: # (optional - may be required in the future) An array of tiers that the feature is available in currently.  e.g., [Free, Silver, Gold, Core, Premium, Ultimate]
+  issue_url: # (optional) This is a link to the deprecation issue in GitLab
+  documentation_url: # (optional) This is a link to the current documentation page
+  image_url: # (optional) This is a link to a thumbnail image depicting the feature
+  video_url: # (optional) Use the youtube thumbnail URL with the structure of https://img.youtube.com/vi/UNIQUEID/hqdefault.jpg
+  announcement_milestone: # (optional - may be required in the future) XX.YY format - the milestone when this feature was first announced as deprecated
+  announcement_date: # (optional - may be required in the future) YYYY-MM-DD format - the date of the milestone release when this feature was first announced as deprecated
+  removal_date: # (optional - may be required in the future) YYYY-MM-DD format - the date of the milestone release when this feature is planned to be removed

doc/deprecations/index.md

+---
+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
+
+<!--
+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.
+
+To add a deprecation, use the example.yml file in `/data/deprecations/templates` as a template,
+then run `bin/rake gitlab:docs:compile_deprecations`.
+-->
+
+## There are no deprecated features for this version of GitLab

lib/tasks/gitlab/docs/compile_deprecations.rake

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