paper_trail 4.0.0 → 5.1.0

data/lib/paper_trail/config.rb

@@ -1,48 +1,64 @@
-require 'singleton'
-require 'paper_trail/serializers/yaml'
+require "singleton"
+require "paper_trail/serializers/yaml"
 
 module PaperTrail
+  # Global configuration affecting all threads. Some thread-specific
+  # configuration can be found in `paper_trail.rb`, others in `controller.rb`.
   class Config
     include Singleton
     attr_accessor :timestamp_field, :serializer, :version_limit
-    attr_reader :serialized_attributes
     attr_writer :track_associations
 
     def initialize
+      # Variables which affect all threads, whose access is synchronized.
+      @mutex = Mutex.new
+      @enabled = true
+
+      # Variables which affect all threads, whose access is *not* synchronized.
       @timestamp_field = :created_at
-      @serializer      = PaperTrail::Serializers::YAML
+      @serializer = PaperTrail::Serializers::YAML
+    end
 
-      # This setting only defaults to false on AR 4.2+, because that's when
-      # it was deprecated. We want it to function with older versions of
-      # ActiveRecord by default.
-      if ::ActiveRecord::VERSION::STRING < '4.2'
-        @serialized_attributes = true
-      end
+    def serialized_attributes
+      ActiveSupport::Deprecation.warn(
+        "PaperTrail.config.serialized_attributes is deprecated without " +
+          "replacement and always returns false."
+      )
+      false
     end
 
-    def serialized_attributes=(value)
-      if ::ActiveRecord::VERSION::MAJOR >= 5
-        ::ActiveSupport::Deprecation.warn(
-          "ActiveRecord 5.0 deprecated `serialized_attributes` "  +
-          "without replacement, so this PaperTrail config setting does " +
-          "nothing with this version, and is always turned off"
-        )
-      end
-      @serialized_attributes = value
+    def serialized_attributes=(_)
+      ActiveSupport::Deprecation.warn(
+        "PaperTrail.config.serialized_attributes= is deprecated without " +
+          "replacement and no longer has any effect."
+      )
     end
 
-    def track_associations
-      @track_associations ||= PaperTrail::VersionAssociation.table_exists?
+    # Previously, 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.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
+      end
     end
-    alias_method :track_associations?, :track_associations
 
-    # Indicates whether PaperTrail is on or off.
+    # Indicates whether PaperTrail is on or off. Default: true.
     def enabled
-      PaperTrail.paper_trail_store[:paper_trail_enabled].nil? || PaperTrail.paper_trail_store[:paper_trail_enabled]
+      @mutex.synchronize { !!@enabled }
     end
 
-    def enabled= enable
-      PaperTrail.paper_trail_store[:paper_trail_enabled] = enable
+    def enabled=(enable)
+      @mutex.synchronize { @enabled = enable }
     end
   end
 end

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

@@ -1,6 +1,10 @@
-require 'paper_trail/version_concern'
+require "paper_trail/version_concern"
 
 module PaperTrail
+  # This is the default ActiveRecord model provided by PaperTrail. Most simple
+  # applications will only use this and its partner, `VersionAssociation`, but
+  # it is possible to sub-class, extend, or even do without this model entirely.
+  # See the readme for details.
   class Version < ::ActiveRecord::Base
     include PaperTrail::VersionConcern
   end

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

@@ -1,7 +1,11 @@
-require 'paper_trail/version_association_concern'
+require "paper_trail/version_association_concern"
 
 module PaperTrail
+  # This is the default ActiveRecord model provided by PaperTrail. Most simple
+  # applications will only use this and its partner, `Version`, but it is
+  # possible to sub-class, extend, or even do without this model entirely.
+  # See the readme for details.
   class VersionAssociation < ::ActiveRecord::Base
     include PaperTrail::VersionAssociationConcern
   end
-end
+end

data/lib/paper_trail/frameworks/active_record.rb

@@ -1,4 +1,4 @@
-# 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`
+# 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"
 require "paper_trail/frameworks/active_record/models/paper_trail/version"

data/lib/paper_trail/frameworks/cucumber.rb

@@ -8,6 +8,7 @@ end
 
 module PaperTrail
   module Cucumber
+    # Helper method for enabling PT in Cucumber features.
     module Extensions
       # :call-seq:
       # with_versioning

data/lib/paper_trail/frameworks/rails/controller.rb

@@ -1,10 +1,27 @@
 module PaperTrail
   module Rails
+    # Extensions to rails controllers. Provides convenient ways to pass certain
+    # information to the model layer, with `controller_info` and `whodunnit`.
+    # Also includes a convenient on/off switch, `enabled_for_controller`.
     module Controller
-
       def self.included(base)
-        base.before_filter :set_paper_trail_enabled_for_controller
-        base.before_filter :set_paper_trail_whodunnit, :set_paper_trail_controller_info
+        before = [
+          :set_paper_trail_enabled_for_controller,
+          :set_paper_trail_controller_info
+        ]
+        after = [
+          :warn_about_not_setting_whodunnit
+        ]
+
+        if base.respond_to? :before_action
+          # Rails 4+
+          before.map { |sym| base.before_action sym }
+          after.map  { |sym| base.after_action  sym }
+        else
+          # Rails 3.
+          before.map { |sym| base.before_filter sym }
+          after.map  { |sym| base.after_filter  sym }
+        end
       end
 
       protected
@@ -36,43 +53,62 @@ module PaperTrail
       #
       # The columns `ip` and `user_agent` must exist in your `versions` # table.
       #
-      # Use the `:meta` option to `PaperTrail::Model::ClassMethods.has_paper_trail`
-      # to store any extra model-level data you need.
+      # Use the `:meta` option to
+      # `PaperTrail::Model::ClassMethods.has_paper_trail` to store any extra
+      # model-level data you need.
       def info_for_paper_trail
         {}
       end
 
-      # Returns `true` (default) or `false` depending on whether PaperTrail should
-      # be active for the current request.
+      # Returns `true` (default) or `false` depending on whether PaperTrail
+      # should be active for the current request.
       #
-      # Override this method in your controller to specify when PaperTrail should
-      # be off.
+      # Override this method in your controller to specify when PaperTrail
+      # should be off.
       def paper_trail_enabled_for_controller
         ::PaperTrail.enabled?
       end
 
       private
 
-      # Tells PaperTrail whether versions should be saved in the current request.
+      # Tells PaperTrail whether versions should be saved in the current
+      # request.
       def set_paper_trail_enabled_for_controller
         ::PaperTrail.enabled_for_controller = paper_trail_enabled_for_controller
       end
 
       # Tells PaperTrail who is responsible for any changes that occur.
       def set_paper_trail_whodunnit
+        @set_paper_trail_whodunnit_called = true
         ::PaperTrail.whodunnit = user_for_paper_trail if ::PaperTrail.enabled_for_controller?
       end
 
-      # Tells PaperTrail any information from the controller you want
-      # to store alongside any changes that occur.
+      # Tells PaperTrail any information from the controller you want to store
+      # alongside any changes that occur.
       def set_paper_trail_controller_info
         ::PaperTrail.controller_info = info_for_paper_trail if ::PaperTrail.enabled_for_controller?
       end
 
+      def warn_about_not_setting_whodunnit
+        enabled = ::PaperTrail.enabled_for_controller?
+        user_present = user_for_paper_trail.present?
+        whodunnit_blank = ::PaperTrail.whodunnit.blank?
+        if enabled && user_present && whodunnit_blank && !@set_paper_trail_whodunnit_called
+          ::Kernel.warn <<-EOS.strip_heredoc
+            user_for_paper_trail is present, but whodunnit has not been set.
+            PaperTrail no longer adds the set_paper_trail_whodunnit callback for
+            you. To continue recording whodunnit, please add this before_action
+            callback to your ApplicationController . For more information,
+            please see https://git.io/vrTsk
+          EOS
+        end
+      end
     end
   end
+end
 
-  if defined?(::ActionController)
-    ::ActiveSupport.on_load(:action_controller) { include PaperTrail::Rails::Controller }
+if defined?(::ActionController)
+  ::ActiveSupport.on_load(:action_controller) do
+    include ::PaperTrail::Rails::Controller
   end
 end

data/lib/paper_trail/frameworks/rails/engine.rb

@@ -1,7 +1,12 @@
 module PaperTrail
   module Rails
+    # See http://guides.rubyonrails.org/engines.html
     class Engine < ::Rails::Engine
-      paths['app/models'] << 'lib/paper_trail/frameworks/active_record/models'
+      paths["app/models"] << "lib/paper_trail/frameworks/active_record/models"
+      config.paper_trail = ActiveSupport::OrderedOptions.new
+      initializer "paper_trail.initialisation" do |app|
+        PaperTrail.enabled = app.config.paper_trail.fetch(:enabled, true)
+      end
     end
   end
 end

data/lib/paper_trail/frameworks/rails.rb

@@ -1,7 +1,2 @@
-require 'paper_trail/frameworks/rails/controller'
-require 'paper_trail/frameworks/rails/engine'
-
-module PaperTrail
-  module Rails
-  end
-end
+require "paper_trail/frameworks/rails/controller"
+require "paper_trail/frameworks/rails/engine"

data/lib/paper_trail/frameworks/rspec/helpers.rb

@@ -1,6 +1,7 @@
 module PaperTrail
   module RSpec
     module Helpers
+      # Included in the RSpec configuration in `frameworks/rspec.rb`
       module InstanceMethods
         # enable versioning for specific blocks (at instance-level)
         def with_versioning
@@ -12,10 +13,11 @@ module PaperTrail
         end
       end
 
+      # Extended by the RSpec configuration in `frameworks/rspec.rb`
       module ClassMethods
         # enable versioning for specific blocks (at class-level)
         def with_versioning(&block)
-          context 'with versioning', :versioning => true do
+          context "with versioning", versioning: true do
             class_exec(&block)
           end
         end

data/lib/paper_trail/frameworks/rspec.rb

@@ -1,6 +1,6 @@
-require 'rspec/core'
-require 'rspec/matchers'
-require 'paper_trail/frameworks/rspec/helpers'
+require "rspec/core"
+require "rspec/matchers"
+require "paper_trail/frameworks/rspec/helpers"
 
 RSpec.configure do |config|
   config.include ::PaperTrail::RSpec::Helpers::InstanceMethods
@@ -13,14 +13,14 @@ RSpec.configure do |config|
     ::PaperTrail.controller_info = {} if defined?(::Rails) && defined?(::RSpec::Rails)
   end
 
-  config.before(:each, :versioning => true) do
+  config.before(:each, versioning: true) do
     ::PaperTrail.enabled = true
   end
 end
 
 RSpec::Matchers.define :be_versioned do
   # check to see if the model has `has_paper_trail` declared on it
-  match { |actual| actual.kind_of?(::PaperTrail::Model::InstanceMethods) }
+  match { |actual| actual.is_a?(::PaperTrail::Model::InstanceMethods) }
 end
 
 RSpec::Matchers.define :have_a_version_with do |attributes|

data/lib/paper_trail/frameworks/sinatra.rb

@@ -1,9 +1,10 @@
-require 'active_support/core_ext/object' # provides the `try` method
+require "active_support/core_ext/object" # provides the `try` method
 
 module PaperTrail
+  # Extensions to `Sinatra`.
   module Sinatra
-
-    # Register this module inside your Sinatra application to gain access to controller-level methods used by PaperTrail
+    # Register this module inside your Sinatra application to gain access to
+    # controller-level methods used by PaperTrail.
     def self.registered(app)
       app.use RequestStore::Middleware
       app.helpers self
@@ -28,10 +29,12 @@ module PaperTrail
 
     # Tells PaperTrail who is responsible for any changes that occur.
     def set_paper_trail_whodunnit
+      @set_paper_trail_whodunnit_called = true
       ::PaperTrail.whodunnit = user_for_paper_trail if ::PaperTrail.enabled?
     end
-
   end
+end
 
-  ::Sinatra.register PaperTrail::Sinatra if defined?(::Sinatra)
+if defined?(::Sinatra)
+  ::Sinatra.register(::PaperTrail::Sinatra)
 end