paper_trail 3.0.0.rc2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0c33a2d2b003d082bede1ad845e1a4b158707782
-  data.tar.gz: 4e47a0a036926d20dca09f9cf22ab7c7c492dadd
+  metadata.gz: c90dbeb20af0ebaa74cf679e80b9d78b299af92d
+  data.tar.gz: b2f30b7cc6460365f92e6d5e7c92873624f1187c
 SHA512:
-  metadata.gz: ae06bb1637cea1664c1f75ede2ac0195cac6f44a490d2988921a71d5461ac8d65cd96171ddbe4ad8d273340c9cba21aed937fdf755bdd56438d96ee49e261deb
-  data.tar.gz: 63587c8419be2ed421ffee4019564b84f64ed1536f5e323437070aab0144e3216800f32698154f98193d383087a0cc2e7ed04f647ed451aa73da8c2a281fbd79
+  metadata.gz: cca17faa39ff342de70157ee32913040fe1ad6098d0f0b446ff470a944071d1b50486c04eba658f021f4ef65d75637cdb0df78cb306275011748ec38847ec887
+  data.tar.gz: 94fc8094261b8c401e228142eeba8d51f5aa5c54a67b522f54e83b9f42562d80feeb981e86b5c73b45094d045d92b3e7f0285571b0e6dd1c78e2d60e07586225

data/CHANGELOG.md

@@ -1,5 +1,6 @@
-## 3.0.0 (Unreleased)
+## 3.0.0
 
+  - [#305](https://github.com/airblade/paper_trail/pull/305) - `PaperTrail::VERSION` should be loaded at runtime.
   - [#295](https://github.com/airblade/paper_trail/issues/295) - Explicitly specify table name for version class when
     querying attributes. Prevents `AmbiguousColumn` errors on certain `JOIN` statements.
   - [#289](https://github.com/airblade/paper_trail/pull/289) - Use `ActiveSupport::Concern` for implementation of base functionality on
@@ -29,6 +30,7 @@
   - [#119](https://github.com/airblade/paper_trail/issues/119) - Support for [Sinatra](http://www.sinatrarb.com/); decoupled gem from `Rails`.
   - Renamed the default serializers from `PaperTrail::Serializers::Yaml` and `PaperTrail::Serializers::Json` to the capitalized forms,
     `PaperTrail::Serializers::YAML` and `PaperTrail::Serializers::JSON`.
+  - Removed deprecated `set_whodunnit` method from Rails Controller scope.
 
 ## 2.7.2
 

data/README.md

@@ -32,9 +32,8 @@ There's an excellent [RailsCast on implementing Undo with Paper Trail](http://ra
 
 Works with ActiveRecord 4 and ActiveRecord 3. Note: this code is on the `master` branch and tagged `v3.x`.
 
-**You are reading the docs for the `master` branch. The latest release of PaperTrail is 2.7.2, the docs for which can be viewed on the [`2.7-stable`](https://github.com/airblade/paper_trail/tree/2.7-stable branch).**
-
 Version 2 is on the branch named [`2.7-stable`](https://github.com/airblade/paper_trail/tree/2.7-stable) and is tagged `v2.x`, and works with Rails 3.
+
 The Rails 2.3 code is on the [`rails2`](https://github.com/airblade/paper_trail/tree/rails2) branch and tagged `v1.x`. These branches are both stable with their respective versions of Rails but will not have new features added/backported to them.
 
 ## Installation
@@ -43,7 +42,7 @@ The Rails 2.3 code is on the [`rails2`](https://github.com/airblade/paper_trail/
 
 1. Add `PaperTrail` to your `Gemfile`.
 
-    `gem 'paper_trail', '>= 3.0.0.rc1'`
+    `gem 'paper_trail', '~> 3.0.0'`
 
 2. Generate a migration which will add a `versions` table to your database.
 
@@ -57,14 +56,15 @@ The Rails 2.3 code is on the [`rails2`](https://github.com/airblade/paper_trail/
 
 ### Sinatra
 
-In order to configure `PaperTrail` for usage with [`Sinatra`](http://www.sinatrarb.com), your Sinatra app must be using `ActiveRecord` 3 or greater.
-It is also recommended to use the [`Sinatra ActiveRecord Extension`](https://github.com/janko-m/sinatra-activerecord) or something similar for managing
-your applications `ActiveRecord` connection in a manner similar to the way `Rails` does. If using the aforementioned `Sinatra ActiveRecord Extension`,
-steps for setting up your app with `PaperTrail` will look something like this:
+In order to configure `PaperTrail` for usage with [Sinatra](http://www.sinatrarb.com),
+your `Sinatra` app must be using `ActiveRecord` 3 or  `ActiveRecord` 4. It is also recommended to use the 
+[Sinatra ActiveRecord Extension](https://github.com/janko-m/sinatra-activerecord) or something similar for managing
+your applications `ActiveRecord` connection in a manner similar to the way `Rails` does. If using the aforementioned
+`Sinatra ActiveRecord Extension`, steps for setting up your app with `PaperTrail` will look something like this:
 
 1. Add `PaperTrail` to your `Gemfile`.
 
-    `gem 'paper_trail', '>= 3.0.0.rc1'`
+    `gem 'paper_trail', '~> 3.0.0'`
 
 2. Generate a migration to add a `versions` table to your database.
 
@@ -84,7 +84,7 @@ PaperTrail provides a helper extension that acts similar to the controller mixin
 
 It will set `PaperTrail.whodunnit` to whatever is returned by a method named `user_for_paper_trail` which you can define inside your Sinatra Application. (by default it attempts to invoke a method named `current_user`)
 
-If you're using the modular [Sinatra::Base](http://www.sinatrarb.com/intro.html#Modular%20vs.%20Classic%20Style) style of application, you will need to register the extension:
+If you're using the modular [`Sinatra::Base`](http://www.sinatrarb.com/intro.html#Modular%20vs.%20Classic%20Style) style of application, you will need to register the extension:
 
 ```ruby
 # bleh_app.rb
@@ -447,7 +447,7 @@ You can find out whether a model instance is the current, live one -- or whether
 
 ## Finding Out Who Was Responsible For A Change
 
-If your `ApplicationController` has a `current_user` method, PaperTrail will store the value it returns in the `version`'s `whodunnit` column.  Note that this column is a string so you will have to convert it to an integer if it's an id and you want to look up the user later on:
+If your `ApplicationController` has a `current_user` method, PaperTrail will store the value it returns in the version's `whodunnit` column.  Note that this column is of type `String`, so you will have to convert it to an integer if it's an id and you want to look up the user later on:
 
 ```ruby
 >> last_change = widget.versions.last
@@ -464,7 +464,7 @@ class ApplicationController
 end
 ```
 
-In a migration or in `rails console` you can set who is responsible like this:
+In a console session you can manually set who is responsible like this:
 
 ```ruby
 >> PaperTrail.whodunnit = 'Andy Stewart'
@@ -484,9 +484,9 @@ class PaperTrail::Version < ActiveRecord::Base
 end
 ```
 
-N.B. A `version`'s `whodunnit` records who changed the object causing the `version` to be stored.  Because a `version` stores the object as it looked before the change (see the table above), `whodunnit` returns who stopped the object looking like this -- not who made it look like this.  Hence `whodunnit` is aliased as `terminator`.
+A version's `whodunnit` records who changed the object causing the `version` to be stored.  Because a version stores the object as it looked before the change (see the table above), `whodunnit` returns who stopped the object looking like this -- not who made it look like this.  Hence `whodunnit` is aliased as `terminator`.
 
-To find out who made a `version`'s object look that way, use `version.originator`.  And to find out who made a "live" object look like it does, use `originator` on the object.
+To find out who made a version's object look that way, use `version.originator`.  And to find out who made a "live" object look like it does, use `originator` on the object.
 
 ```ruby
 >> widget = Widget.find 153                    # assume widget has 0 versions
@@ -533,7 +533,7 @@ end
 
 Alternatively you could store certain metadata for one type of version, and other metadata for other versions.
 
-If you only use custom version classes and don't use PaperTrail's built-in one, on Rails 3.2 you must:
+If you only use custom version classes and don't use PaperTrail's built-in one, on Rails `>= 3.2` you must:
 
 - either declare PaperTrail's version class abstract like this (in `config/initializers/paper_trail_patch.rb`):
 
@@ -543,7 +543,7 @@ PaperTrail::Version.module_eval do
 end
 ```
 
-- or define a `versions` table in the database so Rails can instantiate the version superclass.
+- or create a `versions` table in the database so Rails can instantiate the `PaperTrail::Version` superclass.
 
 You can also specify custom names for the versions and version associations.  This is useful if you already have `versions` or/and `version` methods on your model.  For example:
 
@@ -668,6 +668,7 @@ See [issue 113](https://github.com/airblade/paper_trail/issues/113) for a discus
 
 There may be a way to store authorship versions, probably using association callbacks, no matter how the collection is manipulated but I haven't found it yet.  Let me know if you do.
 
+There has been some discussion of how to implement PaperTrail to fully track HABTM associations. See [pull 90](https://github.com/airblade/paper_trail/pull/90) for an implementation that has worked for some.
 
 ## Storing metadata
 
@@ -706,7 +707,7 @@ end
 Why would you do this?  In this example, `author_id` is an attribute of `Article` and PaperTrail will store it anyway in a serialized form in the `object` column of the `version` record.  But let's say you wanted to pull out all versions for a particular author; without the metadata you would have to deserialize (reify) each `version` object to see if belonged to the author in question.  Clearly this is inefficient.  Using the metadata you can find just those versions you want:
 
 ```ruby
-PaperTrail::Version.all(:conditions => ['author_id = ?', author_id])
+PaperTrail::Version.where(:author_id => author_id)
 ```
 
 Note you can pass a symbol as a value in the `meta` hash to signal a method to call.
@@ -771,7 +772,7 @@ On a global level you can turn PaperTrail off like this:
 >> PaperTrail.enabled = false
 ```
 
-For example, you might want to disable PaperTrail in your Rails application's test environment to speed up your tests.  This will do it:
+For example, you might want to disable PaperTrail in your Rails application's test environment to speed up your tests.  This will do it (note: this gets done automatically for `RSpec and `Cucumber`, please see the [Testing section](#testing)):
 
 ```ruby
 # in config/environments/test.rb

data/lib/paper_trail.rb

@@ -1,6 +1,7 @@
 require 'paper_trail/config'
 require 'paper_trail/has_paper_trail'
 require 'paper_trail/cleaner'
+require 'paper_trail/version_number'
 
 # Require serializers
 Dir[File.join(File.dirname(__FILE__), 'paper_trail', 'serializers', '*.rb')].each { |file| require file }

data/lib/paper_trail/frameworks/cucumber.rb

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

data/lib/paper_trail/frameworks/rails.rb

@@ -59,19 +59,13 @@ module PaperTrail
 
       # Tells PaperTrail who is responsible for any changes that occur.
       def set_paper_trail_whodunnit
-        ::PaperTrail.whodunnit = user_for_paper_trail if paper_trail_enabled_for_controller
-      end
-
-      # DEPRECATED: please use `set_paper_trail_whodunnit` instead.
-      def set_whodunnit
-        logger.warn '[PaperTrail]: the `set_whodunnit` controller method has been deprecated.  Please rename to `set_paper_trail_whodunnit`.'
-        set_paper_trail_whodunnit
+        ::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.
       def set_paper_trail_controller_info
-        ::PaperTrail.controller_info = info_for_paper_trail if paper_trail_enabled_for_controller
+        ::PaperTrail.controller_info = info_for_paper_trail if ::PaperTrail.enabled_for_controller?
       end
 
     end

data/lib/paper_trail/version.rb

@@ -1,224 +1,7 @@
-require 'active_support/concern'
+require File.expand_path('../version_concern', __FILE__)
 
 module PaperTrail
-  module VersionConcern
-    extend ActiveSupport::Concern
-    included do
-      belongs_to :item, :polymorphic => true
-      validates_presence_of :event
-      attr_accessible :item_type, :item_id, :event, :whodunnit, :object, :object_changes if PaperTrail.active_record_protected_attributes?
-
-      after_create :enforce_version_limit!
-    end
-
-    module ClassMethods
-      def with_item_keys(item_type, item_id)
-        where :item_type => item_type, :item_id => item_id
-      end
-
-      def creates
-        where :event => 'create'
-      end
-
-      def updates
-        where :event => 'update'
-      end
-
-      def destroys
-        where :event => 'destroy'
-      end
-
-      def not_creates
-        where 'event <> ?', 'create'
-      end
-
-      # These methods accept a timestamp or a version and returns other versions that come before or after
-      def subsequent(obj)
-        obj = obj.send(PaperTrail.timestamp_field) if obj.is_a?(self)
-        where("#{table_name}.#{PaperTrail.timestamp_field} > ?", obj).
-          order("#{table_name}.#{PaperTrail.timestamp_field} ASC")
-      end
-
-      def preceding(obj)
-        obj = obj.send(PaperTrail.timestamp_field) if obj.is_a?(self)
-        where("#{table_name}.#{PaperTrail.timestamp_field} < ?", obj).
-          order("#{table_name}.#{PaperTrail.timestamp_field} DESC")
-      end
-
-      def between(start_time, end_time)
-        where("#{table_name}.#{PaperTrail.timestamp_field} > ? AND #{table_name}.#{PaperTrail.timestamp_field} < ?",
-          start_time, end_time).order("#{table_name}.#{PaperTrail.timestamp_field} ASC")
-      end
-
-      # Returns whether the `object` column is using the `json` type supported by PostgreSQL
-      def object_col_is_json?
-        @object_col_is_json ||= columns_hash['object'].type == :json
-      end
-
-      # Returns whether the `object_changes` column is using the `json` type supported by PostgreSQL
-      def object_changes_col_is_json?
-        @object_changes_col_is_json ||= columns_hash['object_changes'].type == :json
-      end
-    end
-
-    # Restore the item from this version.
-    #
-    # This will automatically restore all :has_one associations as they were "at the time",
-    # if they are also being versioned by PaperTrail.  NOTE: this isn't always guaranteed
-    # to work so you can either change the lookback period (from the default 3 seconds) or
-    # opt out.
-    #
-    # Options:
-    # :has_one     set to `false` to opt out of has_one reification.
-    #              set to a float to change the lookback time (check whether your db supports
-    #              sub-second datetimes if you want them).
-    def reify(options = {})
-      return nil if object.nil?
-
-      without_identity_map do
-        options[:has_one] = 3 if options[:has_one] == true
-        options.reverse_merge! :has_one => false
-
-        attrs = self.class.object_col_is_json? ? object : PaperTrail.serializer.load(object)
-
-        # Normally a polymorphic belongs_to relationship allows us
-        # to get the object we belong to by calling, in this case,
-        # `item`.  However this returns nil if `item` has been
-        # destroyed, and we need to be able to retrieve destroyed
-        # objects.
-        #
-        # In this situation we constantize the `item_type` to get hold of
-        # the class...except when the stored object's attributes
-        # include a `type` key.  If this is the case, the object
-        # we belong to is using single table inheritance and the
-        # `item_type` will be the base class, not the actual subclass.
-        # If `type` is present but empty, the class is the base class.
-
-        if item
-          model = item
-          # Look for attributes that exist in the model and not in this version. These attributes should be set to nil.
-          (model.attribute_names - attrs.keys).each { |k| attrs[k] = nil }
-        else
-          inheritance_column_name = item_type.constantize.inheritance_column
-          class_name = attrs[inheritance_column_name].blank? ? item_type : attrs[inheritance_column_name]
-          klass = class_name.constantize
-          model = klass.new
-        end
-
-        model.class.unserialize_attributes_for_paper_trail attrs
-
-        # Set all the attributes in this version on the model
-        attrs.each do |k, v|
-          if model.respond_to?("#{k}=")
-            model[k.to_sym] = v
-          else
-            logger.warn "Attribute #{k} does not exist on #{item_type} (Version id: #{id})."
-          end
-        end
-
-        model.send "#{model.class.version_association_name}=", self
-
-        unless options[:has_one] == false
-          reify_has_ones model, options[:has_one]
-        end
-
-        model
-      end
-    end
-
-    # Returns what changed in this version of the item.  Cf. `ActiveModel::Dirty#changes`.
-    # Returns `nil` if your `versions` table does not have an `object_changes` text column.
-    def changeset
-      return nil unless self.class.column_names.include? 'object_changes'
-
-      _changes = self.class.object_changes_col_is_json? ? object_changes : PaperTrail.serializer.load(object_changes)
-      @changeset ||= HashWithIndifferentAccess.new(_changes).tap do |changes|
-        item_type.constantize.unserialize_attribute_changes(changes)
-      end
-    rescue
-      {}
-    end
-
-    # Returns who put the item into the state stored in this version.
-    def originator
-      @originator ||= previous.whodunnit rescue nil
-    end
-
-    # Returns who changed the item from the state it had in this version.
-    # This is an alias for `whodunnit`.
-    def terminator
-      @terminator ||= whodunnit
-    end
-    alias_method :version_author, :terminator
-
-    def sibling_versions(reload = false)
-      @sibling_versions = nil if reload == true
-      @sibling_versions ||= self.class.with_item_keys(item_type, item_id)
-    end
-
-    def next
-      @next ||= sibling_versions.subsequent(self).first
-    end
-
-    def previous
-      @previous ||= sibling_versions.preceding(self).first
-    end
-
-    def index
-      table_name = self.class.table_name
-      @index ||= sibling_versions.
-        select(["#{table_name}.#{PaperTrail.timestamp_field}", "#{table_name}.#{self.class.primary_key}"]).
-        order("#{table_name}.#{PaperTrail.timestamp_field} ASC").index(self)
-    end
-
-    private
-
-    # In Rails 3.1+, calling reify on a previous version confuses the
-    # IdentityMap, if enabled. This prevents insertion into the map.
-    def without_identity_map(&block)
-      if defined?(::ActiveRecord::IdentityMap) && ::ActiveRecord::IdentityMap.respond_to?(:without)
-        ::ActiveRecord::IdentityMap.without(&block)
-      else
-        block.call
-      end
-    end
-
-    # Restore the `model`'s has_one associations as they were when this version was
-    # superseded by the next (because that's what the user was looking at when they
-    # made the change).
-    #
-    # The `lookback` sets how many seconds before the model's change we go.
-    def reify_has_ones(model, lookback)
-      model.class.reflect_on_all_associations(:has_one).each do |assoc|
-        child = model.send assoc.name
-        if child.respond_to? :version_at
-          # N.B. we use version of the child as it was `lookback` seconds before the parent was updated.
-          # Ideally we want the version of the child as it was just before the parent was updated...
-          # but until PaperTrail knows which updates are "together" (e.g. parent and child being
-          # updated on the same form), it's impossible to tell when the overall update started;
-          # and therefore impossible to know when "just before" was.
-          if (child_as_it_was = child.version_at(send(PaperTrail.timestamp_field) - lookback.seconds))
-            child_as_it_was.attributes.each do |k,v|
-              model.send(assoc.name).send :write_attribute, k.to_sym, v rescue nil
-            end
-          else
-            model.send "#{assoc.name}=", nil
-          end
-        end
-      end
-    end
-
-    # checks to see if a value has been set for the `version_limit` config option, and if so enforces it
-    def enforce_version_limit!
-      return unless PaperTrail.config.version_limit.is_a? Numeric
-      previous_versions = sibling_versions.not_creates
-      return unless previous_versions.size > PaperTrail.config.version_limit
-      excess_previous_versions = previous_versions - previous_versions.last(PaperTrail.config.version_limit)
-      excess_previous_versions.map(&:destroy)
-    end
-  end
-
   class Version < ::ActiveRecord::Base
-    include VersionConcern
+    include PaperTrail::VersionConcern
   end
 end

data/lib/paper_trail/version_concern.rb

@@ -0,0 +1,221 @@
+require 'active_support/concern'
+
+module PaperTrail
+  module VersionConcern
+    extend ::ActiveSupport::Concern
+
+    included do
+      belongs_to :item, :polymorphic => true
+      validates_presence_of :event
+      attr_accessible :item_type, :item_id, :event, :whodunnit, :object, :object_changes if PaperTrail.active_record_protected_attributes?
+
+      after_create :enforce_version_limit!
+    end
+
+    module ClassMethods
+      def with_item_keys(item_type, item_id)
+        where :item_type => item_type, :item_id => item_id
+      end
+
+      def creates
+        where :event => 'create'
+      end
+
+      def updates
+        where :event => 'update'
+      end
+
+      def destroys
+        where :event => 'destroy'
+      end
+
+      def not_creates
+        where 'event <> ?', 'create'
+      end
+
+      # These methods accept a timestamp or a version and returns other versions that come before or after
+      def subsequent(obj)
+        obj = obj.send(PaperTrail.timestamp_field) if obj.is_a?(self)
+        where("#{table_name}.#{PaperTrail.timestamp_field} > ?", obj).
+          order("#{table_name}.#{PaperTrail.timestamp_field} ASC")
+      end
+
+      def preceding(obj)
+        obj = obj.send(PaperTrail.timestamp_field) if obj.is_a?(self)
+        where("#{table_name}.#{PaperTrail.timestamp_field} < ?", obj).
+          order("#{table_name}.#{PaperTrail.timestamp_field} DESC")
+      end
+
+      def between(start_time, end_time)
+        where("#{table_name}.#{PaperTrail.timestamp_field} > ? AND #{table_name}.#{PaperTrail.timestamp_field} < ?",
+          start_time, end_time).order("#{table_name}.#{PaperTrail.timestamp_field} ASC")
+      end
+
+      # Returns whether the `object` column is using the `json` type supported by PostgreSQL
+      def object_col_is_json?
+        @object_col_is_json ||= columns_hash['object'].type == :json
+      end
+
+      # Returns whether the `object_changes` column is using the `json` type supported by PostgreSQL
+      def object_changes_col_is_json?
+        @object_changes_col_is_json ||= columns_hash['object_changes'].type == :json
+      end
+    end
+
+    # Restore the item from this version.
+    #
+    # This will automatically restore all :has_one associations as they were "at the time",
+    # if they are also being versioned by PaperTrail.  NOTE: this isn't always guaranteed
+    # to work so you can either change the lookback period (from the default 3 seconds) or
+    # opt out.
+    #
+    # Options:
+    # :has_one     set to `false` to opt out of has_one reification.
+    #              set to a float to change the lookback time (check whether your db supports
+    #              sub-second datetimes if you want them).
+    def reify(options = {})
+      return nil if object.nil?
+
+      without_identity_map do
+        options[:has_one] = 3 if options[:has_one] == true
+        options.reverse_merge! :has_one => false
+
+        attrs = self.class.object_col_is_json? ? object : PaperTrail.serializer.load(object)
+
+        # Normally a polymorphic belongs_to relationship allows us
+        # to get the object we belong to by calling, in this case,
+        # `item`.  However this returns nil if `item` has been
+        # destroyed, and we need to be able to retrieve destroyed
+        # objects.
+        #
+        # In this situation we constantize the `item_type` to get hold of
+        # the class...except when the stored object's attributes
+        # include a `type` key.  If this is the case, the object
+        # we belong to is using single table inheritance and the
+        # `item_type` will be the base class, not the actual subclass.
+        # If `type` is present but empty, the class is the base class.
+
+        if item
+          model = item
+          # Look for attributes that exist in the model and not in this version. These attributes should be set to nil.
+          (model.attribute_names - attrs.keys).each { |k| attrs[k] = nil }
+        else
+          inheritance_column_name = item_type.constantize.inheritance_column
+          class_name = attrs[inheritance_column_name].blank? ? item_type : attrs[inheritance_column_name]
+          klass = class_name.constantize
+          model = klass.new
+        end
+
+        model.class.unserialize_attributes_for_paper_trail attrs
+
+        # Set all the attributes in this version on the model
+        attrs.each do |k, v|
+          if model.respond_to?("#{k}=")
+            model[k.to_sym] = v
+          else
+            logger.warn "Attribute #{k} does not exist on #{item_type} (Version id: #{id})."
+          end
+        end
+
+        model.send "#{model.class.version_association_name}=", self
+
+        unless options[:has_one] == false
+          reify_has_ones model, options[:has_one]
+        end
+
+        model
+      end
+    end
+
+    # Returns what changed in this version of the item.  Cf. `ActiveModel::Dirty#changes`.
+    # Returns `nil` if your `versions` table does not have an `object_changes` text column.
+    def changeset
+      return nil unless self.class.column_names.include? 'object_changes'
+
+      _changes = self.class.object_changes_col_is_json? ? object_changes : PaperTrail.serializer.load(object_changes)
+      @changeset ||= HashWithIndifferentAccess.new(_changes).tap do |changes|
+        item_type.constantize.unserialize_attribute_changes(changes)
+      end
+    rescue
+      {}
+    end
+
+    # Returns who put the item into the state stored in this version.
+    def originator
+      @originator ||= previous.whodunnit rescue nil
+    end
+
+    # Returns who changed the item from the state it had in this version.
+    # This is an alias for `whodunnit`.
+    def terminator
+      @terminator ||= whodunnit
+    end
+    alias_method :version_author, :terminator
+
+    def sibling_versions(reload = false)
+      @sibling_versions = nil if reload == true
+      @sibling_versions ||= self.class.with_item_keys(item_type, item_id)
+    end
+
+    def next
+      @next ||= sibling_versions.subsequent(self).first
+    end
+
+    def previous
+      @previous ||= sibling_versions.preceding(self).first
+    end
+
+    def index
+      table_name = self.class.table_name
+      @index ||= sibling_versions.
+        select(["#{table_name}.#{PaperTrail.timestamp_field}", "#{table_name}.#{self.class.primary_key}"]).
+        order("#{table_name}.#{PaperTrail.timestamp_field} ASC").index(self)
+    end
+
+    private
+
+    # In Rails 3.1+, calling reify on a previous version confuses the
+    # IdentityMap, if enabled. This prevents insertion into the map.
+    def without_identity_map(&block)
+      if defined?(::ActiveRecord::IdentityMap) && ::ActiveRecord::IdentityMap.respond_to?(:without)
+        ::ActiveRecord::IdentityMap.without(&block)
+      else
+        block.call
+      end
+    end
+
+    # Restore the `model`'s has_one associations as they were when this version was
+    # superseded by the next (because that's what the user was looking at when they
+    # made the change).
+    #
+    # The `lookback` sets how many seconds before the model's change we go.
+    def reify_has_ones(model, lookback)
+      model.class.reflect_on_all_associations(:has_one).each do |assoc|
+        child = model.send assoc.name
+        if child.respond_to? :version_at
+          # N.B. we use version of the child as it was `lookback` seconds before the parent was updated.
+          # Ideally we want the version of the child as it was just before the parent was updated...
+          # but until PaperTrail knows which updates are "together" (e.g. parent and child being
+          # updated on the same form), it's impossible to tell when the overall update started;
+          # and therefore impossible to know when "just before" was.
+          if (child_as_it_was = child.version_at(send(PaperTrail.timestamp_field) - lookback.seconds))
+            child_as_it_was.attributes.each do |k,v|
+              model.send(assoc.name).send :write_attribute, k.to_sym, v rescue nil
+            end
+          else
+            model.send "#{assoc.name}=", nil
+          end
+        end
+      end
+    end
+
+    # checks to see if a value has been set for the `version_limit` config option, and if so enforces it
+    def enforce_version_limit!
+      return unless PaperTrail.config.version_limit.is_a? Numeric
+      previous_versions = sibling_versions.not_creates
+      return unless previous_versions.size > PaperTrail.config.version_limit
+      excess_previous_versions = previous_versions - previous_versions.last(PaperTrail.config.version_limit)
+      excess_previous_versions.map(&:destroy)
+    end
+  end
+end

data/lib/paper_trail/version_number.rb

@@ -1,3 +1,3 @@
 module PaperTrail
-  VERSION = '3.0.0.rc2'
+  VERSION = '3.0.0'
 end

data/paper_trail.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.platform      = Gem::Platform::RUBY
   s.summary       = "Track changes to your models' data. Good for auditing or versioning."
   s.description   = s.summary
-  s.homepage      = 'http://github.com/airblade/paper_trail'
+  s.homepage      = 'https://github.com/airblade/paper_trail'
   s.authors       = ['Andy Stewart', 'Ben Atkins']
   s.email         = 'batkinz@gmail.com'
   s.license       = 'MIT'
@@ -17,6 +17,8 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ['lib']
 
+  s.required_rubygems_version = '>= 1.3.6'
+
   s.add_dependency 'activerecord', ['>= 3.0', '< 5.0']
   s.add_dependency 'activesupport', ['>= 3.0', '< 5.0']
 

data/spec/modules/version_concern_spec.rb

@@ -2,49 +2,31 @@ require 'spec_helper'
 
 describe PaperTrail::VersionConcern do
 
-  before(:all) do
-    module Foo
-      class Base < ActiveRecord::Base
-        self.abstract_class = true
-      end
-
-      class Document < Base
-        has_paper_trail :class_name => 'Foo::Version'
-      end
-
-      class Version < Base
-        include PaperTrail::VersionConcern
-      end
-    end
-    Foo::Base.establish_connection(:adapter => 'sqlite3', :database => File.expand_path('../../../test/dummy/db/test-foo.sqlite3', __FILE__))
-
-    module Bar
-      class Base < ActiveRecord::Base
-        self.abstract_class = true
-      end
-
-      class Document < Base
-        has_paper_trail :class_name => 'Bar::Version'
-      end
-
-      class Version < Base
-        include PaperTrail::VersionConcern
-      end
-    end
-    Bar::Base.establish_connection(:adapter => 'sqlite3', :database => File.expand_path('../../../test/dummy/db/test-bar.sqlite3', __FILE__))
-  end
+  before(:all) { require 'support/alt_db_init' }
 
   it 'allows included class to have different connections' do
-    Foo::Version.connection.should_not eq Bar::Version.connection
+    Foo::Version.connection.should_not == Bar::Version.connection
   end
 
   it 'allows custom version class to share connection with superclass' do
-    Foo::Version.connection.should eq Foo::Document.connection
-    Bar::Version.connection.should eq Bar::Document.connection
+    Foo::Version.connection.should == Foo::Document.connection
+    Bar::Version.connection.should == Bar::Document.connection
   end
 
   it 'can be used with class_name option' do
-    Foo::Document.version_class_name.should eq 'Foo::Version'
-    Bar::Document.version_class_name.should eq 'Bar::Version'
+    Foo::Document.version_class_name.should == 'Foo::Version'
+    Bar::Document.version_class_name.should == 'Bar::Version'
+  end
+
+  describe 'persistence', :versioning => true do
+    before do
+      @foo_doc = Foo::Document.create!(:name => 'foobar')
+      @bar_doc = Bar::Document.create!(:name => 'raboof')
+    end
+
+    it 'should store versions in the correct corresponding db location' do
+      @foo_doc.versions.first.should be_instance_of(Foo::Version)
+      @bar_doc.versions.first.should be_instance_of(Bar::Version)
+    end
   end
 end

data/spec/requests/articles_spec.rb

@@ -1,3 +1,7 @@
+RSpec.configure do |c|
+  c.order = 'defined'
+end
+
 require 'spec_helper'
 
 describe "Articles" do
@@ -7,7 +11,9 @@ describe "Articles" do
     specify { PaperTrail.enabled?.should be_false }
 
     it "should not create a version" do
+      PaperTrail.enabled_for_controller?.should be_true
       expect { post articles_path(valid_params) }.to_not change(PaperTrail::Version, :count)
+      PaperTrail.enabled_for_controller?.should be_false
     end
 
     it "should not leak the state of the `PaperTrail.enabled_for_controlller?` into the next test" do

data/spec/spec_helper.rb

@@ -39,5 +39,5 @@ RSpec.configure do |config|
   # order dependency and want to debug it, you can fix the order by providing
   # the seed, which is printed after each run.
   #     --seed 1234
-  # config.order = 'random'
+  config.order ||= 'random'
 end

data/spec/support/alt_db_init.rb

@@ -0,0 +1,44 @@
+# This file copies the test database into locations for the `Foo` and `Bar` namespace,
+# then defines those namespaces, then establishes the sqlite3 connection for the namespaces
+# to simulate an application with multiple database connections.
+
+db_directory = "#{Rails.root}/db"
+# setup alternate databases
+if RUBY_VERSION.to_f >= 1.9
+  FileUtils.cp "#{db_directory}/test.sqlite3", "#{db_directory}/test-foo.sqlite3"
+  FileUtils.cp "#{db_directory}/test.sqlite3", "#{db_directory}/test-bar.sqlite3"
+else
+  require 'ftools'
+  File.cp "#{db_directory}/test.sqlite3", "#{db_directory}/test-foo.sqlite3"
+  File.cp "#{db_directory}/test.sqlite3", "#{db_directory}/test-bar.sqlite3"
+end
+
+module Foo
+  class Base < ActiveRecord::Base
+    self.abstract_class = true
+  end
+
+  class Version < Base
+    include PaperTrail::VersionConcern
+  end
+
+  class Document < Base
+    has_paper_trail :class_name => 'Foo::Version'
+  end
+end
+Foo::Base.establish_connection(:adapter => 'sqlite3', :database => "#{db_directory}/test-foo.sqlite3")
+
+module Bar
+  class Base < ActiveRecord::Base
+    self.abstract_class = true
+  end
+
+  class Version < Base
+    include PaperTrail::VersionConcern
+  end
+
+  class Document < Base
+    has_paper_trail :class_name => 'Bar::Version'
+  end
+end
+Bar::Base.establish_connection(:adapter => 'sqlite3', :database => "#{db_directory}/test-bar.sqlite3")

data/test/functional/thread_safety_test.rb

@@ -6,7 +6,7 @@ class ThreadSafetyTest < ActionController::TestCase
 
     slow_thread = Thread.new do
       controller = TestController.new
-      controller.send :set_whodunnit
+      controller.send :set_paper_trail_whodunnit
       begin
         sleep 0.001
       end while blocked
@@ -15,7 +15,7 @@ class ThreadSafetyTest < ActionController::TestCase
 
     fast_thread = Thread.new do
       controller = TestController.new
-      controller.send :set_whodunnit
+      controller.send :set_paper_trail_whodunnit
       who = PaperTrail.whodunnit
       blocked = false
       who

data/test/paper_trail_test.rb

@@ -5,6 +5,10 @@ class PaperTrailTest < ActiveSupport::TestCase
     assert_kind_of Module, PaperTrail::Version
   end
 
+  test 'Version Number' do
+    assert PaperTrail.const_defined?(:VERSION)
+  end
+
   test 'create with plain model class' do
     widget = Widget.create
     assert_equal 1, widget.versions.length

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail
 version: !ruby/object:Gem::Version
-  version: 3.0.0.rc2
+  version: 3.0.0
 platform: ruby
 authors:
 - Andy Stewart
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-16 00:00:00.000000000 Z
+date: 2013-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -200,6 +200,7 @@ files:
 - lib/paper_trail/serializers/json.rb
 - lib/paper_trail/serializers/yaml.rb
 - lib/paper_trail/version.rb
+- lib/paper_trail/version_concern.rb
 - lib/paper_trail/version_number.rb
 - paper_trail.gemspec
 - spec/models/joined_version_spec.rb
@@ -209,6 +210,7 @@ files:
 - spec/paper_trail_spec.rb
 - spec/requests/articles_spec.rb
 - spec/spec_helper.rb
+- spec/support/alt_db_init.rb
 - test/custom_json_serializer.rb
 - test/dummy/Rakefile
 - test/dummy/app/controllers/application_controller.rb
@@ -285,7 +287,7 @@ files:
 - test/unit/serializers/yaml_test.rb
 - test/unit/timestamp_test.rb
 - test/unit/version_test.rb
-homepage: http://github.com/airblade/paper_trail
+homepage: https://github.com/airblade/paper_trail
 licenses:
 - MIT
 metadata: {}
@@ -300,12 +302,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>'
+  - - '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.10
+rubygems_version: 2.1.11
 signing_key: 
 specification_version: 4
 summary: Track changes to your models' data. Good for auditing or versioning.
@@ -317,6 +319,7 @@ test_files:
 - spec/paper_trail_spec.rb
 - spec/requests/articles_spec.rb
 - spec/spec_helper.rb
+- spec/support/alt_db_init.rb
 - test/custom_json_serializer.rb
 - test/dummy/Rakefile
 - test/dummy/app/controllers/application_controller.rb