paper_trail 2.7.2 → 3.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d52253999aa50ea646f9941296fa663fda663409
-  data.tar.gz: a5e3bb3431519e3b68e4c0c7807b586cbb2e0da5
+  metadata.gz: b667567a3273c0c6d95a75068b7d4e0b5d5c71ba
+  data.tar.gz: 83853768990c1f61e1c9149bc275126254b87415
 SHA512:
-  metadata.gz: 91563f3ad9191ee2f310d4ddc89373207379b0eedde16d0e7cfa719d0a6fa34d9176d1d1f21e5d384030fff06f95f8bdb70c27e0d220867e908c3c36a28b1d33
-  data.tar.gz: a581a7fd4a286cdaec57f1eb7d608db139da015aadb59b461bd201ab8c08e370e086062d7f92c3e51459b2f411c28203e3b481a6982a4f846e79b1b44d0361a3
+  metadata.gz: ba6c131b28bb5a060acdd08839cc53d58407961633389d53775ca0ff47d034964a5d192f56dc3e2315fd0bcd040439b06640120b316e65bfdd68acb9783e0099
+  data.tar.gz: 1e546deade76f16dfd47a2414cf9d0d4021c45fa7d5bf2d825e62f79ba22cc04f0235102fd4c7708ea4f121e8ddedacbc07450ca74dc58c152161887368dc4e8

data/.gitignore

@@ -4,6 +4,7 @@ test/paper_trail_plugin.sqlite3.db
 test/dummy/db/*.sqlite3
 test/dummy/log/*
 test/dummy/tmp/*
+spec/dummy/
 coverage
 pkg/*
 *.gem

data/.rspec

@@ -0,0 +1,3 @@
+--format progress
+--color
+

data/.travis.yml

@@ -2,11 +2,20 @@ language: ruby
 rvm:
   - 2.0.0
   - 1.9.3
-  - 1.9.2
   - 1.8.7
-  - ree
-  - jruby-18mode
   - jruby-19mode
+  - jruby-18mode
+
+before_install:
+  - gem install bundler --version '~> 1.3'
+
+gemfile:
+  - Gemfile
+  - gemfiles/3.0.gemfile
+
 matrix:
   allow_failures:
-    - rvm: 2.0.0
+    - rvm: jruby-18mode
+      gemfile: Gemfile
+    - rvm: 1.8.7
+      gemfile: Gemfile

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 3.0.0 (Unreleased)
+
+  - [#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).
+  - [#235](https://github.com/airblade/paper_trail/pull/235) - Dropped unnecessary secondary sort on `versions` association.
+  - [#216](https://github.com/airblade/paper_trail/pull/216) - Added helper & extension for [RSpec](https://github.com/rspec/rspec),
+    and helper for [Cucumber](http://cukes.info).
+  - [#212](https://github.com/airblade/paper_trail/pull/212) - Added `PaperTrail::Cleaner` module, useful for discarding draft versions.
+  - [#207](https://github.com/airblade/paper_trail/issues/207) - Versions for `'create'` events are now created with `create!` instead of 
+    `create` so that an exception gets raised if it is appropriate to do so.
+  - [#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`.
+
 ## 2.7.2
 
   - [#228](https://github.com/airblade/paper_trail/issues/228) - Refactored default `user_for_paper_trail` method implementation

data/README.md

@@ -1,4 +1,4 @@
-# PaperTrail [![Build Status](https://secure.travis-ci.org/airblade/paper_trail.png)](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://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 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.
 
@@ -29,10 +29,49 @@ There's an excellent [Railscast on implementing Undo with Paper Trail](http://ra
 * Threadsafe.
 
 
-## Rails Version
+## Compatibility
 
-Works on Rails 3 and Rails 2.3.  The Rails 3 code is on the `master` branch and tagged `v2.x`.  The Rails 2.3 code is on the `rails2` branch and tagged `v1.x`.  Please note I'm not adding new features to the Rails 2.3 codebase.
+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
+
+### Rails 3 & 4
+
+1. Install PaperTrail as a gem via your `Gemfile`:
+
+    `gem 'paper_trail', '~> 3.0'`
+
+2. Generate a migration which will add a `versions` table to your database.
+
+    `bundle exec rails generate paper_trail:install`
+
+3. Run the migration.
+
+    `bundle exec rake db:migrate`
+
+4. Add `has_paper_trail` to the models you want to track.
+
+### Sinatra
+
+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`)
+
+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
+require 'sinatra/base'
+
+class BlehApp < Sinatra::Base
+  register Sinatra::PaperTrail
+end
+```
 
 ## API Summary
 
@@ -72,7 +111,7 @@ Widget.paper_trail_off
 Widget.paper_trail_on
 ```
 
-And a `Version` instance has these methods:
+And a `PaperTrail::Version` instance has these methods:
 
 ```ruby
 # Returns the item restored from this version.
@@ -124,7 +163,7 @@ This gives you a `versions` method which returns the paper trail of changes to y
 
 ```ruby
 >> widget = Widget.find 42
->> widget.versions             # [<Version>, <Version>, ...]
+>> widget.versions             # [<PaperTrail::Version>, <PaperTrail::Version>, ...]
 ```
 
 Once you have a version, you can find out what happened:
@@ -150,7 +189,7 @@ PaperTrail stores the pre-change version of the model, unlike some other auditin
 
 >> widget.versions                             # []
 >> widget.update_attributes :name => 'Wotsit'
->> widget.last.reify.name                      # 'Doobly'
+>> widget.versions.last.reify.name             # 'Doobly'
 >> widget.versions.last.event                  # 'update'
 ```
 
@@ -193,7 +232,7 @@ class Article < ActiveRecord::Base
 end
 ```
 
-You may also have the `Version` model save a custom string in it's `event` field instead of the typical `create`, `update`, `destroy`.
+You may also have the `PaperTrail::Version` model save a custom string in it's `event` field instead of the typical `create`, `update`, `destroy`.
 PaperTrail supplies a custom accessor method called `paper_trail_event`, which it will attempt to use to fill the `event` field before
 falling back on one of the default events.
 
@@ -233,7 +272,7 @@ class Article < ActiveRecord::Base
 end
 ```
 
-This means that changes to just the `title` or `rating` will not store another version of the article.  It does not mean that the `title` and `rating` attributes will be ignored if some other change causes a new `Version` to be created.  For example:
+This means that changes to just the `title` or `rating` will not store another version of the article.  It does not mean that the `title` and `rating` attributes will be ignored if some other change causes a new `PaperTrail::Version` to be created.  For example:
 
 ```ruby
 >> a = Article.create
@@ -267,7 +306,7 @@ This means that only changes to the `title` will save a version of the article:
 
 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 `Version`.  In addition, these fields will not be included in the serialised version of the object whenever a new `Version` is created.
+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.
 
 For example:
 
@@ -304,7 +343,7 @@ Undeleting is just as simple:
 >> widget = Widget.find 42
 >> widget.destroy
 # Time passes....
->> widget = 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 it was destroyed
 >> widget.save                         # the widget lives!
 ```
 
@@ -363,7 +402,7 @@ You can find out whether a model instance is the current, live one -- or whether
 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:
 
 ```ruby
->> last_change = Widget.versions.last
+>> last_change = widget.versions.last
 >> user_who_made_the_change = User.find last_change.whodunnit.to_i
 ```
 
@@ -388,7 +427,7 @@ In a migration or in `rails console` you can 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 Version < ActiveRecord::Base
+class PaperTrail::Version < ActiveRecord::Base
   if defined?(Rails::Console)
     PaperTrail.whodunnit = "#{`whoami`.strip}: console"
   elsif File.basename($0) == "rake"
@@ -423,7 +462,7 @@ To find out who made a `version`'s object look that way, use `version.originator
 You can specify custom version subclasses with the `:class_name` option:
 
 ```ruby
-class PostVersion < Version
+class PostVersion < PaperTrail::Version
   # custom behaviour, e.g:
   self.table_name = :post_versions
 end
@@ -438,7 +477,7 @@ This allows you to store each model's versions in a separate table, which is use
 If you are using Postgres, you should also define the sequence that your custom version class will use:
 
 ```ruby
-class PostVersion < Version
+class PostVersion < PaperTrail::Version
   self.table_name = :post_versions
   self.sequence_name = :post_version_id_seq
 end
@@ -451,7 +490,7 @@ If you only use custom version classes and don't use PaperTrail's built-in one,
 - either declare PaperTrail's version class abstract like this (in `config/initializers/paper_trail_patch.rb`):
 
 ```ruby
-Version.module_eval do
+PaperTrail::Version.module_eval do
   self.abstract_class = true
 end
 ```
@@ -609,15 +648,17 @@ For example:
 
 ```ruby
 # config/initializers/paper_trail.rb
-class Version < ActiveRecord::Base
-  attr_accessible :author_id, :word_count, :answer
+module PaperTrail
+  class Version < ActiveRecord::Base
+    attr_accessible :author_id, :word_count, :answer
+  end
 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:
 
 ```ruby
-Version.all(:conditions => ['author_id = ?', author_id])
+PaperTrail::Version.all(:conditions => ['author_id = ?', author_id])
 ```
 
 Note you can pass a symbol as a value in the `meta` hash to signal a method to call.
@@ -793,48 +834,77 @@ sql> delete from versions where created_at < 2010-06-01;
 ```
 
 ```ruby
->> Version.delete_all ["created_at < ?", 1.week.ago]
+>> PaperTrail::Version.delete_all ["created_at < ?", 1.week.ago]
 ```
 
-## Installation
+## Testing
 
-### Rails 3
+You may want to turn PaperTrail off to speed up your tests.  See the [Turning PaperTrail Off/On](#turning-papertrail-offon) section above.
 
-1. Install PaperTrail as a gem via your `Gemfile`:
+### RSpec
 
-    `gem 'paper_trail', '~> 2'`
+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:
 
-2. Generate a migration which will add a `versions` table to your database.
+```ruby
+describe "RSpec test group" do
+  it 'by default, PaperTrail will be turned off' do
+    PaperTrail.should_not be_enabled
+  end
 
-    `bundle exec rails generate paper_trail:install`
+  with_versioning do
+    it 'within a `with_versioning` block it will be turned on' do
+      PaperTrail.should be_enabled
+    end
+  end
 
-3. Run the migration.
+  it 'can be turned on at the `it` or `describe` level like this', :versioning => true do
+    PaperTrail.should be_enabled
+  end
+end
+```
 
-    `bundle exec rake db:migrate`
+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.
 
-4. Add `has_paper_trail` to the models you want to track.
+There is also a `be_versioned` matcher provided by PaperTrail's RSpec helper which can be leveraged like so:
 
-### Rails 2
+```ruby
+class Widget < ActiveRecord::Base
+end
 
-Please see the `rails2` branch.
+describe Widget do
+  it { should_not be_versioned }
 
+  describe "add versioning to the `Widget` class" do
+    before(:all) do
+      class Widget < ActiveRecord::Base
+        has_paper_trail
+      end
+    end
 
-## Testing
+    it { should be_versioned }
+  end
+end
+```
 
-PaperTrail uses Bundler to manage its dependencies (in development and testing).  You can run the tests with `bundle exec rake test`.  (You may need to `bundle install` first.)
+### Cucumber
 
-It's a good idea to reset PaperTrail before each test so data from one test doesn't spill over another.  For example:
+PaperTrail provides a helper 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:
 
 ```ruby
-RSpec.configure do |config|
-  config.before :each do
-    PaperTrail.controller_info = {}
-    PaperTrail.whodunnit = nil
+Given /I want versioning on my model/ do
+  with_versioning do
+    # PaperTrail will be turned on for all code inside of this block
   end
 end
 ```
-You may want to turn PaperTrail off to speed up your tests.  See the "Turning PaperTrail Off/On" section above.
 
+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.
 
 ## Articles
 
@@ -894,6 +964,7 @@ Many thanks to:
 * [Tyler Rick](https://github.com/TylerRick)
 * [Bradley Priest](https://github.com/bradleypriest)
 * [David Butler](https://github.com/dwbutler)
+* [Paul Belt](https://github.com/belt)
 
 
 ## Inspirations

data/Rakefile

@@ -2,8 +2,7 @@ require 'bundler'
 Bundler::GemHelper.install_tasks
 
 require 'rake/testtask'
-
-desc 'Test the paper_trail plugin.'
+desc 'Run tests on PaperTrail with Test::Unit.'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'lib'
   t.libs << 'test'
@@ -11,5 +10,12 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = false
 end
 
+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 => :test
+task :default => :run_all_tests

data/gemfiles/3.0.gemfile

@@ -0,0 +1,31 @@
+source 'https://rubygems.org'
+
+gem 'activerecord', '~> 3.0'
+
+group :development, :test do
+  gem 'rake'
+  gem 'shoulda', '~> 3.5'
+  gem 'ffaker',  '>= 1.15'
+
+  # Testing of Rails
+  gem 'railties', '~> 3.0'
+
+  # Testing of Sinatra
+  gem 'sinatra', '~> 1.0'
+  gem 'rack-test', '>= 0.6'
+
+  # Use sqlite3 gem for regular Ruby
+  gem 'sqlite3', '~> 1.2', :platform => :ruby
+
+  # RSpec testing
+  gem 'rspec-rails', '~> 2.14'
+
+  platforms :jruby, :ruby_18 do
+    # shoulda-matchers > 2.0 is not compatible with Ruby18.
+    # Since we can't specify difference between JRuby 18/19, we need to use shoulda-matchers 1.5 for all JRuby testing.
+    gem 'shoulda-matchers', '~> 1.5'
+  end
+
+  # Use jRuby's sqlite3 adapter for jRuby
+  gem 'activerecord-jdbcsqlite3-adapter', '~> 1.2.9', :platform => :jruby
+end

data/lib/generators/paper_trail/install_generator.rb

@@ -1,11 +1,10 @@
 require 'rails/generators'
 require 'rails/generators/migration'
-require 'rails/generators/active_record/migration'
+require 'rails/generators/active_record'
 
 module PaperTrail
-  class InstallGenerator < Rails::Generators::Base
-    include Rails::Generators::Migration
-    extend ActiveRecord::Generators::Migration
+  class InstallGenerator < ::Rails::Generators::Base
+    include ::Rails::Generators::Migration
 
     source_root File.expand_path('../templates', __FILE__)
     class_option :with_changes, :type => :boolean, :default => false, :desc => "Store changeset (diff) with each version"
@@ -16,5 +15,9 @@ module PaperTrail
       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?
     end
+
+    def self.next_migration_number(dirname)
+      ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
   end
 end

data/lib/paper_trail.rb

@@ -1,13 +1,14 @@
 require 'paper_trail/config'
-require 'paper_trail/controller'
 require 'paper_trail/has_paper_trail'
-require 'paper_trail/version'
+require 'paper_trail/cleaner'
 
-require 'paper_trail/serializers/yaml'
-require 'paper_trail/serializers/json'
+# Require all frameworks and serializers
+Dir[File.join(File.dirname(__FILE__), 'paper_trail', 'frameworks', '*.rb')].each { |file| require file }
+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.
 module PaperTrail
+  extend PaperTrail::Cleaner
 
   # Switches PaperTrail on or off.
   def self.enabled=(value)
@@ -78,14 +79,16 @@ module PaperTrail
     PaperTrail.config.serializer
   end
 
+  def self.active_record_protected_attributes?
+    @active_record_protected_attributes ||= ActiveRecord::VERSION::STRING.to_f < 4.0 || defined?(ProtectedAttributes)
+  end
+
   private
 
   # Thread-safe hash to hold PaperTrail's data.
   # Initializing with needed default values.
   def self.paper_trail_store
-    Thread.current[:paper_trail] ||= {
-      :request_enabled_for_controller => true
-    }
+    Thread.current[:paper_trail] ||= { :request_enabled_for_controller => true }
   end
 
   # Returns PaperTrail's configuration object.
@@ -99,11 +102,14 @@ module PaperTrail
 
 end
 
+require 'paper_trail/version'
 
 ActiveSupport.on_load(:active_record) do
   include PaperTrail::Model
 end
 
-ActiveSupport.on_load(:action_controller) do
-  include PaperTrail::Controller
+if defined?(ActionController)
+  ActiveSupport.on_load(:action_controller) do
+    include PaperTrail::Rails::Controller
+  end
 end