paper_trail 1.5.2 → 1.5.3

data/README.md

@@ -25,7 +25,7 @@ PaperTrail lets you track changes to your models' data.  It's good for auditing
 
 ## Rails Version
 
-Reported to work on Rails 3 (though I haven't yet tried myself).  Known to work on Rails 2.3.  Probably works on Rails 2.2 and 2.1.
+Works on Rails 3 and Rails 2.3.  Probably works on Rails 2.2 and 2.1.
 
 
 ## Basic Usage
@@ -212,6 +212,48 @@ To find out who made a `version`'s object look that way, use `version.originator
     >> last_version.terminator                     # 'Bob'
 
 
+## Has-Many-Through Associations
+
+PaperTrail can track most changes to the join table.  Specifically it can track all additions but it can only track removals which fire the `after_destroy` callback on the join table.  Here are some examples:
+
+Given these models:
+
+    class Book < ActiveRecord::Base
+      has_many :authorships, :dependent => :destroy
+      has_many :authors, :through => :authorships, :source => :person
+      has_paper_trail
+    end
+    
+    class Authorship < ActiveRecord::Base
+      belongs_to :book
+      belongs_to :person
+      has_paper_trail      # NOTE
+    end
+    
+    class Person < ActiveRecord::Base
+      has_many :authorships, :dependent => :destroy
+      has_many :books, :through => :authorships
+      has_paper_trail
+    end
+
+Then each of the following will store authorship versions:
+
+    >> @book.authors << @dostoyevsky
+    >> @book.authors.create :name => 'Tolstoy'
+    >> @book.authorships.last.destroy
+    >> @book.authorships.clear
+
+But none of these will:
+
+    >> @book.authors.delete @tolstoy
+    >> @book.author_ids = [@solzhenistyn.id, @dostoyevsky.id]
+    >> @book.authors = []
+
+Having said that, you can probably (I haven't tested it myself) get the first one (`@book.authors.delete @tolstoy`) working with this [monkey patch](http://stackoverflow.com/questions/2381033/how-to-create-a-full-audit-log-in-rails-for-every-table/2381411#2381411).  Many thanks to Danny Trelogan for pointing it out.
+
+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.
+
+
 ## Storing metadata
 
 You can store arbitrary model-level metadata alongside each version like this:
@@ -315,9 +357,27 @@ Over time your `versions` table will grow to an unwieldy size.  Because each ver
 
 ## Installation
 
+### Rails 3
+
+1. Install PaperTrail as a gem via your `Gemfile`:
+
+    `gem 'paper_trail'`
+
+2. Generate a migration which will add a `versions` table to your database.
+
+    `rails generate paper_trail`
+
+3. Run the migration.
+
+    `rake db:migrate`
+
+4. Add `has_paper_trail` to the models you want to track.
+
+### Rails 2
+
 1. Install PaperTrail as a gem via your `config/environment.rb`:
 
-    `config.gem 'paper_trail'
+    `config.gem 'paper_trail'`
 
 2. Generate a migration which will add a `versions` table to your database.
 
@@ -353,6 +413,7 @@ Many thanks to:
 * [Jeremy Weiskotten](http://github.com/jeremyw)
 * [Phan Le](http://github.com/revo)
 * [jdrucza](http://github.com/jdrucza)
+* [conickal](http://github.com/conickal)
 
 
 ## Inspirations

data/VERSION

@@ -1 +1 @@
-1.5.2
+1.5.3

data/lib/generators/paper_trail/USAGE

@@ -0,0 +1,2 @@
+Description:
+  Generates (but does not run) a migration to add a versions table.

data/lib/generators/paper_trail/paper_trail_generator.rb

@@ -0,0 +1,24 @@
+require 'rails/generators/named_base'
+require 'rails/generators/migration'
+
+class PaperTrailGenerator < Rails::Generators::NamedBase
+  include Rails::Generators::Migration
+
+  desc "Generates (but does not run) a migration to add a versions table."
+  source_root File.expand_path('../templates', __FILE__)
+  argument :name, :type => :string, :default => "create_versions"
+
+  # Implement the required interface for Rails::Generators::Migration.
+  # taken from http://github.com/rails/rails/blob/master/activerecord/lib/generators/active_record.rb
+  def self.next_migration_number(dirname)
+    if ActiveRecord::Base.timestamped_migrations
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    else
+      "%.3d" % (current_migration_number(dirname) + 1)
+    end
+  end
+
+  def create_migration_file
+    migration_template 'create_versions.rb', 'db/migrate/create_versions.rb'
+  end
+end

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

@@ -0,0 +1,18 @@
+class CreateVersions < ActiveRecord::Migration
+  def self.up
+    create_table :versions do |t|
+      t.string   :item_type, :null => false
+      t.integer  :item_id,   :null => false
+      t.string   :event,     :null => false
+      t.string   :whodunnit
+      t.text     :object
+      t.datetime :created_at
+    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

@@ -51,8 +51,6 @@ module PaperTrail
   private
 
   # Thread-safe hash to hold PaperTrail's data.
-  #
-  # TODO: is this a memory leak?
   def self.paper_trail_store
     Thread.current[:paper_trail] ||= {}
   end

data/paper_trail.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{paper_trail}
-  s.version = "1.5.2"
+  s.version = "1.5.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andy Stewart"]
-  s.date = %q{2010-06-28}
+  s.date = %q{2010-10-11}
   s.email = %q{boss@airbladesoftware.com}
   s.extra_rdoc_files = [
     "README.md"
@@ -25,6 +25,9 @@ Gem::Specification.new do |s|
      "generators/paper_trail/templates/create_versions.rb",
      "init.rb",
      "install.rb",
+     "lib/generators/paper_trail/USAGE",
+     "lib/generators/paper_trail/paper_trail_generator.rb",
+     "lib/generators/paper_trail/templates/create_versions.rb",
      "lib/paper_trail.rb",
      "lib/paper_trail/config.rb",
      "lib/paper_trail/controller.rb",

data/test/paper_trail_model_test.rb

@@ -24,6 +24,24 @@ class Article < ActiveRecord::Base
                               :article_id => Proc.new { |article| article.id } }
 end
 
+class Book < ActiveRecord::Base
+  has_many :authorships, :dependent => :destroy
+  has_many :authors, :through => :authorships, :source => :person
+  has_paper_trail
+end
+
+class Authorship < ActiveRecord::Base
+  belongs_to :book
+  belongs_to :person
+  has_paper_trail
+end
+
+class Person < ActiveRecord::Base
+  has_many :authorships, :dependent => :destroy
+  has_many :books, :through => :authorships
+  has_paper_trail
+end
+
 
 class HasPaperTrailModelTest < Test::Unit::TestCase
   load_schema
@@ -586,5 +604,44 @@ class HasPaperTrailModelTest < Test::Unit::TestCase
     end
   end
 
+  context ":has_many :through" do
+    setup do
+      @book = Book.create :title => 'War and Peace'
+      @dostoyevsky  = Person.create :name => 'Dostoyevsky'
+      @solzhenitsyn = Person.create :name => 'Solzhenitsyn'
+    end
+
+    should 'store version on source <<' do
+      count = Version.count
+      @book.authors << @dostoyevsky
+      assert_equal 1, Version.count - count
+      assert_equal Version.last, @book.authorships.first.versions.first
+    end
+
+    should 'store version on source create' do
+      count = Version.count
+      @book.authors.create :name => 'Tolstoy'
+      assert_equal 2, Version.count - count
+      assert_same_elements [Person.last, Authorship.last], [Version.all[-2].item, Version.last.item]
+    end
+
+    should 'store version on join destroy' do
+      @book.authors << @dostoyevsky
+      count = Version.count
+      @book.authorships(true).last.destroy
+      assert_equal 1, Version.count - count
+      assert_equal @book, Version.last.reify.book
+      assert_equal @dostoyevsky, Version.last.reify.person
+    end
+
+    should 'store version on join clear' do
+      @book.authors << @dostoyevsky
+      count = Version.count
+      @book.authorships(true).clear
+      assert_equal 1, Version.count - count
+      assert_equal @book, Version.last.reify.book
+      assert_equal @dostoyevsky, Version.last.reify.person
+    end
+  end
 
 end

data/test/schema.rb

@@ -49,4 +49,17 @@ ActiveRecord::Schema.define(:version => 0) do
     t.string :content
   end
 
+  create_table :books, :force => true do |t|
+    t.string :title
+  end
+
+  create_table :authorships, :force => true do |t|
+    t.integer :book_id
+    t.integer :person_id
+  end
+
+  create_table :people, :force => true do |t|
+    t.string :name
+  end
+
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: paper_trail
 version: !ruby/object:Gem::Version 
-  hash: 7
+  hash: 5
   prerelease: false
   segments: 
   - 1
   - 5
-  - 2
-  version: 1.5.2
+  - 3
+  version: 1.5.3
 platform: ruby
 authors: 
 - Andy Stewart
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-28 00:00:00 +01:00
+date: 2010-10-11 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -38,6 +38,9 @@ files:
 - generators/paper_trail/templates/create_versions.rb
 - init.rb
 - install.rb
+- lib/generators/paper_trail/USAGE
+- lib/generators/paper_trail/paper_trail_generator.rb
+- lib/generators/paper_trail/templates/create_versions.rb
 - lib/paper_trail.rb
 - lib/paper_trail/config.rb
 - lib/paper_trail/controller.rb