paper_trail 3.0.0.beta1 → 3.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b667567a3273c0c6d95a75068b7d4e0b5d5c71ba
-  data.tar.gz: 83853768990c1f61e1c9149bc275126254b87415
+  metadata.gz: 9bf681540718f57e237227b7237dd75588325471
+  data.tar.gz: 53ca44944999542128882287cfeb7a2a0c3957e6
 SHA512:
-  metadata.gz: ba6c131b28bb5a060acdd08839cc53d58407961633389d53775ca0ff47d034964a5d192f56dc3e2315fd0bcd040439b06640120b316e65bfdd68acb9783e0099
-  data.tar.gz: 1e546deade76f16dfd47a2414cf9d0d4021c45fa7d5bf2d825e62f79ba22cc04f0235102fd4c7708ea4f121e8ddedacbc07450ca74dc58c152161887368dc4e8
+  metadata.gz: 0c71e183ad7347c6d2a4202b8f4c5a00cfda6c8945a91edf325d5dbbde3c1458bee5e06cbf135deb3f33446038de435e51682d29b68b0aaf9fba77925c5e839b
+  data.tar.gz: 49fc4e1bc5e418bf1565749e8853f6516dc937fca663638da0a011dd47d6284dc53338cf479f6e8ad3ff74a7f53a93f168708108ce76a93c0474161c49d156d1

data/.travis.yml

@@ -6,9 +6,6 @@ rvm:
   - jruby-19mode
   - jruby-18mode
 
-before_install:
-  - gem install bundler --version '~> 1.3'
-
 gemfile:
   - Gemfile
   - gemfiles/3.0.gemfile

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## 3.0.0 (Unreleased)
 
+  - [#289](https://github.com/airblade/paper_trail/pull/289) - Use `ActiveSupport::Concern` for implementation of base functionality on
+    `PaperTrail::Version` class. Increases flexibility and makes it easier to use custom version classes with multiple `ActiveRecord` connections.
+  - [#288](https://github.com/airblade/paper_trail/issues/288) - Change all scope declarations to class methods on the `PaperTrail::Version`
+    class. Fixes usability when `PaperTrail::Version.abstract_class? == true`.
+  - [#287](https://github.com/airblade/paper_trail/issues/287) - Support for
+    [PostgreSQL's JSON Type](http://www.postgresql.org/docs/9.2/static/datatype-json.html) for storing `object` and `object_changes`.
+  - [#281](https://github.com/airblade/paper_trail/issues/281) - `Rails::Controller` helper will return `false` for the
+    `paper_trail_enabled_for_controller` method if `PaperTrail.enabled? == false`.
+  - [#280](https://github.com/airblade/paper_trail/pull/280) - Don't track virtual timestamp attributes.
+  - [#278](https://github.com/airblade/paper_trail/issues/278)/[#272](https://github.com/airblade/paper_trail/issues/272) -
+    Make RSpec and Cucumber helpers usable with [Spork](https://github.com/sporkrb/spork) and [Zeus](https://github.com/burke/zeus).
+  - [#273](https://github.com/airblade/paper_trail/pull/273) - Make the `only` and `ignore` options accept `Hash` arguments;
+    allows for conditional tracking.
   - [#264](https://github.com/airblade/paper_trail/pull/264) - Allow unwrapped symbol to be passed in to the `on` option.
   - [#224](https://github.com/airblade/paper_trail/issues/224)/[#236](https://github.com/airblade/paper_trail/pull/236) -
     Fixed compatibility with [ActsAsTaggableOn](https://github.com/mbleigh/acts-as-taggable-on).
@@ -12,6 +25,8 @@
   - [#199](https://github.com/airblade/paper_trail/pull/199) - Rails 4 compatibility.
   - [#165](https://github.com/airblade/paper_trail/pull/165) - Namespaced the `Version` class under the `PaperTrail` module.
   - [#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`.
 
 ## 2.7.2
 

data/README.md

@@ -2,8 +2,7 @@
 
 PaperTrail lets you track changes to your models' data.  It's good for auditing or versioning.  You can see how a model looked at any stage in its lifecycle, revert it to any version, and even undelete it after it's been destroyed.
 
-There's an excellent [Railscast on implementing Undo with Paper Trail](http://railscasts.com/episodes/255-undo-with-paper-trail).
-
+There's an excellent [RailsCast on implementing Undo with Paper Trail](http://railscasts.com/episodes/255-undo-with-paper-trail).
 
 ## Features
 
@@ -42,9 +41,9 @@ The Rails 2.3 code is on the [`rails2`](https://github.com/airblade/paper_trail/
 
 ### Rails 3 & 4
 
-1. Install PaperTrail as a gem via your `Gemfile`:
+1. Add `PaperTrail` to your `Gemfile`.
 
-    `gem 'paper_trail', '~> 3.0'`
+    `gem 'paper_trail', '>= 3.0.0.rc1'`
 
 2. Generate a migration which will add a `versions` table to your database.
 
@@ -58,6 +57,29 @@ 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:
+
+1. Add `PaperTrail` to your `Gemfile`.
+
+    `gem 'paper_trail', '>= 3.0.0.beta1'`
+
+2. Generate a migration to add a `versions` table to your database.
+
+    `bundle exec rake db:create_migration NAME=create_versions`
+
+3. Copy contents of [create_versions.rb](https://raw.github.com/airblade/paper_trail/master/lib/generators/paper_trail/templates/create_versions.rb)
+into the `create_versions` migration that was generated into your `db/migrate` directory.
+
+4. Run the migration.
+
+    `bundle exec rake db:migrate`
+
+5. Add `has_paper_trail` to the models you want to track.
+
+
 PaperTrail provides a helper extension that acts similar to the controller mixin it provides for `Rails` applications.
 
 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`)
@@ -69,7 +91,7 @@ If you're using the modular [Sinatra::Base](http://www.sinatrarb.com/intro.html#
 require 'sinatra/base'
 
 class BlehApp < Sinatra::Base
-  register Sinatra::PaperTrail
+  register PaperTrail::Sinatra
 end
 ```
 
@@ -123,6 +145,7 @@ version.originator
 # Returns who changed the item from the state it had in this version.
 version.terminator
 version.whodunnit
+version.version_author
 
 # Returns the next version.
 version.next
@@ -304,6 +327,31 @@ This means that only changes to the `title` will save a version of the article:
 >> a.previous_version.content                # nil
 ```
 
+The `:ignore` and `:only` options can also accept `Hash` arguments, where the :
+
+```ruby
+class Article < ActiveRecord::Base
+  has_paper_trail :only => [:title => Proc.new { |obj| !obj.title.blank? } ]
+end
+```
+
+This means that if the `title` is not blank, then only changes to the `title` will save a version of the article:
+
+```ruby
+>> a = Article.create
+>> a.versions.length                         # 1
+>> a.update_attributes :content => 'Hello'
+>> a.versions.length                         # 2
+>> a.update_attributes :title => 'My Title'
+>> a.versions.length                         # 3
+>> a.update_attributes :content => 'Hai'
+>> a.versions.length                         # 3
+>> a.previous_version.content                # "Hello"
+>> a.update_attributes :title => 'Dif Title'
+>> a.versions.length                         # 4
+>> a.previous_version.content                # "Hai"
+```
+
 Passing both `:ignore` and `:only` options will result in the article being saved if a changed attribute is included in `:only` but not in `:ignore`.
 
 You can skip fields altogether with the `:skip` option.  As with `:ignore`, updates to these fields will not create a new `PaperTrail::Version`.  In addition, these fields will not be included in the serialized version of the object whenever a new `PaperTrail::Version` is created.
@@ -343,7 +391,7 @@ Undeleting is just as simple:
 >> widget = Widget.find 42
 >> widget.destroy
 # Time passes....
->> widget = PaperTrail::Version.find(153).reify    # the widget as it was before it was destroyed
+>> widget = PaperTrail::Version.find(153).reify  # the widget as it was before destruction
 >> widget.save                         # the widget lives!
 ```
 
@@ -356,11 +404,11 @@ You can call `previous_version` and `next_version` on an item to get it as it wa
 
 ```ruby
 >> live_widget = Widget.find 42
->> live_widget.versions.length            # 4 for example
->> widget = live_widget.previous_version  # => widget == live_widget.versions.last.reify
->> widget = widget.previous_version       # => widget == live_widget.versions[-2].reify
->> widget = widget.next_version           # => widget == live_widget.versions.last.reify
->> widget.next_version                    # nil
+>> live_widget.versions.length           # 4 for example
+>> widget = live_widget.previous_version # => widget == live_widget.versions.last.reify
+>> widget = widget.previous_version      # => widget == live_widget.versions[-2].reify
+>> widget = widget.next_version          # => widget == live_widget.versions.last.reify
+>> widget.next_version                   # nil
 ```
 
 As an aside, I'm undecided about whether `widget.previous_version.next_version` should return `nil` or `self` (i.e. `widget`).  Let me know if you have a view.
@@ -547,7 +595,7 @@ The implementation is complicated by the edge case where the parent and child ar
 The correct solution is to make PaperTrail aware of requests or transactions (c.f. [Efficiency's transaction ID middleware](http://github.com/efficiency20/ops_middleware/blob/master/lib/e20/ops/middleware/transaction_id_middleware.rb)).  In the meantime we work around the problem by finding the child as it was a few seconds before the parent was updated.  By default we go 3 seconds before but you can change this by passing the desired number of seconds to the `:has_one` option:
 
 ```ruby
->> t = treasure.versions.last.reify(:has_one => 1)       # look back 1 second instead of 3
+>> t = treasure.versions.last.reify(:has_one => 1)  # look back 1 second instead of 3
 ```
 
 If you are shuddering, take solace from knowing PaperTrail opts out of these shenanigans by default. This means your `:has_one` associated objects will be the live ones, not the ones the user saw at the time.  Since PaperTrail doesn't auto-restore `:has_many` associations (I can't get it to work) or `:belongs_to` (I ran out of time looking at `:has_many`), this at least makes your associations wrong consistently ;)
@@ -655,7 +703,7 @@ module PaperTrail
 end
 ```
 
-Why would you do this?  In this example, `author_id` is an attribute of `Article` and PaperTrail will store it anyway in serialized (YAML) 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:
+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])
@@ -759,7 +807,7 @@ end
 
 ### Per request
 
-You can turn PaperTrail on or off per request by adding a `paper_trail_enabled_for_controller` method to your controller which returns true or false:
+You can turn PaperTrail on or off per request by adding a `paper_trail_enabled_for_controller` method to your controller which returns `true` or `false`:
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -801,7 +849,7 @@ end
 
 ## Using a custom serializer
 
-By default, PaperTrail stores your changes as a YAML dump. You can override this with the serializer config option:
+By default, PaperTrail stores your changes as a `YAML` dump. You can override this with the serializer config option:
 
 ```ruby
 >> PaperTrail.serializer = MyCustomSerializer
@@ -809,8 +857,8 @@ By default, PaperTrail stores your changes as a YAML dump. You can override this
 
 A valid serializer is a `module` (or `class`) that defines a `load` and `dump` method.  These serializers are included in the gem for your convenience:
 
-* [Yaml](https://github.com/airblade/paper_trail/blob/master/lib/paper_trail/serializers/yaml.rb) - Default
-* [Json](https://github.com/airblade/paper_trail/blob/master/lib/paper_trail/serializers/json.rb)
+* [YAML](https://github.com/airblade/paper_trail/blob/master/lib/paper_trail/serializers/yaml.rb) - Default
+* [JSON](https://github.com/airblade/paper_trail/blob/master/lib/paper_trail/serializers/json.rb)
 
 ## Limiting the number of versions created per object instance
 
@@ -819,7 +867,8 @@ there is a configuration option that can be set to cap the number of versions sa
 versions other than `create` events (which will always be preserved if they are stored).
 
 ```ruby
-# will make it so that a maximum of 4 versions will be stored for each object (the 3 most recent ones plus a `create` event)
+# will make it so that a maximum of 4 versions will be stored for each object
+# (the 3 most recent ones plus a `create` event)
 >> PaperTrail.config.version_limit = 3
 # disables/removes the version limit
 >> PaperTrail.config.version_limit = nil
@@ -839,13 +888,13 @@ sql> delete from versions where created_at < 2010-06-01;
 
 ## Testing
 
-You may want to turn PaperTrail off to speed up your tests.  See the [Turning PaperTrail Off/On](#turning-papertrail-offon) section above.
+You may want to turn PaperTrail off to speed up your tests.  See the [Turning PaperTrail Off/On](#turning-papertrail-offon) section above for tips on usage with `Test::Unit`.
 
 ### RSpec
 
-PaperTrail provides a helper that works with RSpec to make it easier to control when `PaperTrail` during testing. By default, PaperTrail will be
-turned off for all tests. When you wish to enable PaperTrail for a test you can either wrap the test in a `with_versioning` block, or pass
-in `:versioning => true` option to a spec block, like so:
+PaperTrail provides a helper that works with [RSpec](https://github.com/rspec/rspec) to make it easier to control when `PaperTrail` is enabled
+during testing. By default, PaperTrail will be turned off for all tests.
+When you wish to enable PaperTrail for a test you can either wrap the test in a `with_versioning` block, or pass in `:versioning => true` option to a spec block, like so:
 
 ```ruby
 describe "RSpec test group" do
@@ -891,7 +940,7 @@ end
 
 ### Cucumber
 
-PaperTrail provides a helper that works similar to the RSpec helper.
+PaperTrail provides a helper for [Cucumber](http://cukes.info) that works similar to the RSpec helper.
 By default, PaperTrail will be turned off for all scenarios by a `before` hook added by the helper.
 When you wish to enable PaperTrail for a scenario, you can wrap code in a `with_versioning` block in a step, like so:
 
@@ -906,8 +955,46 @@ end
 The helper will also reset the `PaperTrail.whodunnit` value to `nil` before each test to help prevent data spillover between tests.
 If you are using PaperTrail with Rails, the helper will automatically set the `PaperTrail.controller_info` value to `{}` as well, again, to help prevent data spillover between tests.
 
+### Spork
+
+If you wish to use the `RSpec` or `Cucumber` helpers with [Spork](https://github.com/sporkrb/spork), you will need to
+manually require the helper(s) in your `prefork` block on your test helper, like so:
+
+```ruby
+# spec/spec_helper.rb
+
+require 'spork'
+
+Spork.prefork do
+  # This file is copied to spec/ when you run 'rails generate rspec:install'
+  ENV["RAILS_ENV"] ||= 'test'
+  require File.expand_path("../../config/environment", __FILE__)
+  require 'rspec/rails'
+  require 'rspec/autorun'
+  require 'paper_trail/frameworks/rspec'
+  require 'paper_trail/frameworks/cucumber'
+  ...
+end
+```
+
+### Zeus
+
+If you wish to use the `RSpec` or `Cucumber` heleprs with [Zeus](https://github.com/burke/zeus), you will need to
+manually require the helper(s) in your test helper, like so:
+
+```ruby
+# spec/spec_helper.rb
+
+ENV["RAILS_ENV"] ||= 'test'
+require File.expand_path("../../config/environment", __FILE__)
+require 'rspec/rails'
+require 'paper_trail/frameworks/rspec'
+```
+
 ## Articles
 
+[Using PaperTrail to track stack traces](http://rubyrailsexpert.com/?p=36), T James Corcoran's blog, 1st October 2013.
+[RailsCast #255 - Undo with PaperTrail](http://railscasts.com/episodes/255-undo-with-paper-trail), 28th February 2011.
 [Keep a Paper Trail with PaperTrail](http://www.linux-mag.com/id/7528), Linux Magazine, 16th September 2009.
 
 
@@ -960,11 +1047,13 @@ Many thanks to:
 * [Ben Morrall](https://github.com/bmorrall)
 * [Yves Senn](https://github.com/senny)
 * [Ben Atkins](https://github.com/fullbridge-batkins)
-* [Yves Senn](https://github.com/senny)
 * [Tyler Rick](https://github.com/TylerRick)
 * [Bradley Priest](https://github.com/bradleypriest)
 * [David Butler](https://github.com/dwbutler)
 * [Paul Belt](https://github.com/belt)
+* [Vlad Bokov](https://github.com/razum2um)
+* [Sean Marcia](https://github.com/SeanMarcia)
+* [Chulki Lee](https://github.com/chulkilee)
 
 
 ## Inspirations

data/Rakefile

@@ -14,8 +14,5 @@ require 'rspec/core/rake_task'
 desc 'Run PaperTrail specs for the RSpec helper.'
 RSpec::Core::RakeTask.new(:spec)
 
-desc 'Run all available test suites'
-task :run_all_tests => [:test, :spec]
-
-desc 'Default: run unit tests.'
-task :default => :run_all_tests
+desc 'Default: run all available test suites'
+task :default => [:test, :spec]

data/lib/generators/paper_trail/install_generator.rb

@@ -17,7 +17,7 @@ module PaperTrail
     end
 
     def self.next_migration_number(dirname)
-      ActiveRecord::Generators::Base.next_migration_number(dirname)
+      ::ActiveRecord::Generators::Base.next_migration_number(dirname)
     end
   end
 end

data/lib/paper_trail.rb

@@ -2,8 +2,7 @@ require 'paper_trail/config'
 require 'paper_trail/has_paper_trail'
 require 'paper_trail/cleaner'
 
-# Require all frameworks and serializers
-Dir[File.join(File.dirname(__FILE__), 'paper_trail', 'frameworks', '*.rb')].each { |file| require file }
+# Require serializers
 Dir[File.join(File.dirname(__FILE__), 'paper_trail', 'serializers', '*.rb')].each { |file| require file }
 
 # PaperTrail's module methods can be called in both models and controllers.
@@ -80,7 +79,7 @@ module PaperTrail
   end
 
   def self.active_record_protected_attributes?
-    @active_record_protected_attributes ||= ActiveRecord::VERSION::STRING.to_f < 4.0 || defined?(ProtectedAttributes)
+    @active_record_protected_attributes ||= ::ActiveRecord::VERSION::STRING.to_f < 4.0 || !!defined?(ProtectedAttributes)
   end
 
   private
@@ -102,8 +101,22 @@ module PaperTrail
 
 end
 
+# Ensure `ProtectedAttributes` gem gets required if it is available before the `Version` class gets loaded in
+unless PaperTrail.active_record_protected_attributes?
+  PaperTrail.send(:remove_instance_variable, :@active_record_protected_attributes)
+  begin
+    require 'protected_attributes'
+  rescue LoadError; end # will rescue if `ProtectedAttributes` gem is not available
+end
+
 require 'paper_trail/version'
 
+# Require frameworks
+require 'paper_trail/frameworks/rails'
+require 'paper_trail/frameworks/sinatra'
+require 'paper_trail/frameworks/rspec' if defined? RSpec
+require 'paper_trail/frameworks/cucumber' if defined? World
+
 ActiveSupport.on_load(:active_record) do
   include PaperTrail::Model
 end

data/lib/paper_trail/config.rb

@@ -8,7 +8,7 @@ module PaperTrail
     def initialize
       @enabled         = true # Indicates whether PaperTrail is on or off.
       @timestamp_field = :created_at
-      @serializer      = PaperTrail::Serializers::Yaml
+      @serializer      = PaperTrail::Serializers::YAML
     end
   end
 end

data/lib/paper_trail/frameworks/cucumber.rb

@@ -1,31 +1,29 @@
-if defined? World
-  # before hook for Cucumber
-  before do
-    ::PaperTrail.enabled = false
-    ::PaperTrail.whodunnit = nil
-    ::PaperTrail.controller_info = {} if defined? ::Rails
-  end
+# before hook for Cucumber
+before do
+  ::PaperTrail.enabled = false
+  ::PaperTrail.whodunnit = nil
+  ::PaperTrail.controller_info = {} if defined? ::Rails
+end
 
-  module PaperTrail
-    module Cucumber
-      module Extensions
-        # :call-seq:
-        # with_versioning
-        #
-        # enable versioning for specific blocks
+module PaperTrail
+  module Cucumber
+    module Extensions
+      # :call-seq:
+      # with_versioning
+      #
+      # enable versioning for specific blocks
 
-        def with_versioning
-          was_enabled = ::PaperTrail.enabled?
-          ::PaperTrail.enabled = true
-          begin
-            yield
-          ensure
-            ::PaperTrail.enabled = was_enabled
-          end
+      def with_versioning
+        was_enabled = ::PaperTrail.enabled?
+        ::PaperTrail.enabled = true
+        begin
+          yield
+        ensure
+          ::PaperTrail.enabled = was_enabled
         end
       end
     end
   end
-
-  World PaperTrail::Cucumber::Extensions
 end
+
+World PaperTrail::Cucumber::Extensions

data/lib/paper_trail/frameworks/rails.rb

@@ -47,7 +47,7 @@ module PaperTrail
       # Override this method in your controller to specify when PaperTrail should
       # be off.
       def paper_trail_enabled_for_controller
-        true
+        ::PaperTrail.enabled?
       end
 
       private