README.rdoc in track_changes-0.5.1 vs README.rdoc in track_changes-1.0.0.pre1

@@ -1,70 +1,82 @@
 = track_changes
 
-TrackChanges is a Rails plugin to facilitate tracking
-changes made to an ActiveRecord model in your
-Controller actions.
+TrackChanges is a Rails engine to facilitate tracking changes made to your
+models.
 
 == Why?
 
-I originally looked at the available auditing solutions
-and it appeared that most of them were not thread-safe.
+I originally looked at the available auditing solutions and it appeared that
+most of them were not thread-safe.
 
+== Requirements
+
+* Rails 3
+* A User model
+
+=== Development Requirements
+
+* JRuby
+* Rails 3
+
 == Installation
 
-  gem install track_changes
+Add to your Gemfile:
 
+  gem 'track_changes'
+
+Then, you can run <tt>rails generate track_changes</tt> to create the migration
+file, the initializer, and copy the CSS stylesheet to your application.
+
 == Configuration
 
-You need to have an Audit class that has a polymorphic
-<tt>belongs_to</tt> association to <tt>:audited</tt>. In
-addition, the Audit model must have a <tt>user</tt>
-attribute, and your controllers must respond to
-<tt>current_user</tt>.
+Currently, the only configuration available is in the initializer
+<tt>config/initializers/track_changes_configuration.rb</tt>. In this file, you
+can set a constant TrackChanges::Configuration::DEFAULT_USER_FINDER to a Proc
+that will return a User model when no <tt>current_user</tt> is specified.
 
-Example Audit class:
+== Model Example
 
-  class Audit < ActiveRecord::Base
-    belongs_to :audited, :polymorphic => true
-    serialize :change_set
-  end
+To enable tracking for your model, add the statement <tt>track_changes</tt> in
+your model definition.
 
-Example Audited class:
+Example:
 
   class Post < ActiveRecord::Base
-    has_many :audits, :as => :audited
+    track_changes
   end
 
-You can also tweak some of the defaults by creating an initializer
-in <tt>RAILS_ROOT/config/initializers/track_changes_configuration.rb</tt>
-and calling TrackChanges::Initializer.instance which yields a
-TrackChanges::Configuration object:
+This will add a polymorphic <tt>has_many</tt> association to the Audit class. It
+will also add an accessor <tt>current_user</tt> which you can set prior to
+updating your model. This will be saved in the Audit entry.
 
-  # These are the defaults anyways
-  TrackChanges::Initializer.instance do |c|
-    c.audit_assocation = :audits        # Calls <tt>create!</tt> on this association method
-    c.current_user     = :current_user  # Controller is sent this method to obtain current user.
-    c.ignore_nil       = true           # Don't crash if a model is nil.
-  end
-
 == Controller Example
 
+To enable automatic user tracking in your controllers. Add the <tt>track_changes</tt>
+statement to your controller. Pass a Symbol as an argument which is the name
+of the instance variable(s) (without the <tt>@</tt>). Theses instance variables
+will have their <tt>current_user</tt> attribute assigned to via the controller's
+<tt>current_user</tt> method.
+
+The <tt>track_changes</tt> method in your controller will also pull in the
+AuditsHelper module which provides some simple helpers.
+
+Example:
+
 In this example, after the `update` action is called,
 the `@post` will be compared to a previous version, and
 if there are any changes, an audit will be created.
 
   class PostController < ApplicationController
-    include TrackChanges
-
     before_filter :get_post, :except => [:index, :new]
 
     # specify a single model
     track_changes :post
 
     # you can also specify multiple models
     #track_changes :post1, :post2, ...
-    
+
     def update
       if @post.update_attributes(params[:post])
         flash[:notice] = "Success."
       else
         render :action => "edit"
@@ -79,9 +91,11 @@
     def get_post
       @post = Post.find(params[:id])
     end
   end
 
+Note, you must have a <tt>before_filter</tt> that assigns the model to the expected
+instance variable.
 
 == COPYRIGHT
 
 Copyright (c) 2008-2010 Matt Haley. See LICENSE for details.