vestal_versions 0.8.3 → 1.0.0

data/.gitignore

@@ -1,4 +1,22 @@
+## MAC OS
 .DS_Store
-pkg
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
 rdoc
-test/*.db
+pkg
+
+## PROJECT::SPECIFIC
+*.db

data/README.rdoc

@@ -4,9 +4,7 @@ Finally, DRY ActiveRecord versioning!
 
 <tt>acts_as_versioned</tt>[http://github.com/technoweenie/acts_as_versioned] by technoweenie[http://github.com/technoweenie] was a great start, but it failed to keep up with ActiveRecord's introduction of dirty objects in version 2.1. Additionally, each versioned model needs its own versions table that duplicates most of the original table's columns. The versions table is then populated with records that often duplicate most of the original record's attributes. All in all, not very DRY.
 
-<tt>simply_versioned</tt>[http://github.com/mmower/simply_versioned] by mmower[http://github.com/mmower] started to move in the right direction by removing a great deal of the duplication of acts_as_versioned. It requires only one versions table and no changes whatsoever to existing models. Its versions table stores all of the model attributes as a YAML hash in a single text column. But we could be DRYer!
-
-<tt>vestal_versions</tt>[http://github.com/laserlemon/vestal_versions] keeps in the spirit of consolidating to one versions table, polymorphically associated with its parent models. But it goes one step further by storing a serialized hash of _only_ the models' changes. Think modern version control systems. By traversing the record of changes, the models can be reverted to any point in time.
+<tt>vestal_versions</tt>[http://github.com/laserlemon/vestal_versions] requires only one versions table (polymorphically associated with its parent models) and no changes whatsoever to existing tables. But it goes one step DRYer by storing a serialized hash of _only_ the models' changes. Think modern version control systems. By traversing the record of changes, the models can be reverted to any point in time.
 
 And that's just what <tt>vestal_versions</tt> does. Not only can a model be reverted to a previous version number but also to a date or time!
 
@@ -15,7 +13,9 @@ And that's just what <tt>vestal_versions</tt> does. Not only can a model be reve
 In <tt>environment.rb</tt>:
 
   Rails::Initializer.run do |config|
+    ...
     config.gem 'vestal_versions'
+    ...
   end
 
 At your application root, run:
@@ -24,7 +24,7 @@ At your application root, run:
 
 Next, generate and run the first and last versioning migration you'll ever need:
 
-  $ script/generate vestal_versions_migration
+  $ script/generate vestal_versions
   $ rake db:migrate
 
 == Example
@@ -43,17 +43,17 @@ To version an ActiveRecord model, simply add <tt>versioned</tt> to your class li
 
 It's that easy! Now watch it in action...
 
-  >> u = User.create(:first_name => 'Steve', :last_name => 'Richert')
+  >> u = User.create(:first_name => "Steve", :last_name => "Richert")
   => #<User first_name: "Steve", last_name: "Richert">
   >> u.version
   => 1
-  >> u.update_attribute(:first_name, 'Stephen')
+  >> u.update_attribute(:first_name, "Stephen")
   => true
   >> u.name
   => "Stephen Richert"
   >> u.version
   => 2
-  >> u.revert_to(:first)
+  >> u.revert_to(10.seconds.ago)
   => 1
   >> u.name
   => "Steve Richert"
@@ -63,7 +63,7 @@ It's that easy! Now watch it in action...
   => true
   >> u.version
   => 3
-  >> u.update_attribute(:last_name, 'Jobs')
+  >> u.update_attribute(:last_name, "Jobs")
   => true
   >> u.name
   => "Steve Jobs"
@@ -75,3 +75,105 @@ It's that easy! Now watch it in action...
   => "Stephen Richert"
   >> u.version
   => 5
+
+== Upgrading to 1.0
+
+For the most part, version 1.0 of <tt>vestal_versions</tt> is backwards compatible, with just a few notable changes:
+
+* The versions table has been beefed up. You'll need to add the following columns (and indexes, if you feel so inclined):
+  
+    change_table :versions do |t|
+      t.belongs_to :user, :polymorphic => true
+      t.string :user_name
+      t.string :tag
+    end
+    
+    change_table :versions do |t|
+      t.index [:user_id, :user_type]
+      t.index :user_name
+      t.index :tag
+    end
+  
+* When a model is created (or updated the first time after being versioned), an initial version record with a number of 1 is no longer created. These aren't used during reversion and so they end up just being dead weight. Feel free to scrap all your versions where <tt>number == 1</tt> after the upgrade if you'd like to free up some room in your database (but you don't have to).
+  
+* Models that have no version records in the database will return a <tt>@user.version</tt> of 1. In the past, this would have returned <tt>nil</tt> instead.
+  
+* <tt>Version</tt> has moved to <tt>VestalVersions::Version</tt> to make way for custom version classes.
+  
+* <tt>Version#version</tt> did not survive the move to <tt>VestalVersions::Version#version</tt>. That alias was dropped (too confusing). Use <tt>VestalVersions::Version#number</tt>.
+
+== New to 1.0
+
+There are a handful of exciting new additions in version 1.0 of <tt>vestal_versions</tt>. A lot has changed in the code: much better documentation, more modular organization of features, and a more exhaustive test suite. But there are also a number of new features that are available in this release of <tt>vestal_versions</tt>:
+
+* The ability to completely skip versioning within a new <tt>skip_version</tt> block:
+  
+    @user.version # => 1
+    @user.skip_version do
+      @user.update_attribute(:first_name, "Stephen")
+      @user.first_name = "Steve"
+      @user.save
+      @user.update_attributes(:last_name => "Jobs")
+    end
+    @user.version # => 1
+  
+  Also available, are <tt>merge_version</tt> and <tt>append_version</tt> blocks. The <tt>merge_version</tt> block will compile the possibly multiple versions that would result from the updates inside the block into one summary version. The single resulting version is then tacked onto the version history as usual. The <tt>append_version</tt> block works similarly except that the resulting single version is combined with the most recent version in the history and saved.
+  
+* Version tagging. Any version can have a tag attached to it (must be unique within the scope of the versioned parent) and that tag can be used for reversion.
+  
+    @user.name # => "Steve Richert"
+    @user.update_attribute(:last_name, "Jobs")
+    @user.name # => "Steve Jobs"
+    @user.tag_version("apple")
+    @user.update_attribute(:last_name, "Richert")
+    @user.name # => "Steve Richert"
+    @user.revert_to("apple")
+    @user.name # => "Steve Jobs"
+  
+  So if you're not big on version numbers, you could just tag your versions and avoid the numbers altogether.
+  
+* Resetting. This is basically a hard revert. The new <tt>reset_to!</tt> instance method behaves just like the <tt>revert_to!</tt> method except that after the reversion, it will also scrap all the versions that came after that target version.
+  
+    @user.name # => "Steve Richert"
+    @user.version # => 1
+    @user.versions.count # => 0
+    @user.update_attribute(:last_name, "Jobs")
+    @user.name # => "Steve Jobs"
+    @user.version # => 2
+    @user.versions.count # => 1
+    @user.reset_to!(1)
+    @user.name # => "Steve Richert"
+    @user.version # => 1
+    @user.versions.count # => 0
+  
+* Storing which user is responsible for a revision. Rather than introduce a lot of controller magic to guess what to store, you can simply update an additional attribute on your versioned model: <tt>updated_by</tt>.
+  
+    @user.update_attributes(:last_name => "Jobs", :updated_by => "Tyler")
+    @user.versions.last.user # => "Tyler"
+  
+  Instead of passing a simple string to the <tt>updated_by</tt> setter, you can pass a model instance, such as an ActiveRecord user or administrator. The association will be saved polymorphically alongside the version.
+  
+    @user.update_attributes(:last_name => "Jobs", :updated_by => current_user)
+    @user.versions.last.user # => #<User first_name: "Steven", last_name: "Tyler">
+  
+* Global configuration. The new <tt>vestal_versions</tt> Rails generator also writes an initializer with instructions on how to set application-wide options for the <tt>versioned</tt> method.
+  
+* Conditional version creation. The <tt>versioned</tt> method now accepts <tt>:if</tt> and <tt>:unless</tt> options. Each expects a symbol representing an instance method or a proc that will be evaluated to determine whether or not to create a new version after an update. An array containing any combination of symbols and procs can also be given.
+  
+    class User < ActiveRecord::Base
+      versioned :if => :really_create_a_version?
+    end
+  
+* Custom version classes. By passing a <tt>:class_name</tt> option to the <tt>versioned</tt> method, you can specify your own ActiveRecord version model. <tt>VestalVersions::Version</tt> is the default, but feel free to stray from that. I recommend that your custom model inherit from <tt>VestalVersions::Version</tt>, but that's up to you!
+  
+* A <tt>versioned?</tt> convenience class method. If your user model is versioned, <tt>User.versioned?</tt> will let you know.
+  
+== Thanks!
+
+Thank you to all those who post {issues and suggestions}[http://github.com/laserlemon/vestal_versions/issues]. And special thanks to:
+
+* splattael[http://github.com/splattael], who first bugged (and helped) me to write some tests for this thing
+* snaury[http://github.com/snaury], who helped out early on with the <tt>between</tt> association method, the <tt>:dependent</tt> option and a conflict from using a method called <tt>changes</tt>
+* sthapit[http://github.com/sthapit], who was responsible for the <tt>:only</tt> and <tt>:except</tt> options as well as showing me that I'm a dummy for storing a useless first version
+
+To contribute to <tt>vestal_versions</tt>, please fork, hack away in the integration[http://github.com/laserlemon/vestal_versions/tree/integration] branch and send me a pull request. Remember your tests!

data/Rakefile

@@ -1,6 +1,7 @@
 require 'rubygems'
 require 'rake'
 require 'rake/testtask'
+require 'rcov/rcovtask'
 require 'rake/rdoctask'
 
 begin
@@ -12,15 +13,18 @@ begin
     g.email = 'steve@laserlemon.com'
     g.homepage = 'http://github.com/laserlemon/vestal_versions'
     g.authors = %w(laserlemon)
-    g.add_development_dependency 'thoughtbot-shoulda'
+    g.add_development_dependency 'activerecord'
+    g.add_development_dependency 'activesupport'
+    g.add_development_dependency 'shoulda'
+    g.add_development_dependency 'mocha'
     g.rubyforge_project = 'laser-lemon'
   end
+  Jeweler::GemcutterTasks.new
   Jeweler::RubyforgeTasks.new do |r|
     r.doc_task = 'rdoc'
   end
-  Jeweler::GemcutterTasks.new
 rescue LoadError
-  puts 'Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com'
+  puts 'Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler'
 end
 
 Rake::TestTask.new do |t|
@@ -28,12 +32,19 @@ Rake::TestTask.new do |t|
   t.pattern = 'test/**/*_test.rb'
 end
 
+Rcov::RcovTask.new do |t|
+  t.libs = %w(test)
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task :test => :check_dependencies
 task :default => :test
 
 Rake::RDocTask.new do |r|
   version = File.exist?('VERSION') ? File.read('VERSION') : nil
   r.rdoc_dir = 'rdoc'
   r.title = ['vestal_versions', version].compact.join(' ')
+  r.options << '--line-numbers' << '--inline-source'
   r.rdoc_files.include('README*')
   r.rdoc_files.include('lib/**/*.rb')
 end

data/VERSION

@@ -1 +1 @@
-0.8.3
+1.0.0

data/lib/vestal_versions.rb

@@ -1,149 +1,99 @@
-require 'version'
-
-module LaserLemon
-  module VestalVersions
-    def self.included(base)
-      base.extend ClassMethods
-    end
-
-    module ClassMethods
-      def versioned(options = {})
-        class_inheritable_accessor :version_only_columns
-        self.version_only_columns = Array(options[:only]).map(&:to_s).uniq if options[:only]
-        class_inheritable_accessor :version_except_columns
-        self.version_except_columns = Array(options[:except]).map(&:to_s).uniq if options[:except]
-
-        has_many :versions, :as => :versioned, :order => 'versions.number ASC', :dependent => :delete_all do
-          def between(from, to)
-            from_number, to_number = number_at(from), number_at(to)
-            return [] if from_number.nil? || to_number.nil?
-            condition = (from_number == to_number) ? to_number : Range.new(*[from_number, to_number].sort)
-            all(
-              :conditions => {:number => condition},
-              :order => "versions.number #{(from_number > to_number) ? 'DESC' : 'ASC'}"
-            )
-          end
-
-          def at(value)
-            case value
-              when Version then value
-              when Numeric then find_by_number(value.floor)
-              when Symbol then respond_to?(value) ? send(value) : nil
-              when Date, Time then last(:conditions => ['versions.created_at <= ?', value.to_time])
-            end
-          end
-
-          def number_at(value)
-            case value
-              when Version then value.number
-              when Numeric then value.floor
-              when Symbol, Date, Time then at(value).try(:number)
-            end
-          end
-        end
-
-        after_create :create_initial_version
-        after_update :create_initial_version, :if => :needs_initial_version?
-        after_update :create_version, :if => :needs_version?
-
-        include InstanceMethods
-        alias_method_chain :reload, :versions
-      end
+# +vestal_versions+ keeps track of updates to ActiveRecord models, leveraging the introduction of
+# dirty attributes in Rails 2.1. By storing only the updated attributes in a serialized column of a
+# single version model, the history is kept DRY and no additional schema changes are necessary.
+#
+# Author:: Steve Richert
+# Copyright:: Copyright (c) 2009 Steve Richert
+# License:: MIT License (http://www.opensource.org/licenses/mit-license.php)
+#
+# To enable versioning on a model, simply use the +versioned+ method:
+#
+#   class User < ActiveRecord::Base
+#     versioned
+#   end
+#
+#   user = User.create(:name => "Steve Richert")
+#   user.version # => 1
+#   user.update_attribute(:name, "Steve Jobs")
+#   user.version # => 2
+#   user.revert_to(1)
+#   user.name # => "Steve Richert"
+#
+# See the +versioned+ documentation for more details.
+
+Dir[File.join(File.dirname(__FILE__), 'vestal_versions', '*.rb')].each{|f| require f }
+
+# The base module that gets included in ActiveRecord::Base. See the documentation for
+# VestalVersions::ClassMethods for more useful information.
+module VestalVersions
+  def self.included(base) # :nodoc:
+    base.class_eval do
+      extend ClassMethods
+      extend Versioned
     end
+  end
 
-    module InstanceMethods
-      private
-        def versioned_columns
-          case
-            when version_only_columns then self.class.column_names & version_only_columns
-            when version_except_columns then self.class.column_names - version_except_columns
-            else self.class.column_names
-          end - %w(created_at created_on updated_at updated_on)
-        end
-
-        def needs_initial_version?
-          versions.empty?
-        end
-
-        def needs_version?
-          !(versioned_columns & changed).empty?
-        end
-
-        def reset_version(new_version = nil)
-          @last_version = nil if new_version.nil?
-          @version = new_version
-        end
-
-        def create_initial_version
-          versions.create(:changes => nil, :number => 1)
-        end
-
-        def create_version
-          versions.create(:changes => changes.slice(*versioned_columns), :number => (last_version + 1))
-          reset_version
-        end
-
-      public
-        def version
-          @version ||= last_version
-        end
-
-        def last_version
-          @last_version ||= versions.maximum(:number)
-        end
-
-        def reverted?
-          version != last_version
-        end
-
-        def reload_with_versions(*args)
-          reset_version
-          reload_without_versions(*args)
-        end
-
-        def changes_between(from, to)
-          from_number, to_number = versions.number_at(from), versions.number_at(to)
-          return {} if from_number == to_number
-          chain = versions.between(from_number, to_number)
-          return {} if chain.empty?
-
-          backward = chain.first > chain.last
-          backward ? chain.pop : chain.shift
-
-          chain.inject({}) do |changes, version|
-            version.changes.each do |attribute, change|
-              change.reverse! if backward
-              new_change = [changes.fetch(attribute, change).first, change.last]
-              changes.update(attribute => new_change)
-            end
-            changes
-          end
-        end
-
-        def revert_to(value)
-          to_number = versions.number_at(value)
-          changes = changes_between(version, to_number)
-          return version if changes.empty?
-
-          changes.each do |attribute, change|
-            write_attribute(attribute, change.last)
-          end
-
-          reset_version(to_number)
-        end
-
-        def revert_to!(value)
-          revert_to(value)
-          reset_version if saved = save
-          saved
-        end
-
-        def latest_changes
-          return {} if version.nil? || version == 1
-          versions.at(version).changes
-        end
+  module ClassMethods
+    # +versioned+ associates an ActiveRecord model with many versions. When the object is updated,
+    # a new version containing the changes is created. There are several options available to the
+    # +versioned+ method, most of which are passed to the +has_many+ association itself:
+    # * <tt>:class_name</tt>: The class name of the version model to use for the association. By
+    #   default, this is set to "VestalVersions::Version", representing the built-in version class.
+    #   By specifying this option, you can override the version class, to include custom version
+    #   behavior. It's recommended that a custom version inherit from VestalVersions::Version.
+    # * <tt>:dependent</tt>: Also common to +has_many+ associations, this describes the behavior of
+    #   version records when the parent object is destroyed. This defaults to :delete_all, which
+    #   will permanently remove all associated versions *without* triggering any destroy callbacks.
+    #   Other options are :destroy which removes the associated versions *with* callbacks, or
+    #   :nullify which leaves the version records in the database, but dissociates them from the
+    #   parent object by setting the foreign key columns to +nil+ values.
+    # * <tt>:except</tt>: An update will trigger version creation as long as at least one column
+    #   outside those specified here was updated. Also, upon version creation, the columns
+    #   specified here will be excluded from the change history. This is useful when dealing with
+    #   unimportant, constantly changing, or sensitive information. This option accepts a symbol,
+    #   string or an array of either, representing column names to exclude. It is completely
+    #   optional and defaults to +nil+, allowing all columns to be versioned. This option is also
+    #   ignored if the +only+ option is used.
+    # * <tt>:extend</tt>: This option allows you to extend the +has_many+ association proxy with a
+    #   module or an array of modules. Any methods defined in those modules become available on the
+    #   +versions+ association. The VestalVersions::Versions module is essential to the
+    #   functionality of +vestal_versions+ and so is prepended to any additional modules that you
+    #   might specify here.
+    # * <tt>:if</tt>: Accepts a symbol, a proc or an array of either to be evaluated when the parent
+    #   object is updated to determine whether a new version should be created. +to_proc+ is called
+    #   on any symbols given and the resulting procs are called, passing in the object itself. If
+    #   an array is given, all must be evaluate to +true+ in order for a version to be created.
+    # * <tt>:only</tt>: An update will trigger version creation as long as at least one updated
+    #   column falls within those specified here. Also, upon version creation, only the columns
+    #   specified here will be included in the change history. This option accepts a symbol, string
+    #   or an array of either, representing column names to include. It is completely optional and
+    #   defaults to +nil+, allowing all columns to be versioned. This option takes precedence over
+    #   the +except+ option if both are specified.
+    # * <tt>:unless</tt>: Accepts a symbol, a proc or an array of either to be evaluated when the
+    #   parent object is updated to determine whether version creation should be skipped. +to_proc+
+    #   is called on any symbols given and the resulting procs are called, passing in the object
+    #   itself. If an array is given and any element evaluates as +true+, the version creation will
+    #   be skipped.
+    def versioned(options = {}, &block)
+      return if versioned?
+
+      include Options
+      include Changes
+      include Creation
+      include Users
+      include Reversion
+      include Reset
+      include Conditions
+      include Control
+      include Tagging
+      include Reload
+
+      prepare_versioned_options(options)
+      has_many :versions, options, &block
     end
   end
+
+  extend Configuration
 end
 
-ActiveRecord::Base.send(:include, LaserLemon::VestalVersions)
+ActiveRecord::Base.send(:include, VestalVersions)