paper_trail 3.0.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c90dbeb20af0ebaa74cf679e80b9d78b299af92d
-  data.tar.gz: b2f30b7cc6460365f92e6d5e7c92873624f1187c
+  metadata.gz: 1054af34e2822ac77b034943d283274d8a9daa62
+  data.tar.gz: 219b4b1fd749df6babf4517ff056ae223ba6bb6e
 SHA512:
-  metadata.gz: cca17faa39ff342de70157ee32913040fe1ad6098d0f0b446ff470a944071d1b50486c04eba658f021f4ef65d75637cdb0df78cb306275011748ec38847ec887
-  data.tar.gz: 94fc8094261b8c401e228142eeba8d51f5aa5c54a67b522f54e83b9f42562d80feeb981e86b5c73b45094d045d92b3e7f0285571b0e6dd1c78e2d60e07586225
+  metadata.gz: 0397014880df4049900f6191b41d31c70b4bee0373943dfd1fd8cc876ed4ed220273a5e973c8d8bae471be9ebc875d12b23ede208bf246ebe2247a230fc99f03
+  data.tar.gz: 9697bea9302726a452c319909a77face2e281392ca29a187f1bd7d5c3f35ce92b1ba94e3c9698aca50b5c88623d0bcb0b7f66fc692a2fe723a7ef171efece060

data/.travis.yml

@@ -6,11 +6,14 @@ rvm:
   - jruby-19mode
   - jruby-18mode
 
+before_install: gem update --system 2.2.1
+
 gemfile:
   - Gemfile
   - gemfiles/3.0.gemfile
 
 matrix:
+  fast_finish: true
   allow_failures:
     - rvm: jruby-18mode
       gemfile: Gemfile

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 3.0.1
+
+  - [#340](https://github.com/airblade/paper_trail/issues/340) - Prevent potential error encountered when using the `InstallGenerator`
+    with Rails `4.1.0.rc1`.
+  - [#334](https://github.com/airblade/paper_trail/pull/334) - Add small-scope `whodunnit` method to `PaperTrail::Model::InstanceMethods`.
+  - [#329](https://github.com/airblade/paper_trail/issues/329) - Add `touch_with_version` method to `PaperTrail::Model::InstanceMethods`,
+    to allow for generating a version `touch`ing a model.
+  - [#328](https://github.com/airblade/paper_trail/pull/328) / [#326](https://github.com/airblade/paper_trail/issues/326) /
+    [#307](https://github.com/airblade/paper_trail/issues/307) - `Model.paper_trail_enabled_for_model?` and
+    `model_instance.without_versioning` is now thread-safe.
+  - [#316](https://github.com/airblade/paper_trail/issues/316) - `user_for_paper_trail` should default to `current_user.try(:id)`
+    instead of `current_user` (if `current_user` is defined).
+  - [#313](https://github.com/airblade/paper_trail/pull/313) - Make the `Rails::Controller` helper compatible with
+    `ActionController::API` for compatibility with the [`rails-api`](https://github.com/rails-api/rails-api) gem.
+  - [#312](https://github.com/airblade/paper_trail/issues/312) - Fix RSpec `with_versioning` class level helper method.
+  - `model_instance.without_versioning` now yields the `model_instance`, enabling syntax like this:
+    `model_instance.without_versioning { |obj| obj.update_attributes(:name => 'value') }`.
+  - Deprecated `Model.paper_trail_on` and `Model.paper_trail_off` in favor of bang versions of the methods. Deprecation warning
+    informs users that the non-bang versions of the methods will be removed in version `3.1.0`.
+
 ## 3.0.0
 
   - [#305](https://github.com/airblade/paper_trail/pull/305) - `PaperTrail::VERSION` should be loaded at runtime.
@@ -35,11 +55,11 @@
 ## 2.7.2
 
   - [#228](https://github.com/airblade/paper_trail/issues/228) - Refactored default `user_for_paper_trail` method implementation
-  so that `current_user` only gets invoked if it is defined.
+    so that `current_user` only gets invoked if it is defined.
   - [#219](https://github.com/airblade/paper_trail/pull/219) - Fixed issue where attributes stored with `nil` value might not get
-  reified properly depending on the way the serializer worked.
+    reified properly depending on the way the serializer worked.
   - [#213](https://github.com/airblade/paper_trail/issues/213) - Added a `version_limit` option to the `PaperTrail::Config` options
-  that can be used to restrict the number of versions PaperTrail will store per object instance.
+    that can be used to restrict the number of versions PaperTrail will store per object instance.
   - [#187](https://github.com/airblade/paper_trail/pull/187) - Confirmed JRuby support.
   - [#174](https://github.com/airblade/paper_trail/pull/174) - The `event` field on the versions table can now be customized.
 

data/README.md

@@ -1,4 +1,4 @@
-# PaperTrail [![Build Status](https://secure.travis-ci.org/airblade/paper_trail.png?branch=master)](http://travis-ci.org/airblade/paper_trail) [![Dependency Status](https://gemnasium.com/airblade/paper_trail.png)](https://gemnasium.com/airblade/paper_trail)
+# PaperTrail [![Build Status](https://img.shields.io/travis/airblade/paper_trail/master.svg)](https://travis-ci.org/airblade/paper_trail) [![Dependency Status](https://img.shields.io/gemnasium/airblade/paper_trail.svg)](https://gemnasium.com/airblade/paper_trail)
 
 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.
 
@@ -42,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'`
+    `gem 'paper_trail', '~> 3.0.1'`
 
 2. Generate a migration which will add a `versions` table to your database.
 
@@ -57,14 +57,14 @@ 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  `ActiveRecord` 4. It is also recommended to use the 
+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'`
+    `gem 'paper_trail', '~> 3.0.1'`
 
 2. Generate a migration to add a `versions` table to your database.
 
@@ -126,11 +126,18 @@ widget.previous_version
 # Returns the widget (not a version) as it became next.
 widget.next_version
 
+# Generates a version for a `touch` event (`widget.touch` does NOT generate a version)
+widget.touch_with_version
+
 # Turn PaperTrail off for all widgets.
-Widget.paper_trail_off
+Widget.paper_trail_off!
 
 # Turn PaperTrail on for all widgets.
-Widget.paper_trail_on
+Widget.paper_trail_on!
+
+# Check wheter PaperTrail is enabled for all widgets
+Widget.paper_trail_enabled_for_model?
+widget.paper_trail_enabled_for_model?
 ```
 
 And a `PaperTrail::Version` instance has these methods:
@@ -408,11 +415,9 @@ You can call `previous_version` and `next_version` on an item to get it as it wa
 >> 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
+>> widget.next_version                   # live_widget
 ```
 
-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.
-
 If instead you have a particular `version` of an item you can navigate to the previous and next versions.
 
 ```ruby
@@ -459,7 +464,7 @@ You may want PaperTrail to call a different method to find out who is responsibl
 ```ruby
 class ApplicationController
   def user_for_paper_trail
-    logged_in? ? current_member : 'Public user'  # or whatever
+    logged_in? ? current_member.id : 'Public user'  # or whatever
   end
 end
 ```
@@ -475,15 +480,28 @@ In a console session you can manually set who is responsible like this:
 You can avoid having to do this manually by setting your initializer to pick up the username of the current user from the OS, like this:
 
 ```ruby
-class PaperTrail::Version < ActiveRecord::Base
-  if defined?(Rails::Console)
-    PaperTrail.whodunnit = "#{`whoami`.strip}: console"
-  elsif File.basename($0) == "rake"
-    PaperTrail.whodunnit = "#{`whoami`.strip}: rake #{ARGV.join ' '}"
-  end
+# config/initializers/paper_trail.rb
+if defined?(::Rails::Console)
+  PaperTrail.whodunnit = "#{`whoami`.strip}: console"
+elsif File.basename($0) == "rake"
+  PaperTrail.whodunnit = "#{`whoami`.strip}: rake #{ARGV.join ' '}"
 end
 ```
 
+Sometimes you want to define who is responsible for a change in a small scope without overwriting value of `PaperTrail.whodunnit`. It is possible to define the `whodunnit` value for an operation inside a block like this:
+
+```ruby
+>> PaperTrail.whodunnit = 'Andy Stewart'
+>> widget.whodunnit('Lucas Souza') do
+>>   widget.update_attributes :name => 'Wibble'
+>> end
+>> widget.versions.last.whodunnit              # Lucas Souza
+>> widget.update_attributes :name => 'Clair'
+>> widget.versions.last.whodunnit              # Andy Stewart
+>> widget.whodunnit('Ben Atkins') { |w| w.update_attributes :name => 'Beth' } # this syntax also works
+>> widget.versions.last.whodunnit              # Ben Atkins
+```
+
 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.
@@ -535,7 +553,7 @@ Alternatively you could store certain metadata for one type of version, and othe
 
 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`):
+- either declare the `PaperTrail::Version` class to be abstract like this (in an initializer):
 
 ```ruby
 PaperTrail::Version.module_eval do
@@ -575,8 +593,14 @@ If you can think of a good way to achieve this, please let me know.
 PaperTrail can restore `:has_one` associations as they were at (actually, 3 seconds before) the time.
 
 ```ruby
+class Location < ActiveRecord::Base
+  belongs_to :treasure
+  has_paper_trail
+end
+
 class Treasure < ActiveRecord::Base
   has_one :location
+  has_paper_trail
 end
 
 >> treasure.amount                  # 100
@@ -691,7 +715,7 @@ PaperTrail will call your proc with the current article and store the result in
 N.B.  You must also:
 
 * Add your metadata columns to the `versions` table.
-* Declare your metadata columns using `attr_accessible`.
+* Declare your metadata columns using `attr_accessible`. (If you are using `ActiveRecord 3`, or `ActiveRecord 4` with the [ProtectedAttributes](https://github.com/rails/protected_attributes) gem)
 
 For example:
 
@@ -724,12 +748,14 @@ end
 
 Remember to add those extra columns to your `versions` table and use `attr_accessible` ;)
 
+**NOTE FOR RAILS 4:** If you're using [Strong Parameters](https://github.com/rails/strong_parameters) in Rails 4 and have *not* included the `protected_attributes` gem, there's no need to declare your metadata columns using `attr_accessible`.
+
 
 ## Diffing Versions
 
 There are two scenarios: diffing adjacent versions and diffing non-adjacent versions.
 
-The best way to diff adjacent versions is to get PaperTrail to do it for you.  If you add an `object_changes` text column to your `versions` table, either at installation time with the `--with-changes` option or manually, PaperTrail will store the `changes` diff (excluding any attributes PaperTrail is ignoring) in each `update` version.  You can use the `version.changeset` method to retrieve it.  For example:
+The best way to diff adjacent versions is to get PaperTrail to do it for you.  If you add an `object_changes` text column to your `versions` table, either at installation time with the `rails generate paper_trail:install --with-changes` option or manually, PaperTrail will store the `changes` diff (excluding any attributes PaperTrail is ignoring) in each `update` version.  You can use the `version.changeset` method to retrieve it.  For example:
 
 ```ruby
 >> widget = Widget.create :name => 'Bob'
@@ -772,7 +798,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 (note: this gets done automatically for `RSpec and `Cucumber`, please see the [Testing section](#testing)):
+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
@@ -823,13 +849,13 @@ end
 If you are about change some widgets and you don't want a paper trail of your changes, you can turn PaperTrail off like this:
 
 ```ruby
->> Widget.paper_trail_off
+>> Widget.paper_trail_off!
 ```
 
 And on again like this:
 
 ```ruby
->> Widget.paper_trail_on
+>> Widget.paper_trail_on!
 ```
 
 ### Per method call
@@ -1055,6 +1081,7 @@ Many thanks to:
 * [Vlad Bokov](https://github.com/razum2um)
 * [Sean Marcia](https://github.com/SeanMarcia)
 * [Chulki Lee](https://github.com/chulkilee)
+* [Lucas Souza](https://github.com/lucasas)
 
 
 ## Inspirations

data/gemfiles/3.0.gemfile

@@ -19,6 +19,7 @@ group :development, :test do
 
   # RSpec testing
   gem 'rspec-rails', '~> 2.14'
+  gem 'generator_spec'
 
   platforms :jruby, :ruby_18 do
     # shoulda-matchers > 2.0 is not compatible with Ruby18.

data/lib/generators/paper_trail/install_generator.rb

@@ -1,5 +1,4 @@
 require 'rails/generators'
-require 'rails/generators/migration'
 require 'rails/generators/active_record'
 
 module PaperTrail
@@ -13,7 +12,7 @@ module PaperTrail
 
     def create_migration_file
       migration_template 'create_versions.rb', 'db/migrate/create_versions.rb'
-      migration_template 'add_object_changes_column_to_versions.rb', 'db/migrate/add_object_changes_column_to_versions.rb' if options.with_changes?
+      migration_template 'add_object_changes_to_versions.rb', 'db/migrate/add_object_changes_to_versions.rb' if options.with_changes?
     end
 
     def self.next_migration_number(dirname)

data/lib/generators/paper_trail/templates/add_object_changes_to_versions.rb

@@ -0,0 +1,5 @@
+class AddObjectChangesToVersions < ActiveRecord::Migration
+  def change
+    add_column :versions, :object_changes, :text
+  end
+end

data/lib/generators/paper_trail/templates/create_versions.rb

@@ -1,5 +1,5 @@
 class CreateVersions < ActiveRecord::Migration
-  def self.up
+  def change
     create_table :versions do |t|
       t.string   :item_type, :null => false
       t.integer  :item_id,   :null => false
@@ -10,9 +10,4 @@ class CreateVersions < ActiveRecord::Migration
     end
     add_index :versions, [:item_type, :item_id]
   end
-
-  def self.down
-    remove_index :versions, [:item_type, :item_id]
-    drop_table :versions
-  end
 end

data/lib/paper_trail.rb

@@ -32,6 +32,16 @@ module PaperTrail
     !!paper_trail_store[:request_enabled_for_controller]
   end
 
+  # Sets whether PaperTrail is enabled or disabled for this model in the current request.
+  def self.enabled_for_model(model, value)
+    paper_trail_store[:"enabled_for_#{model}"] = value
+  end
+
+  # Returns `true` if PaperTrail is enabled for this model in the current request, `false` otherwise.
+  def self.enabled_for_model?(model)
+    !!paper_trail_store.fetch(:"enabled_for_#{model}", true)
+  end
+
   # Set the field which records when a version was created.
   def self.timestamp_field=(field_name)
     PaperTrail.config.timestamp_field = field_name
@@ -79,7 +89,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::MAJOR < 4 || !!defined?(ProtectedAttributes)
   end
 
   private

data/lib/paper_trail/frameworks/rails.rb

@@ -3,7 +3,7 @@ module PaperTrail
     module Controller
 
       def self.included(base)
-        if defined?(ActionController) && base == ActionController::Base
+        if defined?(ActionController) && (base == ActionController::Base || base == ActionController::API)
           base.before_filter :set_paper_trail_enabled_for_controller
           base.before_filter :set_paper_trail_whodunnit, :set_paper_trail_controller_info
         end
@@ -17,7 +17,7 @@ module PaperTrail
       # Override this method in your controller to call a different
       # method, e.g. `current_person`, or anything you like.
       def user_for_paper_trail
-        current_user if defined?(current_user)
+        current_user.try(:id) if defined?(current_user)
       end
 
       # Returns any information about the controller or request that you

data/lib/paper_trail/frameworks/rspec.rb

@@ -1,9 +1,10 @@
 require 'rspec/core'
 require 'rspec/matchers'
-require File.expand_path('../rspec/extensions', __FILE__)
+require 'paper_trail/frameworks/rspec/helpers'
 
 RSpec.configure do |config|
-  config.include ::PaperTrail::RSpec::Extensions
+  config.include ::PaperTrail::RSpec::Helpers::InstanceMethods
+  config.extend ::PaperTrail::RSpec::Helpers::ClassMethods
 
   config.before(:each) do
     ::PaperTrail.enabled = false

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

@@ -0,0 +1,25 @@
+module PaperTrail
+  module RSpec
+    module Helpers
+      module InstanceMethods
+        # enable versioning for specific blocks (at instance-level)
+        def with_versioning
+          was_enabled = ::PaperTrail.enabled?
+          ::PaperTrail.enabled = true
+          yield
+        ensure
+          ::PaperTrail.enabled = was_enabled
+        end
+      end
+
+      module ClassMethods
+        # enable versioning for specific blocks (at class-level)
+        def with_versioning(&block)
+          context 'with versioning', :versioning => true do
+            class_exec(&block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/paper_trail/frameworks/sinatra.rb

@@ -15,7 +15,7 @@ module PaperTrail
     # Override this method in your controller to call a different
     # method, e.g. `current_person`, or anything you like.
     def user_for_paper_trail
-      current_user if defined?(current_user)
+      current_user.try(:id) if defined?(current_user)
     end
 
     private

data/lib/paper_trail/has_paper_trail.rb

@@ -14,11 +14,11 @@ module PaperTrail
       #               `:create`, `:update`, `:destroy` as desired.
       # :class_name   the name of a custom Version class.  This class should inherit from `PaperTrail::Version`.
       # :ignore       an array of attributes for which a new `Version` will not be created if only they change.
-      #               it can also aceept a Hash as an argument where the key is the attribute to ignore (a `String` or `Symbol`), 
+      #               it can also aceept a Hash as an argument where the key is the attribute to ignore (a `String` or `Symbol`),
       #               which will only be ignored if the value is a `Proc` which returns truthily.
       # :if, :unless  Procs that allow to specify conditions when to save versions for an object
       # :only         inverse of `ignore` - a new `Version` will be created only for these attributes if supplied
-      #               it can also aceept a Hash as an argument where the key is the attribute to track (a `String` or `Symbol`), 
+      #               it can also aceept a Hash as an argument where the key is the attribute to track (a `String` or `Symbol`),
       #               which will only be counted if the value is a `Proc` which returns truthily.
       # :skip         fields to ignore completely.  As with `ignore`, updates to these fields will not create
       #               a new `Version`.  In addition, these fields will not be included in the serialized versions
@@ -54,15 +54,12 @@ module PaperTrail
 
         paper_trail_options[:meta] ||= {}
 
-        class_attribute :paper_trail_enabled_for_model
-        self.paper_trail_enabled_for_model = true
-
         class_attribute :versions_association_name
         self.versions_association_name = options[:versions] || :versions
 
         attr_accessor :paper_trail_event
 
-        if ::ActiveRecord::VERSION::STRING.to_f >= 4.0 # `has_many` syntax for specifying order uses a lambda in Rails 4
+        if ::ActiveRecord::VERSION::MAJOR >= 4 # `has_many` syntax for specifying order uses a lambda in Rails 4
           has_many self.versions_association_name,
             lambda { order("#{PaperTrail.timestamp_field} ASC") },
             :class_name => self.version_class_name, :as => :item
@@ -80,13 +77,27 @@ module PaperTrail
       end
 
       # Switches PaperTrail off for this class.
+      def paper_trail_off!
+        PaperTrail.enabled_for_model(self, false)
+      end
+
       def paper_trail_off
-        self.paper_trail_enabled_for_model = false
+        warn "DEPRECATED: use `paper_trail_off!` instead of `paper_trail_off`. Support for `paper_trail_off` will be removed in PaperTrail 3.1"
+        self.paper_trail_off!
       end
 
       # Switches PaperTrail on for this class.
-      def paper_trail_on
-        self.paper_trail_enabled_for_model = true
+      def paper_trail_on!
+        PaperTrail.enabled_for_model(self, true)
+      end
+
+	    def paper_trail_on
+        warn "DEPRECATED: use `paper_trail_on!` instead of `paper_trail_on`. Support for `paper_trail_on` will be removed in PaperTrail 3.1"
+        self.paper_trail_on!
+      end
+
+      def paper_trail_enabled_for_model?
+        PaperTrail.enabled_for_model?(self)
       end
 
       def paper_trail_version_class
@@ -192,13 +203,43 @@ module PaperTrail
         nil
       end
 
+      def paper_trail_enabled_for_model?
+        self.class.paper_trail_enabled_for_model?
+      end
+
       # Executes the given method or block without creating a new version.
       def without_versioning(method = nil)
-        paper_trail_was_enabled = self.paper_trail_enabled_for_model
-        self.class.paper_trail_off
-        method ? method.to_proc.call(self) : yield
+        paper_trail_was_enabled = self.paper_trail_enabled_for_model?
+        self.class.paper_trail_off!
+        method ? method.to_proc.call(self) : yield(self)
+      ensure
+        self.class.paper_trail_on! if paper_trail_was_enabled
+      end
+
+      # Temporarily overwrites the value of whodunnit and then executes the provided block.
+      def whodunnit(value)
+        raise ArgumentError, 'expected to receive a block' unless block_given?
+        current_whodunnit = PaperTrail.whodunnit
+        PaperTrail.whodunnit = value
+        yield self
       ensure
-        self.class.paper_trail_on if paper_trail_was_enabled
+        PaperTrail.whodunnit = current_whodunnit
+      end
+
+      # Mimicks behavior of `touch` method from `ActiveRecord::Persistence`, but generates a version
+      #
+      # TODO: lookinto leveraging the `after_touch` callback from `ActiveRecord` to allow the
+      #  regular `touch` method go generate a version as normal. May make sense to switch the `record_update`
+      #  method to leverage an `after_update` callback anyways (likely for v3.1.0)
+      def touch_with_version(name = nil)
+        raise ActiveRecordError, "can not touch on a new record object" unless persisted?
+
+        attributes = timestamp_attributes_for_update_in_model
+        attributes << name if name
+        current_time = current_time_from_proper_timezone
+
+        attributes.each { |column| write_attribute(column, current_time) }
+        save!
       end
 
       private
@@ -323,7 +364,7 @@ module PaperTrail
       end
 
       def paper_trail_switched_on?
-        PaperTrail.enabled? && PaperTrail.enabled_for_controller? && self.paper_trail_enabled_for_model
+        PaperTrail.enabled? && PaperTrail.enabled_for_controller? && self.paper_trail_enabled_for_model?
       end
 
       def save_version?

data/lib/paper_trail/version_number.rb

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

data/paper_trail.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'sinatra', '~> 1.0'
   s.add_development_dependency 'rack-test', '>= 0.6'
   s.add_development_dependency 'rspec-rails', '~> 2.14'
+  s.add_development_dependency 'generator_spec'
 
   # JRuby support for the test ENV
   unless defined?(JRUBY_VERSION)

data/spec/generators/install_generator_spec.rb

@@ -0,0 +1,67 @@
+require 'spec_helper'
+require 'generator_spec/test_case'
+require File.expand_path('../../../lib/generators/paper_trail/install_generator', __FILE__)
+
+describe PaperTrail::InstallGenerator, :type => :generator do
+  include GeneratorSpec::TestCase
+  destination File.expand_path('../tmp', __FILE__)
+
+  after(:all) { prepare_destination } # cleanup the tmp directory
+
+  describe "no options" do
+    before(:all) do
+      prepare_destination
+      run_generator
+    end
+  
+    it "generates a migration for creating the 'versions' table" do
+      destination_root.should have_structure {
+        directory 'db' do
+          directory 'migrate' do
+            migration 'create_versions' do
+              contains 'class CreateVersions'
+              contains 'def change'
+              contains 'create_table :versions do |t|'
+            end
+          end
+        end
+      }
+    end
+  end
+
+  describe "`--with-changes` option set to `true`" do
+    before(:all) do
+      prepare_destination
+      run_generator %w(--with-changes)
+    end
+
+    it "generates a migration for creating the 'versions' table" do
+      destination_root.should have_structure {
+        directory 'db' do
+          directory 'migrate' do
+            migration 'create_versions' do
+              contains 'class CreateVersions'
+              contains 'def change'
+              contains 'create_table :versions do |t|'
+            end
+          end
+        end
+      }
+    end
+
+    it "generates a migration for adding the 'object_changes' column to the 'versions' table" do
+      destination_root.should have_structure {
+        directory 'db' do
+          directory 'migrate' do
+            migration 'add_object_changes_to_versions' do
+              contains 'class AddObjectChangesToVersions'
+              contains 'def change'
+              contains 'add_column :versions, :object_changes, :text'
+            end
+          end
+        end
+      }
+    end
+  end
+
+end

data/spec/models/widget_spec.rb

@@ -5,9 +5,9 @@ describe Widget do
     it { should be_versioned }
   end
 
-  describe "`versioning` option" do
-    let(:widget) { Widget.create :name => 'Bob', :an_integer => 1 }
+  let(:widget) { Widget.create :name => 'Bob', :an_integer => 1 }
 
+  describe "`versioning` option" do
     context :enabled, :versioning => true do
       it 'should enable versioning for models wrapped within a block' do
         widget.versions.size.should == 1
@@ -20,4 +20,122 @@ describe Widget do
       end
     end
   end
+
+  describe "Methods" do
+    describe "Instance", :versioning => true do
+      describe :whodunnit do
+        it { should respond_to(:whodunnit) }
+
+        context "no block given" do
+          it "should raise an error" do
+            expect { widget.whodunnit('Ben') }.to raise_error(ArgumentError, 'expected to receive a block')
+          end
+        end
+
+        context "block given" do
+          let(:orig_name) { Faker::Name.name }
+          let(:new_name) { Faker::Name.name }
+
+          before do
+            PaperTrail.whodunnit = orig_name
+            widget.versions.last.whodunnit.should == orig_name # persist `widget`
+          end
+
+          it "should modify value of `PaperTrail.whodunnit` while executing the block" do
+            widget.whodunnit(new_name) do
+              PaperTrail.whodunnit.should == new_name
+              widget.update_attributes(:name => 'Elizabeth')
+            end
+            widget.versions.last.whodunnit.should == new_name
+          end
+
+          it "should revert the value of `PaperTrail.whodunnit` to it's previous value after executing the block" do
+            widget.whodunnit(new_name) { |w| w.update_attributes(:name => 'Elizabeth') }
+            PaperTrail.whodunnit.should == orig_name
+          end
+
+          context "error within block" do
+            it "should ensure that the whodunnit value still reverts to it's previous value" do
+              expect { widget.whodunnit(new_name) { raise } }.to raise_error
+              PaperTrail.whodunnit.should == orig_name
+            end
+          end
+        end
+      end
+
+      describe :touch_with_version do
+        it { should respond_to(:touch_with_version) }
+
+        it "should generate a version" do
+          count = widget.versions.size
+          widget.touch_with_version
+          widget.versions.size.should == count + 1
+        end
+
+        it "should increment the `:updated_at` timestamp" do
+          time_was = widget.updated_at
+          widget.touch_with_version
+          widget.updated_at.should > time_was
+        end
+      end
+    end
+
+    describe "Class" do
+      subject { Widget }
+
+      describe :paper_trail_off! do
+        it { should respond_to(:paper_trail_off!) }
+
+        it 'should set the `paper_trail_enabled_for_model?` to `false`' do
+          subject.paper_trail_enabled_for_model?.should be_true
+          subject.paper_trail_off!
+          subject.paper_trail_enabled_for_model?.should be_false
+        end
+      end
+
+      describe :paper_trail_off do
+        it { should respond_to(:paper_trail_off) }
+
+        it 'should set the invoke `paper_trail_off!`' do
+          subject.should_receive(:warn)
+          subject.should_receive(:paper_trail_off!)
+          subject.paper_trail_off
+        end
+
+        it 'should display a deprecation warning' do
+          subject.should_receive(:warn).with("DEPRECATED: use `paper_trail_on!` instead of `paper_trail_on`. Support for `paper_trail_on` will be removed in PaperTrail 3.1")
+          subject.paper_trail_on
+        end
+      end
+
+      describe :paper_trail_on! do
+        before { subject.paper_trail_off! }
+
+        it { should respond_to(:paper_trail_on!) }
+
+        it 'should set the `paper_trail_enabled_for_model?` to `true`' do
+          subject.paper_trail_enabled_for_model?.should be_false
+          subject.paper_trail_on!
+          subject.paper_trail_enabled_for_model?.should be_true
+        end
+      end
+
+      describe :paper_trail_on do
+        before { subject.paper_trail_off! }
+
+        it { should respond_to(:paper_trail_on) }
+
+        it 'should set the invoke `paper_trail_on!`' do
+          subject.should_receive(:warn)
+          subject.should_receive(:paper_trail_on!)
+          subject.paper_trail_on
+        end
+
+        it 'should display a deprecation warning' do
+          subject.should_receive(:warn).with("DEPRECATED: use `paper_trail_on!` instead of `paper_trail_on`. Support for `paper_trail_on` will be removed in PaperTrail 3.1")
+          subject.paper_trail_on
+        end
+      end
+    end
+  end
 end

data/spec/paper_trail_spec.rb

@@ -5,13 +5,21 @@ describe "PaperTrail RSpec Helper" do
     it 'should have versioning off by default' do
       ::PaperTrail.should_not be_enabled
     end
-    it 'should turn versioning on in a with_versioning block' do
+    it 'should turn versioning on in a `with_versioning` block' do
       ::PaperTrail.should_not be_enabled
       with_versioning do
         ::PaperTrail.should be_enabled
       end
       ::PaperTrail.should_not be_enabled
     end
+
+    context "error within `with_versioning` block" do
+      it "should revert the value of `PaperTrail.enabled?` to it's previous state" do
+        ::PaperTrail.should_not be_enabled
+        expect { with_versioning { raise } }.to raise_error
+        ::PaperTrail.should_not be_enabled
+      end
+    end
   end
 
   context '`versioning: true`', :versioning => true do
@@ -27,6 +35,19 @@ describe "PaperTrail RSpec Helper" do
     end
   end
 
+  context '`with_versioning` block at class level' do
+    it { ::PaperTrail.should_not be_enabled }
+
+    with_versioning do
+      it 'should have versioning on by default' do
+        ::PaperTrail.should be_enabled
+      end
+    end
+    it 'should not leak the `enabled?` state into successive tests' do
+      ::PaperTrail.should_not be_enabled
+    end
+  end
+
   describe :whodunnit do
     before(:all) { ::PaperTrail.whodunnit = 'foobar' }
 

data/spec/requests/articles_spec.rb

@@ -1,23 +1,19 @@
-RSpec.configure do |c|
-  c.order = 'defined'
-end
-
 require 'spec_helper'
 
 describe "Articles" do
   let(:valid_params) { { :article => { :title => 'Doh', :content => Faker::Lorem.sentence } } }
 
   context "versioning disabled" do
-    specify { PaperTrail.enabled?.should be_false }
+    specify { PaperTrail.should_not be_enabled }
 
     it "should not create a version" do
-      PaperTrail.enabled_for_controller?.should be_true
+      PaperTrail.should be_enabled_for_controller
       expect { post articles_path(valid_params) }.to_not change(PaperTrail::Version, :count)
-      PaperTrail.enabled_for_controller?.should be_false
+      PaperTrail.should_not be_enabled_for_controller
     end
 
-    it "should not leak the state of the `PaperTrail.enabled_for_controlller?` into the next test" do
-      PaperTrail.enabled_for_controller?.should be_true
+    it "should not leak the state of the `PaperTrail.enabled_for_controller?` into the next test" do
+      PaperTrail.should be_enabled_for_controller
     end
   end
 end

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/test/dummy/app/controllers/application_controller.rb

@@ -7,7 +7,10 @@ class ApplicationController < ActionController::Base
 
   # Returns id of hypothetical current user
   def current_user
-    153
+    @current_user ||= OpenStruct.new(:id => 153).tap do |obj|
+      # Invoking `id` returns the `object_id` value in Ruby18 unless specifically overwritten
+      def obj.id; 153; end if RUBY_VERSION.to_f < 1.9
+    end
   end
 
   def info_for_paper_trail

data/test/dummy/app/controllers/test_controller.rb

@@ -1,5 +1,5 @@
 class TestController < ActionController::Base
-  def current_user
+  def user_for_paper_trail
     Thread.current.object_id
   end
 end

data/test/dummy/app/models/elephant.rb

@@ -1,3 +1,3 @@
 class Elephant < Animal
-  paper_trail_off
+  paper_trail_off!
 end

data/test/dummy/app/models/widget.rb

@@ -2,7 +2,7 @@ class Widget < ActiveRecord::Base
   has_paper_trail
   has_one :wotsit
 
-  if ActiveRecord::VERSION::STRING.to_f >= 4.0 # `has_many` syntax for specifying order uses a lambda in Rails 4
+  if ::ActiveRecord::VERSION::MAJOR >= 4 # `has_many` syntax for specifying order uses a lambda in Rails 4
     has_many :fluxors, lambda { order(:name) }
   else
     has_many :fluxors, :order => :name

data/test/dummy/db/migrate/20110208155312_set_up_test_tables.rb

@@ -10,9 +10,9 @@ class SetUpTestTables < ActiveRecord::Migration
       t.time      :a_time
       t.date      :a_date
       t.boolean   :a_boolean
-      t.datetime  :created_at, :updated_at
       t.string    :sacrificial_column
       t.string    :type
+      t.timestamps
     end
 
     create_table :versions, :force => true do |t|
@@ -54,7 +54,7 @@ class SetUpTestTables < ActiveRecord::Migration
     create_table :wotsits, :force => true do |t|
       t.integer :widget_id
       t.string  :name
-      t.datetime :created_at, :updated_at
+      t.timestamps
     end
 
     create_table :fluxors, :force => true do |t|

data/test/dummy/db/schema.rb

@@ -71,6 +71,7 @@ ActiveRecord::Schema.define(:version => 20110208155312) do
     t.integer  "article_id"
     t.string   "ip"
     t.string   "user_agent"
+    t.text     :object_changes
   end
 
   add_index "versions", ["item_type", "item_id"], :name => "index_versions_on_item_type_and_item_id"

data/test/functional/modular_sinatra_test.rb

@@ -12,7 +12,10 @@ class BaseApp < Sinatra::Base
   end
 
   def current_user
-    'foobar'
+    @current_user ||= OpenStruct.new(:id => 'foobar').tap do |obj|
+      # Invoking `id` returns the `object_id` value in Ruby18 unless specifically overwritten
+      def obj.id; 'foobar'; end if RUBY_VERSION.to_f < 1.9
+    end
   end
 end
 

data/test/functional/sinatra_test.rb

@@ -12,7 +12,10 @@ class Sinatra::Application
   end
 
   def current_user
-    'raboof'
+    @current_user ||= OpenStruct.new(:id => 'raboof').tap do |obj|
+      # Invoking `id` returns the `object_id` value in Ruby18 unless specifically overwritten
+      def obj.id; 'raboof'; end if RUBY_VERSION.to_f < 1.9
+    end
   end
 
 end

data/test/functional/thread_safety_test.rb

@@ -1,7 +1,7 @@
 require 'test_helper'
 
 class ThreadSafetyTest < ActionController::TestCase
-  test "be thread safe" do
+  test "be thread safe when using #set_paper_trail_whodunnit" do
     blocked = true
 
     slow_thread = Thread.new do
@@ -23,4 +23,26 @@ class ThreadSafetyTest < ActionController::TestCase
 
     assert_not_equal slow_thread.value, fast_thread.value
   end
+
+  test "be thread safe when using #without_versioning" do
+    enabled = nil
+
+    slow_thread = Thread.new do
+      Widget.new.without_versioning do
+        sleep(0.01)
+        enabled = Widget.paper_trail_enabled_for_model?
+        sleep(0.01)
+      end
+      enabled
+    end
+
+    fast_thread = Thread.new do
+      sleep(0.005)
+      Widget.paper_trail_enabled_for_model?
+    end
+
+    assert_not_equal slow_thread.value, fast_thread.value
+    assert Widget.paper_trail_enabled_for_model?
+    assert PaperTrail.enabled_for_model?(Widget)
+  end
 end

data/test/unit/model_test.rb

@@ -478,11 +478,11 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
 
     context 'with its paper trail turned off' do
       setup do
-        Widget.paper_trail_off
+        Widget.paper_trail_off!
         @count = @widget.versions.length
       end
 
-      teardown { Widget.paper_trail_on }
+      teardown { Widget.paper_trail_on! }
 
       context 'when updated' do
         setup { @widget.update_attributes :name => 'Beeblebrox' }
@@ -495,12 +495,12 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
       context 'when destroyed "without versioning"' do
         should 'leave paper trail off after call' do
           @widget.without_versioning :destroy
-          assert !Widget.paper_trail_enabled_for_model
+          assert !Widget.paper_trail_enabled_for_model?
         end
       end
 
       context 'and then its paper trail turned on' do
-        setup { Widget.paper_trail_on }
+        setup { Widget.paper_trail_on! }
 
         context 'when updated' do
           setup { @widget.update_attributes :name => 'Ford' }
@@ -515,14 +515,28 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
             @widget.without_versioning do
               @widget.update_attributes :name => 'Ford'
             end
+            # The model instance should yield itself for convenience purposes
+            @widget.without_versioning { |w| w.update_attributes :name => 'Nixon' }
           end
 
           should 'not create new version' do
-            assert_equal 1, @widget.versions.length
+            assert_equal @count, @widget.versions.length
           end
 
           should 'enable paper trail after call' do
-            assert Widget.paper_trail_enabled_for_model
+            assert Widget.paper_trail_enabled_for_model?
+          end
+        end
+
+        context 'when receiving a method name as an argument' do
+          setup { @widget.without_versioning(:touch_with_version) }
+
+          should 'not create new version' do
+            assert_equal @count, @widget.versions.length
+          end
+
+          should 'enable paper trail after call' do
+            assert Widget.paper_trail_enabled_for_model?
           end
         end
       end
@@ -615,7 +629,7 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
 
     should 'reify with the correct type' do
       # For some reason this test appears to be broken on AR4 in the test env. Executing it manually in the Rails console seems to work.. not sure what the issues is here.
-      assert_kind_of FooWidget, @foo.versions.last.reify if ActiveRecord::VERSION::STRING.to_f < 4.0
+      assert_kind_of FooWidget, @foo.versions.last.reify if ActiveRecord::VERSION::MAJOR < 4
       assert_equal @foo.versions.first, PaperTrail::Version.last.previous
       assert_nil PaperTrail::Version.last.next
     end
@@ -771,7 +785,7 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
       should 'store dynamic meta data based on a method of the item' do
         assert_equal @article.action_data_provider_method, @article.versions.last.action
       end
-      
+
       should 'store dynamic meta data based on an attribute of the item prior to creation' do
         assert_equal nil, @article.versions.last.title
       end
@@ -793,7 +807,7 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
         should 'store dynamic meta data which depends on the item' do
           assert_equal @article.id, @article.versions.last.article_id
         end
-        
+
         should 'store dynamic meta data based on an attribute of the item prior to the update' do
           assert_equal @initial_title, @article.versions.last.title
         end
@@ -814,7 +828,7 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
         should 'store dynamic meta data which depends on the item' do
           assert_equal @article.id, @article.versions.last.article_id
         end
-        
+
         should 'store dynamic meta data based on an attribute of the item prior to the destruction' do
           assert_equal @initial_title, @article.versions.last.title
         end
@@ -837,7 +851,6 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
     should 'return its previous self' do
       assert_equal @widget.versions[-2].reify, @widget.previous_version
     end
-
   end
 
 
@@ -1060,7 +1073,7 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
         end
         # Need an additional clause to detect what version of ActiveRecord is being used for this test because AR4 injects the `updated_at` column into the changeset for updates to models
         should 'version.object_changes should not have stored the default, ridiculously long (to_yaml) serialization of the TimeZone object' do
-          assert @person.versions.last.object_changes.length < (ActiveRecord::VERSION::STRING.to_f < 4.0 ? 105 : 118), "object_changes length was #{@person.versions.last.object_changes.length}"
+          assert @person.versions.last.object_changes.length < (ActiveRecord::VERSION::MAJOR < 4 ? 105 : 118), "object_changes length was #{@person.versions.last.object_changes.length}"
         end
         # But now it stores the short, serialized value.
         should 'version.object attribute should have stored the value returned by the attribute serializer' do

data/test/unit/protected_attrs_test.rb

@@ -3,7 +3,7 @@ require 'test_helper'
 class ProtectedAttrsTest < ActiveSupport::TestCase
   subject { ProtectedWidget.new }
 
-  if ActiveRecord::VERSION::STRING.to_f < 4.0 # these ActiveModel matchers (provided by shoulda-matchers) only work for Rails 3
+  if ActiveRecord::VERSION::MAJOR < 4 # these ActiveModel matchers (provided by shoulda-matchers) only work for Rails 3
     accessible_attrs = ProtectedWidget.accessible_attributes.to_a
     accessible_attrs.each do |attr_name|
       should allow_mass_assignment_of(attr_name.to_sym)
@@ -36,7 +36,7 @@ class ProtectedAttrsTest < ActiveSupport::TestCase
 
       should 'the previous version should contain right attributes' do
         # For some reason this test seems to be broken in JRuby 1.9 mode in the test env even though it works in the console. WTF?
-        unless ActiveRecord::VERSION::STRING.to_f >= 4.0 && defined?(JRUBY_VERSION) && RUBY_VERSION.to_f >= 1.9
+        unless ActiveRecord::VERSION::MAJOR >= 4 && defined?(JRUBY_VERSION) && RUBY_VERSION.to_f >= 1.9
           assert_equal @widget.previous_version.attributes, @initial_attributes
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: paper_trail
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.0.1
 platform: ruby
 authors:
 - Andy Stewart
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-11 00:00:00.000000000 Z
+date: 2014-03-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -155,6 +155,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: generator_spec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement
@@ -186,7 +200,7 @@ files:
 - gemfiles/3.0.gemfile
 - lib/generators/paper_trail/USAGE
 - lib/generators/paper_trail/install_generator.rb
-- lib/generators/paper_trail/templates/add_object_changes_column_to_versions.rb
+- lib/generators/paper_trail/templates/add_object_changes_to_versions.rb
 - lib/generators/paper_trail/templates/create_versions.rb
 - lib/paper_trail.rb
 - lib/paper_trail/cleaner.rb
@@ -194,7 +208,7 @@ files:
 - lib/paper_trail/frameworks/cucumber.rb
 - lib/paper_trail/frameworks/rails.rb
 - lib/paper_trail/frameworks/rspec.rb
-- lib/paper_trail/frameworks/rspec/extensions.rb
+- lib/paper_trail/frameworks/rspec/helpers.rb
 - lib/paper_trail/frameworks/sinatra.rb
 - lib/paper_trail/has_paper_trail.rb
 - lib/paper_trail/serializers/json.rb
@@ -203,6 +217,7 @@ files:
 - lib/paper_trail/version_concern.rb
 - lib/paper_trail/version_number.rb
 - paper_trail.gemspec
+- spec/generators/install_generator_spec.rb
 - spec/models/joined_version_spec.rb
 - spec/models/version_spec.rb
 - spec/models/widget_spec.rb
@@ -307,11 +322,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: 1.3.6
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.11
+rubygems_version: 2.2.1
 signing_key: 
 specification_version: 4
 summary: Track changes to your models' data. Good for auditing or versioning.
 test_files:
+- spec/generators/install_generator_spec.rb
 - spec/models/joined_version_spec.rb
 - spec/models/version_spec.rb
 - spec/models/widget_spec.rb

data/lib/generators/paper_trail/templates/add_object_changes_column_to_versions.rb

@@ -1,9 +0,0 @@
-class AddObjectChangesColumnToVersions < ActiveRecord::Migration
-  def self.up
-    add_column :versions, :object_changes, :text
-  end
-
-  def self.down
-    remove_column :versions, :object_changes
-  end
-end

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

@@ -1,20 +0,0 @@
-module PaperTrail
-  module RSpec
-    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
-      end
-    end
-  end
-end