paper_trail 8.1.2 → 9.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4d9e6729cf3633953e38a14daf62fbd663938de52a1d495cdcbc5b3b63a12c2
-  data.tar.gz: c12f82f3b75a454cfd55b389923859fe799128430f6eb541fb93e10b2dd00454
+  metadata.gz: 24616bf1e1df70302e7417a24d60141dc2a0d20f1c6e8ac3690dbd4abf890a82
+  data.tar.gz: 8f0ea37c0b65a0c15bfbf4096db430e81d848952f6d42ecbc09d5028fa042d3e
 SHA512:
-  metadata.gz: 14b592477bc7292c66c1791e0762e62b1a817ece28d44f5156f7c7242fb18e62b93ebbd92b0efd7172538184bae2aa0c9c914b59e3378b15b043748eefa1f340
-  data.tar.gz: b5b5352145cbb72c796234d4761a69141de72cb0ecd74f914b7082e318ea868185cabfee3df3f91d7c0f5f7ccad23e2d4cb3495f89c26500d5dd390a03131f11
+  metadata.gz: 109af4466c2f6a61b42633bb94e46909203252757d7864250dd8e62cddfe82ef317419fc5ad8f784eecb453af387a02242b643b58b8eadd5778ce1e64c4b56a3
+  data.tar.gz: b840ca06183ff5411b0dcc493c8bdbc8abaa94060d8dfccaf1b0cbd0bbf69cd4bda4c2a98e3bd406d4760317e9949c89e306bd7b54e676237b162f3721f30497

data/lib/generators/paper_trail/install_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rails/generators"
 require "rails/generators/active_record"
 

data/lib/paper_trail.rb

@@ -1,10 +1,26 @@
-require "active_support"
+# frozen_string_literal: true
+
+# AR does not require all of AS, but PT does. PT uses core_ext like
+# `String#squish`, so we require `active_support/all`. Instead of eagerly
+# loading all of AS here, we could put specific `require`s in only the various
+# PT files that need them, but this seems easier to troubleshoot, though it may
+# add a few milliseconds to rails boot time. If that becomes a pain point, we
+# can revisit this decision.
+require "active_support/all"
+
+# AR is required for, eg. has_paper_trail.rb, so we could put this `require` in
+# all of those files, but it seems easier to troubleshoot if we just make sure
+# AR is loaded here before loading *any* of PT. See discussion of
+# performance/simplicity tradeoff for activesupport above.
+require "active_record"
+
 require "request_store"
 require "paper_trail/cleaner"
 require "paper_trail/config"
 require "paper_trail/has_paper_trail"
 require "paper_trail/record_history"
 require "paper_trail/reifier"
+require "paper_trail/request"
 require "paper_trail/version_association_concern"
 require "paper_trail/version_concern"
 require "paper_trail/version_number"
@@ -31,124 +47,158 @@ module PaperTrail
   class << self
     # @api private
     def clear_transaction_id
-      self.transaction_id = nil
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.clear_transaction_id is deprecated, " \
+        "use PaperTrail.request.clear_transaction_id",
+        caller(1)
+      )
+      request.clear_transaction_id
     end
 
-    # Switches PaperTrail on or off.
+    # Switches PaperTrail on or off, for all threads.
     # @api public
     def enabled=(value)
       PaperTrail.config.enabled = value
     end
 
-    # Returns `true` if PaperTrail is on, `false` otherwise.
-    # PaperTrail is enabled by default.
+    # Returns `true` if PaperTrail is on, `false` otherwise. This is the
+    # on/off switch that affects all threads. Enabled by default.
     # @api public
     def enabled?
       !!PaperTrail.config.enabled
     end
 
-    # Sets whether PaperTrail is enabled or disabled for the current request.
-    # @api public
+    # @deprecated
     def enabled_for_controller=(value)
-      paper_trail_store[:request_enabled_for_controller] = value
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.enabled_for_controller= is deprecated, " \
+        "use PaperTrail.request.enabled=",
+        caller(1)
+      )
+      request.enabled = value
     end
 
-    # Returns `true` if PaperTrail is enabled for the request, `false` otherwise.
-    #
-    # See `PaperTrail::Rails::Controller#paper_trail_enabled_for_controller`.
-    # @api public
+    # @deprecated
     def enabled_for_controller?
-      !!paper_trail_store[:request_enabled_for_controller]
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.enabled_for_controller? is deprecated, " \
+        "use PaperTrail.request.enabled?",
+        caller(1)
+      )
+      request.enabled?
     end
 
-    # Sets whether PaperTrail is enabled or disabled for this model in the
-    # current request.
-    # @api public
+    # @deprecated
     def enabled_for_model(model, value)
-      paper_trail_store[:"enabled_for_#{model}"] = value
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.enabled_for_model is deprecated, " \
+        "use PaperTrail.request.enabled_for_model",
+        caller(1)
+      )
+      request.enabled_for_model(model, value)
     end
 
-    # Returns `true` if PaperTrail is enabled for this model in the current
-    # request, `false` otherwise.
-    # @api public
+    # @deprecated
     def enabled_for_model?(model)
-      !!paper_trail_store.fetch(:"enabled_for_#{model}", true)
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.enabled_for_model? is deprecated, " \
+        "use PaperTrail.request.enabled_for_model?",
+        caller(1)
+      )
+      request.enabled_for_model?(model)
     end
 
-    # Returns a `::Gem::Version`, convenient for comparisons. This is
+    # Returns PaperTrail's `::Gem::Version`, convenient for comparisons. This is
     # recommended over `::PaperTrail::VERSION::STRING`.
     # @api public
     def gem_version
       ::Gem::Version.new(VERSION::STRING)
     end
 
+    # Set variables for the current request, eg. whodunnit.
+    #
+    # All request-level variables are now managed here, as of PT 9. Having the
+    # word "request" right there in your application code will remind you that
+    # these variables only affect the current request, not all threads.
+    #
+    # Given a block, temporarily sets the given `options` and execute the block.
+    #
+    # Without a block, this currently just returns `PaperTrail::Request`.
+    # However, please do not use `PaperTrail::Request` directly. Currently,
+    # `Request` is a `Module`, but in the future it is quite possible we may
+    # make it a `Class`. If we make such a choice, we will not provide any
+    # warning and will not treat it as a breaking change. You've been warned :)
+    #
+    # @api public
+    def request(options = nil, &block)
+      if options.nil? && !block_given?
+        Request
+      else
+        Request.with(options, &block)
+        nil
+      end
+    end
+
     # Set the field which records when a version was created.
     # @api public
     def timestamp_field=(_field_name)
       raise(E_TIMESTAMP_FIELD_CONFIG)
     end
 
-    # Sets who is responsible for any changes that occur. You would normally use
-    # this in a migration or on the console, when working with models directly.
-    # In a controller it is set automatically to the `current_user`.
-    # @api public
+    # @deprecated
     def whodunnit=(value)
-      paper_trail_store[:whodunnit] = value
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.whodunnit= is deprecated, use PaperTrail.request.whodunnit=",
+        caller(1)
+      )
+      request.whodunnit = value
     end
 
-    # If nothing passed, returns who is reponsible for any changes that occur.
-    #
-    #   PaperTrail.whodunnit = "someone"
-    #   PaperTrail.whodunnit # => "someone"
-    #
-    # If value and block passed, set this value as whodunnit for the duration of the block
-    #
-    #   PaperTrail.whodunnit("me") do
-    #     puts PaperTrail.whodunnit # => "me"
-    #   end
-    #
-    # @api public
-    def whodunnit(value = nil)
-      if value
-        raise ArgumentError, "no block given" unless block_given?
-
-        previous_whodunnit = paper_trail_store[:whodunnit]
-        paper_trail_store[:whodunnit] = value
-
-        begin
-          yield
-        ensure
-          paper_trail_store[:whodunnit] = previous_whodunnit
-        end
-      elsif paper_trail_store[:whodunnit].respond_to?(:call)
-        paper_trail_store[:whodunnit].call
+    # @deprecated
+    def whodunnit(value = nil, &block)
+      if value.nil?
+        ::ActiveSupport::Deprecation.warn(
+          "PaperTrail.whodunnit is deprecated, use PaperTrail.request.whodunnit",
+          caller(1)
+        )
+        request.whodunnit
+      elsif block_given?
+        ::ActiveSupport::Deprecation.warn(
+          "Passing a block to PaperTrail.whodunnit is deprecated, " \
+          'use PaperTrail.request(whodunnit: "John") do .. end',
+          caller(1)
+        )
+        request(whodunnit: value, &block)
       else
-        paper_trail_store[:whodunnit]
+        raise ArgumentError, "Invalid arguments"
       end
     end
 
-    # Sets any information from the controller that you want PaperTrail to
-    # store.  By default this is set automatically by a before filter.
-    # @api public
+    # @deprecated
     def controller_info=(value)
-      paper_trail_store[:controller_info] = value
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.controller_info= is deprecated, use PaperTrail.request.controller_info=",
+        caller(1)
+      )
+      request.controller_info = value
     end
 
-    # Returns any information from the controller that you want
-    # PaperTrail to store.
-    #
-    # See `PaperTrail::Rails::Controller#info_for_paper_trail`.
-    # @api public
+    # @deprecated
     def controller_info
-      paper_trail_store[:controller_info]
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.controller_info is deprecated, use PaperTrail.request.controller_info",
+        caller(1)
+      )
+      request.controller_info
     end
 
-    # Getter and Setter for PaperTrail Serializer
+    # Set the PaperTrail serializer. This setting affects all threads.
     # @api public
     def serializer=(value)
       PaperTrail.config.serializer = value
     end
 
+    # Get the PaperTrail serializer used by all threads.
     # @api public
     def serializer
       PaperTrail.config.serializer
@@ -156,27 +206,29 @@ module PaperTrail
 
     # @api public
     def transaction?
-      ::ActiveRecord::Base.connection.open_transactions > 0
+      ::ActiveRecord::Base.connection.open_transactions.positive?
     end
 
-    # @api public
+    # @deprecated
     def transaction_id
-      paper_trail_store[:transaction_id]
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.transaction_id is deprecated without replacement.",
+        caller(1)
+      )
+      request.transaction_id
     end
 
-    # @api public
+    # @deprecated
     def transaction_id=(id)
-      paper_trail_store[:transaction_id] = id
-    end
-
-    # Thread-safe hash to hold PaperTrail's data. Initializing with needed
-    # default values.
-    # @api private
-    def paper_trail_store
-      RequestStore.store[:paper_trail] ||= { request_enabled_for_controller: true }
+      ::ActiveSupport::Deprecation.warn(
+        "PaperTrail.transaction_id= is deprecated without replacement.",
+        caller(1)
+      )
+      request.transaction_id = id
     end
 
-    # Returns PaperTrail's configuration object.
+    # Returns PaperTrail's global configuration object, a singleton. These
+    # settings affect all threads.
     # @api private
     def config
       @config ||= PaperTrail::Config.instance

data/lib/paper_trail/attribute_serializers/attribute_serializer_factory.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "paper_trail/type_serializers/postgres_array_serializer"
 
 module PaperTrail
@@ -7,7 +9,7 @@ module PaperTrail
     # replaces certain default Active Record serializers
     # with custom PaperTrail ones.
     module AttributeSerializerFactory
-      AR_PG_ARRAY_CLASS = "ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array".freeze
+      AR_PG_ARRAY_CLASS = "ActiveRecord::ConnectionAdapters::PostgreSQL::OID::Array"
 
       def self.for(klass, attr)
         active_record_serializer = klass.type_for_attribute(attr)

data/lib/paper_trail/attribute_serializers/cast_attribute_serializer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "paper_trail/attribute_serializers/attribute_serializer_factory"
 
 module PaperTrail

data/lib/paper_trail/attribute_serializers/object_attribute.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "paper_trail/attribute_serializers/cast_attribute_serializer"
 
 module PaperTrail

data/lib/paper_trail/attribute_serializers/object_changes_attribute.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "paper_trail/attribute_serializers/cast_attribute_serializer"
 
 module PaperTrail

data/lib/paper_trail/cleaner.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module PaperTrail
   # Utilities for deleting version records.
   module Cleaner

data/lib/paper_trail/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "singleton"
 require "paper_trail/serializers/yaml"
 
@@ -5,9 +7,26 @@ module PaperTrail
   # Global configuration affecting all threads. Some thread-specific
   # configuration can be found in `paper_trail.rb`, others in `controller.rb`.
   class Config
+    DPR_TRACK_ASSOC = <<~STR
+      Association tracking is an endangered feature. For the past three or four
+      years it has been an experimental feature, not recommended for production.
+      It has a long list of known issues
+      (https://github.com/airblade/paper_trail#4b1-known-issues) and has no
+      regular volunteers caring for it.
+
+      If you don't use this feature, I strongly recommend disabling it.
+
+      If you do use this feature, please head over to
+      https://github.com/airblade/paper_trail/issues/1070 and volunteer to work
+      on the known issues.
+
+      If we can't make a serious dent in the list of known issues over the next
+      few years, then I'm inclined to delete it, though that would make me sad
+      because I've put dozens of hours into it, and I know others have too.
+    STR
+
     include Singleton
     attr_accessor :serializer, :version_limit
-    attr_writer :track_associations
 
     def initialize
       # Variables which affect all threads, whose access is synchronized.
@@ -18,18 +37,24 @@ module PaperTrail
       @serializer = PaperTrail::Serializers::YAML
     end
 
-    # Previously, we checked `PaperTrail::VersionAssociation.table_exists?`
+    def track_associations=(value)
+      @track_associations = !!value
+      if @track_associations
+        ::ActiveSupport::Deprecation.warn(DPR_TRACK_ASSOC, caller(1))
+      end
+    end
+
+    # As of PaperTrail 5, `track_associations?` defaults to false. Tracking
+    # associations is an experimental feature so we recommend setting
+    # PaperTrail.config.track_associations = false in your
+    # config/initializers/paper_trail.rb
+    #
+    # In PT 4, we checked `PaperTrail::VersionAssociation.table_exists?`
     # here, but that proved to be problematic in situations when the database
     # connection had not been established, or when the database does not exist
     # yet (as with `rake db:create`).
     def track_associations?
       if @track_associations.nil?
-        ActiveSupport::Deprecation.warn <<-EOS.strip_heredoc.gsub(/\s+/, " ")
-          PaperTrail.config.track_associations has not been set. As of PaperTrail 5, it
-          defaults to false. Tracking associations is an experimental feature so
-          we recommend setting PaperTrail.config.track_associations = false in
-          your config/initializers/paper_trail.rb
-        EOS
         false
       else
         @track_associations

data/lib/paper_trail/frameworks/active_record.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # This file only needs to be loaded if the gem is being used outside of Rails,
 # since otherwise the model(s) will get loaded in via the `Rails::Engine`.
 require "paper_trail/frameworks/active_record/models/paper_trail/version_association"

data/lib/paper_trail/frameworks/active_record/models/paper_trail/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "paper_trail/version_concern"
 
 module PaperTrail

data/lib/paper_trail/frameworks/active_record/models/paper_trail/version_association.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "paper_trail/version_association_concern"
 
 module PaperTrail

data/lib/paper_trail/frameworks/cucumber.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 # before hook for Cucumber
 Before do
   PaperTrail.enabled = false
-  PaperTrail.enabled_for_controller = true
-  PaperTrail.whodunnit = nil
-  PaperTrail.controller_info = {} if defined? Rails
+  PaperTrail.request.enabled = true
+  PaperTrail.request.whodunnit = nil
+  PaperTrail.request.controller_info = {} if defined?(::Rails)
 end
 
 module PaperTrail