Merge pull request #676 from bugsnag/aliases

Deprecate and provide replacements for inconsistent methods

CHANGELOG.md

@@ -1,6 +1,20 @@
 Changelog
 =========
 
+## TBD
+
+### Deprecated
+
+* For consistency with Bugsnag notifiers for other languages, a number of methods have been deprecated in this release. The old options will be removed in the next major version | [#676](https://github.com/bugsnag/bugsnag-ruby/pull/676)
+    * The `notify_release_stages` configuration option has been deprecated in favour of `enabled_release_stages`
+    * The `auto_capture_sessions` and `track_sessions` configuration options have been deprecated in favour of `auto_track_sessions`
+    * The `Report` class has been deprecated in favour of the `Event` class
+    * The `Report#meta_data` attribute has been deprecated in favour of `Event#metadata`
+    * The `Breadcrumb#meta_data` attribute has been deprecated in favour of `Breadcrumb#metadata`
+    * The `Breadcrumb#name` attribute has been deprecated in favour of `Breadcrumb#message`
+    * The breadcrumb type constants in the `Bugsnag::Breadcrumbs` module has been deprecated in favour of the constants available in the `Bugsnag::BreadcrumbType` module
+    For example, `Bugsnag::Breadcrumbs::ERROR_BREADCRUMB_TYPE` is now available as `Bugsnag::BreadcrumbType::ERROR`
+
 ## v6.22.1 (11 August 2021)
 
 ### Fixes

features/fixtures/plain/app/app.rb

@@ -16,7 +16,7 @@ def configure_using_environment
     conf.auto_notify = ENV["BUGSNAG_AUTO_NOTIFY"] != "false"
     conf.ignore_classes << lambda { |ex| ex.class.to_s == ENV["BUGSNAG_IGNORE_CLASS"] } if ENV.include? "BUGSNAG_IGNORE_CLASS"
     conf.meta_data_filters << ENV["BUGSNAG_META_DATA_FILTERS"] if ENV.include? "BUGSNAG_META_DATA_FILTERS"
-    conf.notify_release_stages = [ENV["BUGSNAG_NOTIFY_RELEASE_STAGE"]] if ENV.include? "BUGSNAG_NOTIFY_RELEASE_STAGE"
+    conf.enabled_release_stages = [ENV["BUGSNAG_NOTIFY_RELEASE_STAGE"]] if ENV.include? "BUGSNAG_NOTIFY_RELEASE_STAGE"
     conf.project_root = ENV["BUGSNAG_PROJECT_ROOT"] if ENV.include? "BUGSNAG_PROJECT_ROOT"
     conf.proxy_host = ENV["BUGSNAG_PROXY_HOST"] if ENV.include? "BUGSNAG_PROXY_HOST"
     conf.proxy_password = ENV["BUGSNAG_PROXY_PASSWORD"] if ENV.include? "BUGSNAG_PROXY_PASSWORD"

features/fixtures/rails5/app/config/initializers/bugsnag.rb

@@ -7,14 +7,14 @@
   config.auto_notify = ENV["BUGSNAG_AUTO_NOTIFY"] != "false"
   config.project_root = ENV["BUGSNAG_PROJECT_ROOT"] if ENV.include? "BUGSNAG_PROJECT_ROOT"
   config.ignore_classes << lambda { |ex| ex.class.to_s == ENV["BUGSNAG_IGNORE_CLASS"] } if ENV.include? "BUGSNAG_IGNORE_CLASS"
-  config.auto_capture_sessions = ENV["BUGSNAG_AUTO_CAPTURE_SESSIONS"] == "true" unless ENV["USE_DEFAULT_AUTO_CAPTURE_SESSIONS"] == "true"
+  config.auto_track_sessions = ENV["BUGSNAG_AUTO_CAPTURE_SESSIONS"] == "true" unless ENV["USE_DEFAULT_AUTO_CAPTURE_SESSIONS"] == "true"
   config.send_code = ENV["BUGSNAG_SEND_CODE"] != "false"
   config.send_environment = ENV["BUGSNAG_SEND_ENVIRONMENT"] == "true"
   config.meta_data_filters << 'filtered_parameter'
 
   if ENV["SQL_ONLY_BREADCRUMBS"] == "true"
     config.before_breadcrumb_callbacks << Proc.new do |breadcrumb|
-      breadcrumb.ignore! unless breadcrumb.meta_data[:event_name] == "sql.active_record" && breadcrumb.meta_data[:name] == "User Load"
+      breadcrumb.ignore! unless breadcrumb.metadata[:event_name] == "sql.active_record" && breadcrumb.metadata[:name] == "User Load"
     end
   end
 

lib/bugsnag.rb

@@ -5,6 +5,7 @@
 require "bugsnag/configuration"
 require "bugsnag/meta_data"
 require "bugsnag/report"
+require "bugsnag/event"
 require "bugsnag/cleaner"
 require "bugsnag/helpers"
 require "bugsnag/session_tracker"
@@ -28,6 +29,7 @@
 require "bugsnag/middleware/classify_error"
 require "bugsnag/middleware/delayed_job"
 
+require "bugsnag/breadcrumb_type"
 require "bugsnag/breadcrumbs/validator"
 require "bugsnag/breadcrumbs/breadcrumb"
 require "bugsnag/breadcrumbs/breadcrumbs"
@@ -237,7 +239,7 @@ def load_integration(integration)
     #
     # @param name [String] the main breadcrumb name/message
     # @param meta_data [Hash] String, Numeric, or Boolean meta data to attach
-    # @param type [String] the breadcrumb type, from Bugsnag::Breadcrumbs::VALID_BREADCRUMB_TYPES
+    # @param type [String] the breadcrumb type, see {Bugsnag::BreadcrumbType}
     # @param auto [Symbol] set to :auto if the breadcrumb is automatically created
     # @return [void]
     def leave_breadcrumb(name, meta_data={}, type=Bugsnag::Breadcrumbs::MANUAL_BREADCRUMB_TYPE, auto=:manual)

lib/bugsnag/breadcrumb_type.rb

@@ -0,0 +1,14 @@
+require "bugsnag/breadcrumbs/breadcrumbs"
+
+module Bugsnag
+  module BreadcrumbType
+    ERROR = Bugsnag::Breadcrumbs::ERROR_BREADCRUMB_TYPE
+    LOG = Bugsnag::Breadcrumbs::LOG_BREADCRUMB_TYPE
+    MANUAL = Bugsnag::Breadcrumbs::MANUAL_BREADCRUMB_TYPE
+    NAVIGATION = Bugsnag::Breadcrumbs::NAVIGATION_BREADCRUMB_TYPE
+    PROCESS = Bugsnag::Breadcrumbs::PROCESS_BREADCRUMB_TYPE
+    REQUEST = Bugsnag::Breadcrumbs::REQUEST_BREADCRUMB_TYPE
+    STATE = Bugsnag::Breadcrumbs::STATE_BREADCRUMB_TYPE
+    USER = Bugsnag::Breadcrumbs::USER_BREADCRUMB_TYPE
+  end
+end

lib/bugsnag/breadcrumbs/breadcrumb.rb

@@ -1,11 +1,13 @@
 module Bugsnag::Breadcrumbs
   class Breadcrumb
+    # @deprecated Use {#message} instead
     # @return [String] the breadcrumb name
     attr_accessor :name
 
     # @return [String] the breadcrumb type
     attr_accessor :type
 
+    # @deprecated Use {#metadata} instead
     # @return [Hash, nil] metadata hash containing strings, numbers, or booleans, or nil
     attr_accessor :meta_data
 
@@ -23,7 +25,7 @@ class Breadcrumb
     # @api private
     #
     # @param name [String] the breadcrumb name
-    # @param type [String] the breadcrumb type from Bugsnag::Breadcrumbs::VALID_BREADCRUMB_TYPES
+    # @param type [String] the breadcrumb type from Bugsnag::BreadcrumbType
     # @param meta_data [Hash, nil] a hash containing strings, numbers, or booleans, or nil
     # @param auto [Symbol] set to `:auto` if the breadcrumb is automatically generated
     def initialize(name, type, meta_data, auto)
@@ -72,5 +74,36 @@ def to_h
         :timestamp => @timestamp.iso8601(3)
       }
     end
+
+    # TODO: "message" and "metadata" can be simple attr_accessors when they
+    #       replace "name" and "meta_data"
+    # NOTE: these are not aliases as YARD doesn't allow documenting the non-alias
+    #       as deprecated without also marking the alias as deprecated
+
+    # The breadcrumb message
+    # @!attribute message
+    # @return [String]
+    def message
+      @name
+    end
+
+    # @param message [String]
+    # @return [void]
+    def message=(message)
+      @name = message
+    end
+
+    # A Hash containing arbitrary metadata associated with this breadcrumb
+    # @!attribute metadata
+    # @return [Hash, nil]
+    def metadata
+      @meta_data
+    end
+
+    # @param metadata [Hash, nil]
+    # @return [void]
+    def metadata=(metadata)
+      @meta_data = metadata
+    end
   end
 end

lib/bugsnag/breadcrumbs/breadcrumbs.rb

@@ -1,4 +1,5 @@
 module Bugsnag::Breadcrumbs
+  # @deprecated Use {Bugsnag::BreadcrumbType} instead
   VALID_BREADCRUMB_TYPES = [
     ERROR_BREADCRUMB_TYPE = "error",
     MANUAL_BREADCRUMB_TYPE = "manual",

lib/bugsnag/configuration.rb

@@ -24,6 +24,7 @@ class Configuration
     attr_accessor :release_stage
 
     # A list of which release stages should cause notifications to be sent
+    # @deprecated Use {#enabled_release_stages} instead
     # @return [Array<String>, nil]
     attr_accessor :notify_release_stages
 
@@ -104,6 +105,7 @@ class Configuration
     attr_accessor :discard_classes
 
     # Whether Bugsnag should automatically record sessions
+    # @deprecated Use {#auto_track_sessions} instead
     # @return [Boolean]
     attr_accessor :auto_capture_sessions
 
@@ -125,7 +127,8 @@ class Configuration
     attr_reader :enable_sessions
 
     # A list of strings indicating allowable automatic breadcrumb types
-    # @see Bugsnag::Breadcrumbs::VALID_BREADCRUMB_TYPES
+    # @deprecated Use {#enabled_breadcrumb_types} instead
+    # @see Bugsnag::BreadcrumbType
     # @return [Array<String>]
     attr_accessor :enabled_automatic_breadcrumb_types
 
@@ -503,6 +506,51 @@ def remove_on_error(callback)
       middleware.remove(callback)
     end
 
+    # TODO: These methods can be a simple attr_accessor when they replace the
+    #       methods they are aliasing
+    # NOTE: they are not aliases as YARD doesn't allow documenting the non-alias
+    #       as deprecated without also marking the alias as deprecated
+
+    # A list of which release stages should cause notifications to be sent
+    # @!attribute enabled_release_stages
+    # @return [Array<String>, nil]
+    def enabled_release_stages
+      @notify_release_stages
+    end
+
+    # @param release_stages [Array<String>, nil]
+    # @return [void]
+    def enabled_release_stages=(release_stages)
+      @notify_release_stages = release_stages
+    end
+
+    # A list of breadcrumb types that Bugsnag will collect automatically
+    # @!attribute enabled_breadcrumb_types
+    # @see Bugsnag::BreadcrumbType
+    # @return [Array<String>]
+    def enabled_breadcrumb_types
+      @enabled_automatic_breadcrumb_types
+    end
+
+    # @param breadcrumb_types [Array<String>]
+    # @return [void]
+    def enabled_breadcrumb_types=(breadcrumb_types)
+      @enabled_automatic_breadcrumb_types = breadcrumb_types
+    end
+
+    # Whether sessions should be tracked automatically
+    # @!attribute auto_track_sessions
+    # @return [Boolean]
+    def auto_track_sessions
+      @auto_capture_sessions
+    end
+
+    # @param track_sessions [Boolean]
+    # @return [void]
+    def auto_track_sessions=(track_sessions)
+      @auto_capture_sessions = track_sessions
+    end
+
     private
 
     attr_writer :scopes_to_filter

lib/bugsnag/event.rb

@@ -0,0 +1,7 @@
+require "bugsnag/report"
+
+module Bugsnag
+  # For now Event is just an alias of Report. This points to the same object so
+  # any changes to Report will also affect Event
+  Event = Report
+end

lib/bugsnag/report.rb

@@ -72,6 +72,7 @@ class Report
     attr_accessor :grouping_hash
 
     # Arbitrary metadata attached to this report
+    # @deprecated Use {#metadata} instead
     # @return [Hash]
     attr_accessor :meta_data
 
@@ -257,6 +258,19 @@ def summary
       end
     end
 
+    # A Hash containing arbitrary metadata
+    # @!attribute metadata
+    # @return [Hash]
+    def metadata
+      @meta_data
+    end
+
+    # @param metadata [Hash]
+    # @return [void]
+    def metadata=(metadata)
+      @meta_data = metadata
+    end
+
     private
 
     def generate_exception_list

spec/breadcrumb_type_spec.rb

@@ -0,0 +1,23 @@
+require "spec_helper"
+
+require "bugsnag/breadcrumb_type"
+require "bugsnag/breadcrumbs/breadcrumbs"
+
+describe Bugsnag::BreadcrumbType do
+  it "contains constants equivalent to the breadcrumb types defined in Bugsnag::Breadcrumbs" do
+    expect(Bugsnag::BreadcrumbType::ERROR).to eq(Bugsnag::Breadcrumbs::ERROR_BREADCRUMB_TYPE)
+    expect(Bugsnag::BreadcrumbType::LOG).to eq(Bugsnag::Breadcrumbs::LOG_BREADCRUMB_TYPE)
+    expect(Bugsnag::BreadcrumbType::MANUAL).to eq(Bugsnag::Breadcrumbs::MANUAL_BREADCRUMB_TYPE)
+    expect(Bugsnag::BreadcrumbType::NAVIGATION).to eq(Bugsnag::Breadcrumbs::NAVIGATION_BREADCRUMB_TYPE)
+    expect(Bugsnag::BreadcrumbType::PROCESS).to eq(Bugsnag::Breadcrumbs::PROCESS_BREADCRUMB_TYPE)
+    expect(Bugsnag::BreadcrumbType::REQUEST).to eq(Bugsnag::Breadcrumbs::REQUEST_BREADCRUMB_TYPE)
+    expect(Bugsnag::BreadcrumbType::STATE).to eq(Bugsnag::Breadcrumbs::STATE_BREADCRUMB_TYPE)
+    expect(Bugsnag::BreadcrumbType::USER).to eq(Bugsnag::Breadcrumbs::USER_BREADCRUMB_TYPE)
+  end
+
+  it "defines the same number of breadcrumb type constants" do
+    old_types = Bugsnag::Breadcrumbs.constants.select { |type| type.to_s.end_with?("_BREADCRUMB_TYPE") }
+
+    expect(Bugsnag::BreadcrumbType.constants.length).to eq(old_types.length)
+  end
+end

spec/breadcrumbs/breadcrumb_spec.rb

@@ -10,6 +10,19 @@
       breadcrumb = Bugsnag::Breadcrumbs::Breadcrumb.new("my message", nil, nil, nil)
 
       expect(breadcrumb.name).to eq("my message")
+      expect(breadcrumb.message).to eq("my message")
+    end
+
+    it "can be accessed as #message" do
+      breadcrumb = Bugsnag::Breadcrumbs::Breadcrumb.new("my message", nil, nil, nil)
+
+      breadcrumb.message = "my other message"
+      expect(breadcrumb.message).to eq("my other message")
+      expect(breadcrumb.name).to eq("my other message")
+
+      breadcrumb.name = "another message"
+      expect(breadcrumb.message).to eq("another message")
+      expect(breadcrumb.name).to eq("another message")
     end
   end
 
@@ -26,6 +39,19 @@
       breadcrumb = Bugsnag::Breadcrumbs::Breadcrumb.new(nil, nil, {:a => 1, :b => 2}, nil)
 
       expect(breadcrumb.meta_data).to eq({:a => 1, :b => 2})
+      expect(breadcrumb.metadata).to eq({:a => 1, :b => 2})
+    end
+
+    it "can be accessed as #metadata" do
+      breadcrumb = Bugsnag::Breadcrumbs::Breadcrumb.new(nil, nil, { a: 1, b: 2 }, nil)
+
+      breadcrumb.metadata = { c: 3 }
+      expect(breadcrumb.meta_data).to eq({ c: 3 })
+      expect(breadcrumb.metadata).to eq({ c: 3 })
+
+      breadcrumb.meta_data = { d: 4 }
+      expect(breadcrumb.meta_data).to eq({ d: 4 })
+      expect(breadcrumb.metadata).to eq({ d: 4 })
     end
   end
 

spec/configuration_spec.rb

@@ -87,6 +87,22 @@
     end
   end
 
+  describe "#auto_track_sessions" do
+    it "defaults to true" do
+      expect(subject.auto_track_sessions).to eq(true)
+    end
+
+    it "shares a backing boolean with 'auto_capture_sessions'" do
+      subject.auto_track_sessions = false
+      expect(subject.auto_track_sessions).to eq(false)
+      expect(subject.auto_capture_sessions).to eq(false)
+
+      subject.auto_capture_sessions = true
+      expect(subject.auto_track_sessions).to eq(true)
+      expect(subject.auto_capture_sessions).to eq(true)
+    end
+  end
+
   describe "#enable_sessions" do
     it "defaults to true" do
       expect(subject.enable_sessions).to eq(true)
@@ -443,6 +459,29 @@ def debug(name, &block)
     end
   end
 
+  describe "#enabled_breadcrumb_types" do
+    it "defaults to Bugsnag::Breadcrumbs::VALID_BREADCRUMB_TYPES" do
+      expect(subject.enabled_breadcrumb_types).to eq(Bugsnag::Breadcrumbs::VALID_BREADCRUMB_TYPES)
+    end
+
+    it "is an editable array" do
+      subject.enabled_breadcrumb_types << "Some custom type"
+      expect(subject.enabled_breadcrumb_types).to include("Some custom type")
+    end
+
+    it "shares a backing array with 'enabled_automatic_breadcrumb_types'" do
+      expect(subject.enabled_breadcrumb_types).to be(subject.enabled_automatic_breadcrumb_types)
+
+      subject.enabled_breadcrumb_types = [1, 2, 3]
+      expect(subject.enabled_breadcrumb_types).to eq([1, 2, 3])
+      expect(subject.enabled_automatic_breadcrumb_types).to eq([1, 2, 3])
+
+      subject.enabled_automatic_breadcrumb_types = [4, 5, 6]
+      expect(subject.enabled_breadcrumb_types).to eq([4, 5, 6])
+      expect(subject.enabled_automatic_breadcrumb_types).to eq([4, 5, 6])
+    end
+  end
+
   describe "#before_breadcrumb_callbacks" do
     it "initially returns an empty array" do
       expect(subject.before_breadcrumb_callbacks).to eq([])