Fixes #38410 - Add mechanism for deprecating displayed fields

doc/creating_commands.md

@@ -755,6 +755,35 @@ def adapter
 end
 ```
 
+#### Deprecating fields
+To deprecate a field, add `:deprecated => true` as an option for the field. This will print a warning message to stderr whenever the field is displayed. Consider removing this field from the default set so it is not displayed without a `--fields` param:
+
+```
+field :dep_fld, _("Deprecated field"), Fields::Field, :sets => ['ALL'], :deprecated => true
+```
+
+Example output:
+
+```
+$ hammer foo info --fields "Deprecated field"
+Warning: Field 'Deprecated field' is deprecated and may be removed in future versions.
+Deprecated field: bar
+```
+
+Additionally, a field may be 'replaced by' another field using `:replaced_by => "Path/To/New/Field"`. This will mark the field as deprecated and print a similar warning message to stderr whenever the field is displayed:
+
+```
+field :rep_fld, _("Replaced field"), Fields::Field, :sets => ['ALL'], :replaced_by => "Path/New field"
+```
+
+Example output:
+
+```
+$ hammer foo info --fields "Replaced field"
+Warning: Field 'Replaced field' is deprecated. Consider using 'Path/New field' instead.
+Replaced field: bar
+```
+
 #### Verbosity
 Currently Hammer [defines](https://github.com/theforeman/hammer-cli/blob/master/lib/hammer_cli/verbosity.rb) three basic verbose modes:
   * __QUIET__ - Prints nothing

lib/hammer_cli/output/adapter/base.rb

@@ -42,6 +42,12 @@ def render_fields(fields, data)
     end
 
     def render_field(field, data, label_width)
+      if field.replaced_by
+        warn "WARNING: Field '#{field.full_label}' is deprecated. Consider using '#{field.replaced_by}' instead."
+      elsif field.deprecated
+        warn "WARNING: Field '#{field.full_label}' is deprecated and may be removed in future versions."
+      end
+
       if field.is_a? Fields::ContainerField
         output = ""
 

lib/hammer_cli/output/fields.rb

@@ -4,14 +4,16 @@ module Fields
   class Field
     attr_reader :path
     attr_writer :sets
-    attr_accessor :label, :parent
+    attr_accessor :label, :parent, :replaced_by, :deprecated
 
     def initialize(options={})
       @hide_blank = options[:hide_blank].nil? ? false : options[:hide_blank]
       @hide_missing = options[:hide_missing].nil? ? true : options[:hide_missing]
       @path = options[:path] || []
       @label = options[:label]
       @sets = options[:sets]
+      @replaced_by = options[:replaced_by]
+      @deprecated = (options[:deprecated].nil?) ? !@replaced_by.nil? : options[:deprecated]
       @options = options
     end
 

test/unit/output/adapter/base_test.rb

@@ -28,6 +28,9 @@
     let(:blank)             { Fields::Field.new(:path => [:blank], :label => "Blank", :hide_blank => true) }
     let(:login)             { Fields::Field.new(:path => [:login], :label => "Login") }
     let(:missing)           { Fields::Field.new(:path => [:login], :label => "Missing", :hide_missing => false) }
+    let (:deprecated_a) { Fields::Field.new(:path => [:deprecated_a], :label => "Deprecated", :deprecated => true) }
+    let (:new_field) { Fields::Field.new(:path => [:new_field], :label => "New field") }
+    let (:deprecated_b) { Fields::Field.new(:path => [:deprecated_b], :label => "Replaced by", :replaced_by => 'New field') }
 
     let(:data) { HammerCLI::Output::RecordCollection.new [{
       :id => 112,
@@ -55,7 +58,10 @@
           :name => 'size',
           :value => '32'
         }
-      ]
+      ],
+      deprecated_a: 'deprecated_a',
+      deprecated_b: 'deprecated_b',
+      new_field: 'new_field'
     }]}
 
     it "should print one field" do
@@ -199,6 +205,31 @@
       _{ adapter.print_collection(fields, data) }.must_output(expected_output)
     end
 
+    it "should warn about deprecated fields" do
+      fields = [deprecated_a]
+
+      expected_stdout= [
+        "Deprecated: deprecated_a",
+        "\n"
+      ].join("\n")
+      expected_stderr = "WARNING: Field 'Deprecated' is deprecated and may be removed in future versions.\n"
+
+      _{ adapter.print_collection(fields, data) }.must_output(stdout=expected_stdout, stderr=expected_stderr)
+    end
+
+    it "should warn about replaced fields" do
+      fields = [new_field, deprecated_b]
+
+      expected_stdout= [
+        "New field:   new_field",
+        "Replaced by: deprecated_b",
+        "\n"
+      ].join("\n")
+      expected_stderr = "WARNING: Field 'Replaced by' is deprecated. Consider using 'New field' instead.\n"
+
+      _{ adapter.print_collection(fields, data) }.must_output(stdout=expected_stdout, stderr=expected_stderr)
+    end
+
     context 'printing by chunks' do
       let(:context) { { show_ids: true } }
       let(:collection_count) { 30 }