paper_trail 1.4.0 → 17.0.0

data/README.md

@@ -1,225 +0,0 @@
-# PaperTrail
-
-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.
-
-
-## Features
-
-* Stores every create, update and destroy.
-* Does not store updates which don't change anything.
-* Does not store updates which only change attributes you are ignoring.
-* Allows you to get at every version, including the original, even once destroyed.
-* Allows you to get at every version even if the schema has since changed.
-* Automatically records who was responsible if your controller has a `current_user` method.
-* Allows you to set who is responsible at model-level (useful for migrations).
-* Allows you to store arbitrary metadata with each version (useful for filtering versions).
-* Can be turned off/on (useful for migrations).
-* No configuration necessary.
-* Stores everything in a single database table (generates migration for you).
-* Thoroughly tested.
-
-
-## Rails Version
-
-Known to work on Rails 2.3.  Probably works on Rails 2.2 and 2.1.
-
-
-## Basic Usage
-
-PaperTrail is simple to use.  Just add 15 characters to a model to get a paper trail of every `create`, `update`, and `destroy`.
-
-    class Widget < ActiveRecord::Base
-      has_paper_trail
-    end
-
-This gives you a `versions` method which returns the paper trail of changes to your model.
-
-    >> widget = Widget.find 42
-    >> widget.versions             # [<Version>, <Version>, ...]
-
-Once you have a version, you can find out what happened:
-
-    >> v = widget.versions.last
-    >> v.event                     # 'update' (or 'create' or 'destroy')
-    >> v.whodunnit                 # '153'  (if the update was via a controller and
-                                   #         the controller has a current_user method,
-                                   #         here returning the id of the current user)
-    >> v.created_at                # when the update occurred
-    >> widget = v.reify            # the widget as it was before the update;
-                                   # would be nil for a create event
-
-PaperTrail stores the pre-change version of the model, unlike some other auditing/versioning plugins, so you can retrieve the original version.  This is useful when you start keeping a paper trail for models that already have records in the database.
-
-    >> widget = Widget.find 153
-    >> widget.name                                 # 'Doobly'
-
-    # Add has_paper_trail to Widget model.
-
-    >> widget.versions                             # []
-    >> widget.update_attributes :name => 'Wotsit'
-    >> widget.versions.first.reify.name            # 'Doobly'
-    >> widget.versions.first.event                 # 'update'
-
-This also means that PaperTrail does not waste space storing a version of the object as it currently stands.  The `versions` method gives you previous versions; to get the current one just call a finder on your `Widget` model as usual.
-
-Here's a helpful table showing what PaperTrail stores:
-
-<table>
-  <tr>
-    <th>Event</th>
-    <th>Model Before</th>
-    <th>Model After</th>
-  </tr>
-  <tr>
-    <td>create</td>
-    <td>nil</td>
-    <td>widget</td>
-  </tr>
-  <tr>
-    <td>update</td>
-    <td>widget</td>
-    <td>widget'</td>
-  <tr>
-    <td>destroy</td>
-    <td>widget</td>
-    <td>nil</td>
-  </tr>
-</table>
-
-PaperTrail stores the values in the Model Before column.  Most other auditing/versioning plugins store the After column.
-
-
-## Ignoring changes to certain attributes
-
-You can ignore changes to certain attributes like this:
-
-    class Article < ActiveRecord::Base
-      has_paper_trail :ignore => [:title, :rating]
-    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 crated.  For example:
-
-    >> a = Article.create
-    >> a.versions.length                         # 1
-    >> a.update_attributes :title => 'My Title', :rating => 3
-    >> a.versions.length                         # 1
-    >> a.update_attributes :content => 'Hello'
-    >> a.versions.length                         # 2
-    >> a.versions.last.reify.title               # 'My Title'
-
-
-## Reverting And Undeleting A Model
-
-PaperTrail makes reverting to a previous version easy:
-
-    >> widget = Widget.find 42
-    >> widget.update_attributes :name => 'Blah blah'
-    # Time passes....
-    >> widget = widget.versions.last.reify  # the widget as it was before the update
-    >> widget.save                          # reverted
-
-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.save                         # the widget lives!
-
-In fact you could use PaperTrail to implement an undo system, though I haven't had the opportunity yet to do it myself.
-
-
-## Finding Out Who Was Responsible For A Change
-
-If your `ApplicationController` has a `current_user` method, PaperTrail will store the value it returns in the `version`'s `whodunnit` column.  Note that this column is a string so you will have to convert it to an integer if it's an id and you want to look up the user later on:
-
-    >> last_change = Widget.versions.last
-    >> user_who_made_the_change = User.find last_change.whodunnit.to_i
-
-In a migration or in `script/console` you can set who is responsible like this:
-
-    >> PaperTrail.whodunnit = 'Andy Stewart'
-    >> widget.update_attributes :name => 'Wibble'
-    >> widget.versions.last.whodunnit              # Andy Stewart
-
-
-## Storing metadata
-
-You can store arbitrary metadata alongside each version like this:
-
-    class Article < ActiveRecord::Base
-      belongs_to :author
-      has_paper_trail :meta => { :author_id => Proc.new { |article| article.author_id },
-                                 :answer    => 42 }
-    end
-
-PaperTrail will call your proc with the current article and store the result in the `author_id` column of the `versions` table.  (Remember to add your metadata columns to the table.)
-
-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:
-
-    Version.all(:conditions => ['author_id = ?', author_id])
-
-
-## Turning PaperTrail Off/On
-
-Sometimes you don't want to store changes.  Perhaps you are only interested in changes made
-by your users and don't need to store changes you make yourself in, say, a migration.
-
-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:
-
-    >> Widget.paper_trail_off
-
-And on again like this:
-
-    >> Widget.paper_trail_on
-
-
-## Installation
-
-1. Install PaperTrail either as a gem (from Gemcutter; the ones on GitHub are obsolete) or as a plugin:
-
-    `config.gem 'paper_trail', :source => 'http://gemcutter.org'`
-
-    or:
-
-    `script/plugin install git://github.com/airblade/paper_trail.git`
-
-2. Generate a migration which will add a `versions` table to your database.
-
-    `script/generate paper_trail`
-
-3. Run the migration.
-
-    `rake db:migrate`
-
-4. Add `has_paper_trail` to the models you want to track.
-
-
-## Testing
-
-PaperTrail has a thorough suite of tests.  Thanks to [Zachery Hostens](http://github.com/zacheryph) for making them able to run standalone, i.e. without needing PaperTrail to be sitting in a Rails app.
-
-
-## Problems
-
-Please use GitHub's [issue tracker](http://github.com/airblade/paper_trail/issues).
-
-
-## Contributors
-
-Many thanks to:
-
-* [Zachery Hostens](http://github.com/zacheryph)
-
-
-## Inspirations
-
-* [Simply Versioned](http://github.com/github/simply_versioned)
-* [Acts As Audited](http://github.com/collectiveidea/acts_as_audited)
-
-
-## Intellectual Property
-
-Copyright (c) 2009 Andy Stewart (boss@airbladesoftware.com).
-Released under the MIT licence.

data/Rakefile

@@ -1,50 +0,0 @@
-require 'rake'
-require 'rake/testtask'
-require 'rake/rdoctask'
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.name = 'paper_trail'
-    gemspec.summary = "Track changes to your models' data.  Good for auditing or versioning."
-    gemspec.email = 'boss@airbladesoftware.com'
-    gemspec.homepage = 'http://github.com/airblade/paper_trail'
-    gemspec.authors = ['Andy Stewart']
-  end
-  Jeweler::GemcutterTasks.new
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
-end
-
-desc 'Test the paper_trail plugin.'
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = true
-end
-
-begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new do |test|
-    test.libs << 'test'
-    test.pattern = 'test/**/*_test.rb'
-    test.verbose = true
-  end
-rescue LoadError
-  task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
-  end
-end
-
-desc 'Generate documentation for the paper_trail plugin.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'PaperTrail'
-  rdoc.options << '--line-numbers' << '--inline-source'
-  rdoc.rdoc_files.include('README')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
-
-desc 'Default: run unit tests.'
-task :default => :test

data/VERSION

@@ -1 +0,0 @@
-1.4.0

data/generators/paper_trail/USAGE

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

data/generators/paper_trail/paper_trail_generator.rb

@@ -1,9 +0,0 @@
-class PaperTrailGenerator < Rails::Generator::Base
-
-  def manifest
-    record do |m|
-      m.migration_template 'create_versions.rb', 'db/migrate', :migration_file_name => 'create_versions'
-    end
-  end
-
-end

data/generators/paper_trail/templates/create_versions.rb

@@ -1,18 +0,0 @@
-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/init.rb

@@ -1 +0,0 @@
-# Include hook code here

data/install.rb

@@ -1 +0,0 @@
-# Install hook code here

data/lib/paper_trail/version.rb

@@ -1,59 +0,0 @@
-class Version < ActiveRecord::Base
-  belongs_to :item, :polymorphic => true
-  validates_presence_of :event
-
-  def reify
-    unless object.nil?
-      # Attributes
-
-      attrs = YAML::load object
-
-      # Normally a polymorphic belongs_to relationship allows us
-      # to get the object we belong to by calling, in this case,
-      # +item+.  However this returns nil if +item+ has been
-      # destroyed, and we need to be able to retrieve destroyed
-      # objects.
-      #
-      # In this situation we constantize the +item_type+ to get hold of
-      # the class...except when the stored object's attributes
-      # include a +type+ key.  If this is the case, the object
-      # we belong to is using single table inheritance and the
-      # +item_type+ will be the base class, not the actual subclass.
-      # If +type+ is present but empty, the class is the base class.
-
-      if item
-        model = item
-      else
-        class_name = attrs['type'].blank? ? item_type : attrs['type']
-        klass = class_name.constantize
-        model = klass.new
-      end
-
-      attrs.each do |k, v|
-        begin
-          model.send "#{k}=", v
-        rescue NoMethodError
-          logger.warn "Attribute #{k} does not exist on #{item_type} (Version id: #{id})."
-        end
-      end
-
-      model
-    end
-  end
-
-  def next
-    Version.first :conditions => ["id > ? AND item_type = ? AND item_id = ?", id, item_type, item_id],
-                  :order => 'id ASC'
-  end
-
-  def previous
-    Version.first :conditions => ["id < ? AND item_type = ? AND item_id = ?", id, item_type, item_id],
-                  :order => 'id DESC'
-  end
-
-  def index
-    Version.all(:conditions => ["item_type = ? AND item_id = ?", item_type, item_id],
-                :order => 'id ASC').index(self)
-  end
-  
-end

data/paper_trail.gemspec

@@ -1,67 +0,0 @@
-# Generated by jeweler
-# DO NOT EDIT THIS FILE DIRECTLY
-# Instead, edit Jeweler::Tasks in rakefile, and run the gemspec command
-# -*- encoding: utf-8 -*-
-
-Gem::Specification.new do |s|
-  s.name = %q{paper_trail}
-  s.version = "1.4.0"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["Andy Stewart"]
-  s.date = %q{2010-01-06}
-  s.email = %q{boss@airbladesoftware.com}
-  s.extra_rdoc_files = [
-    "README.md"
-  ]
-  s.files = [
-    ".gitignore",
-     "MIT-LICENSE",
-     "README.md",
-     "Rakefile",
-     "VERSION",
-     "generators/paper_trail/USAGE",
-     "generators/paper_trail/paper_trail_generator.rb",
-     "generators/paper_trail/templates/create_versions.rb",
-     "init.rb",
-     "install.rb",
-     "lib/paper_trail.rb",
-     "lib/paper_trail/has_paper_trail.rb",
-     "lib/paper_trail/version.rb",
-     "paper_trail.gemspec",
-     "rails/init.rb",
-     "tasks/paper_trail_tasks.rake",
-     "test/database.yml",
-     "test/paper_trail_controller_test.rb",
-     "test/paper_trail_model_test.rb",
-     "test/paper_trail_schema_test.rb",
-     "test/schema.rb",
-     "test/schema_change.rb",
-     "test/test_helper.rb",
-     "uninstall.rb"
-  ]
-  s.homepage = %q{http://github.com/airblade/paper_trail}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.5}
-  s.summary = %q{Track changes to your models' data.  Good for auditing or versioning.}
-  s.test_files = [
-    "test/paper_trail_controller_test.rb",
-     "test/paper_trail_model_test.rb",
-     "test/paper_trail_schema_test.rb",
-     "test/schema.rb",
-     "test/schema_change.rb",
-     "test/test_helper.rb"
-  ]
-
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-    else
-    end
-  else
-  end
-end
-

data/rails/init.rb

@@ -1 +0,0 @@
-require 'paper_trail'

data/test/database.yml

@@ -1,18 +0,0 @@
-sqlite3:
-  adapter: sqlite3
-  database: ":memory:"
-
-postgresql:
-  adapter: postgresql
-  username: postgres
-  password: postgres
-  database: paper_trail_plugin_test
-  min_messages: ERROR
-
-mysql:
-  adapter: mysql
-  host: localhost
-  username: andy
-  password: 
-  database: paper_trail_plugin_test
-  socket: /tmp/mysql.sock

data/test/paper_trail_controller_test.rb

@@ -1,70 +0,0 @@
-require File.dirname(__FILE__) + '/test_helper.rb'
-
-class ApplicationController < ActionController::Base
-  def rescue_action(e)
-    raise e
-  end
-
-  # Returns id of hypothetical current user
-  def current_user
-    153
-  end
-end
-
-class WidgetsController < ApplicationController
-  def create
-    @widget = Widget.create params[:widget]
-    head :ok
-  end
-
-  def update
-    @widget = Widget.find params[:id]
-    @widget.update_attributes params[:widget]
-    head :ok
-  end
-
-  def destroy
-    @widget = Widget.find params[:id]
-    @widget.destroy
-    head :ok
-  end
-end
-
-
-class PaperTrailControllerTest < ActionController::TestCase #Test::Unit::TestCase
-  def setup
-    @controller = WidgetsController.new
-    @request = ActionController::TestRequest.new
-    @response = ActionController::TestResponse.new
-
-    ActionController::Routing::Routes.draw do |map|
-      map.resources :widgets
-    end
-  end
-
-  test 'create' do
-    post :create, :widget => { :name => 'Flugel' }
-    widget = assigns(:widget)
-    assert_equal 1, widget.versions.length
-    assert_equal 153, widget.versions.last.whodunnit.to_i
-  end
-
-  test 'update' do
-    w = Widget.create :name => 'Duvel'
-    assert_equal 1, w.versions.length
-    put :update, :id => w.id, :widget => { :name => 'Bugle' }
-    widget = assigns(:widget)
-    assert_equal 2, widget.versions.length
-    assert_equal 153, widget.versions.last.whodunnit.to_i
-  end
-
-  test 'destroy' do
-    w = Widget.create :name => 'Roundel'
-    assert_equal 1, w.versions.length
-    delete :destroy, :id => w.id
-    widget = assigns(:widget)
-    assert_equal 2, widget.versions.length
-    assert_equal 153, widget.versions.last.whodunnit.to_i
-  end
-end
-