paper_trail 4.0.0 → 5.1.0

data/README.md

@@ -1,146 +1,176 @@
-# PaperTrail [![Build Status][4]][5] [![Dependency Status][6]][7]
-
-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](#features)
-- [Compatibility](#compatibility)
-- [Installation](#installation)
-- [API Summary](#api-summary)
-- [Basic Usage](#basic-usage)
-- [Choosing Lifecycle Events To Monitor](#choosing-lifecycle-events-to-monitor)
-- [Choosing When To Save New Versions](#choosing-when-to-save-new-versions)
-- [Choosing Attributes To Monitor](#choosing-attributes-to-monitor)
-- [Reverting And Undeleting A Model](#reverting-and-undeleting-a-model)
-- [Navigating Versions](#navigating-versions)
-- [Finding Out Who Was Responsible For A Change](#finding-out-who-was-responsible-for-a-change)
-- [Custom Version Classes](#custom-version-classes)
-- [Associations](#associations)
-- [Storing metadata](#storing-metadata)
-- [Diffing Versions](#diffing-versions)
-- [Turning PaperTrail Off/On](#turning-papertrail-offon)
-- [Using a custom serializer](#using-a-custom-serializer)
-- [SerializedAttributes support](#serializedattributes-support)
-- [Limiting the Number of Versions Created](#limiting-the-number-of-versions-created)
-- [Deleting Old Versions](#deleting-old-versions)
-- [Testing](#testing)
-
-## Features
-
-* Stores every create, update and destroy (or only the lifecycle events you specify).
-* Does not store updates which don't change anything.
-* Allows you to specify attributes (by inclusion or exclusion) which must change for a Version to be stored.
-* 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.
-* Allows you to get at the version as of a particular time.
-* Option to automatically restore `has_one`, `has_many` and `has_many :through` associations as they were at the time.
-* Automatically records who was responsible via your controller.  PaperTrail calls `current_user` by default, if it exists, but you can have it call any method you like.
-* Allows you to set who is responsible at model-level (useful for migrations).
-* Allows you to store arbitrary model-level metadata with each version (useful for filtering versions).
-* Allows you to store arbitrary controller-level information with each version, e.g. remote IP.
-* Can be turned off/on per class (useful for migrations).
-* Can be turned off/on per request (useful for testing with an external service).
-* Can be turned off/on globally (useful for testing).
-* No configuration necessary.
-* Stores everything in a single database table by default (generates migration for you), or can use separate tables for separate models.
-* Supports custom version classes so different models' versions can have different behaviour.
-* Supports custom name for versions association.
-* Thoroughly tested.
-* Threadsafe.
-
-
-## Compatibility
-
-Works with `ActiveRecord` 3+. Note: this code is on the `master` branch and tagged `v4.x`.
-
-Version 3 is on the branch named [`3.0-stable`][9] and is tagged `v3.x`, and works ActiveRecord 4 and ActiveRecord 3.
-
-Version 2 is on the branch named [`2.7-stable`][10] and is tagged `v2.x`, and works with Rails 3.
-
-The Rails 2.3 code is on the [`rails2`][11] 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
+# PaperTrail
+
+[![Build Status][4]][5] [![Dependency Status][6]][7]
+
+Track changes to your models, for auditing or versioning. See how a model looked
+at any stage in its lifecycle, revert it to any version, or restore it after it
+has been destroyed.
+
+## Documentation
+
+| Version        | Documentation |
+| -------------- | ------------- |
+| 5              | https://github.com/airblade/paper_trail/blob/master/README.md |
+| 4.1            | https://github.com/airblade/paper_trail/blob/4.1-stable/README.md |
+| 4.0            | https://github.com/airblade/paper_trail/blob/4.0-stable/README.md |
+| 3              | https://github.com/airblade/paper_trail/blob/3.0-stable/README.md |
+| 2              | https://github.com/airblade/paper_trail/blob/2.7-stable/README.md |
+| 1              | https://github.com/airblade/paper_trail/blob/rails2/README.md |
+
+## Table of Contents
+
+- [1. Introduction](#1-introduction)
+  - [1.a. Compatibility](#1a-compatibility)
+  - [1.b. Installation](#1b-installation)
+  - [1.c. Basic Usage](#1c-basic-usage)
+  - [1.d. API Summary](#1d-api-summary)
+- [2. Limiting What is Versioned, and When](#2-limiting-what-is-versioned-and-when)
+  - [2.a. Choosing Lifecycle Events To Monitor](#2a-choosing-lifecycle-events-to-monitor)
+  - [2.b. Choosing When To Save New Versions](#2b-choosing-when-to-save-new-versions)
+  - [2.c. Choosing Attributes To Monitor](#2c-choosing-attributes-to-monitor)
+  - [2.d. Turning PaperTrail Off](#2d-turning-papertrail-off)
+  - [2.e. Limiting the Number of Versions Created](#2e-limiting-the-number-of-versions-created)
+- [3. Working With Versions](#3-working-with-versions)
+  - [3.a. Reverting And Undeleting A Model](#3a-reverting-and-undeleting-a-model)
+  - [3.b. Navigating Versions](#3b-navigating-versions)
+  - [3.c. Diffing Versions](#3c-diffing-versions)
+  - [3.d. Deleting Old Versions](#3d-deleting-old-versions)
+- [4. Saving More Information About Versions](#4-saving-more-information-about-versions)
+  - [4.a. Finding Out Who Was Responsible For A Change](#4a-finding-out-who-was-responsible-for-a-change)
+  - [4.b. Associations](#4b-associations)
+  - [4.c. Storing metadata](#4c-storing-metadata)
+- [5. ActiveRecord](#5-activerecord)
+  - [5.a. Single Table Inheritance](#5a-single-table-inheritance-sti)
+  - [5.b. Configuring the `versions` Association](#5b-configuring-the-versions-association)
+  - [5.c. Generators](#5c-generators)
+- [6. Extensibility](#6-extensibility)
+  - [6.a. Custom Version Classes](#6a-custom-version-classes)
+  - [6.b. Custom Serializer](#6b-custom-serializer)
+- [7. Testing](#7-testing)
+- [8. Sinatra](#8-sinatra)
+
+## 1. Introduction
+
+### 1.a. Compatibility
+
+| paper_trail    | branch     | tags   | ruby     | activerecord |
+| -------------- | ---------- | ------ | -------- | ------------ |
+| 5              | master     | v5.x   | >= 1.9.3 | >= 3.0, < 6  |
+| 4              | 4.0-stable | v4.x   | >= 1.8.7 | >= 3.0, < 6  |
+| 3              | 3.0-stable | v3.x   | >= 1.8.7 | >= 3.0, < 5  |
+| 2              | 2.7-stable | v2.x   | >= 1.8.7 | >= 3.0, < 4  |
+| 1              | rails2     | v1.x   | >= 1.8.7 | >= 2.3, < 3  |
+
+### 1.b. Installation
 
 1. Add PaperTrail to your `Gemfile`.
 
-    `gem 'paper_trail', '~> 4.0.0'`
+    `gem 'paper_trail'`
 
-2. Generate a migration which will add a `versions` table to your database.
+1. Add a `versions` table to your database.
 
-    `bundle exec rails generate paper_trail:install`
+    ```
+    bundle exec rails generate paper_trail:install
+    bundle exec rake db:migrate
+    ```
 
-3. Run the migration.
+    If using [rails_admin][38], you must enable the experimental
+    [Associations](#associations) feature. For more information on this
+    generator, see [section 5.c. Generators](#5c-generators).
 
-    `bundle exec rake db:migrate`
-
-4. Add `has_paper_trail` to the models you want to track.
+1. Add `has_paper_trail` to the models you want to track.
 
-### Sinatra
+    ```ruby
+    class Widget < ActiveRecord::Base
+      has_paper_trail
+    end
+    ```
 
-In order to configure PaperTrail for usage with [Sinatra][12], your `Sinatra`
-app must be using `ActiveRecord` 3 or 4. It is also recommended to use the
-[Sinatra ActiveRecord Extension][13] or something similar for managing your
-applications `ActiveRecord` connection in a manner similar to the way `Rails`
-does. If using the aforementioned `Sinatra ActiveRecord Extension`, steps for
-setting up your app with PaperTrail will look something like this:
+1. If your controllers have a `current_user` method, you can easily [track who
+is responsible for changes](#finding-out-who-was-responsible-for-a-change)
+by adding a controller callback.
 
-1. Add PaperTrail to your `Gemfile`.
+    ```ruby
+    class ApplicationController
+      before_filter :set_paper_trail_whodunnit
+    end
+    ```
 
-    `gem 'paper_trail', '~> 4.0.0'`
+### 1.c. Basic Usage
 
-2. Generate a migration to add a `versions` table to your database.
+Your models now have a `versions` method which returns the "paper trail" of
+changes to your model.
 
-    `bundle exec rake db:create_migration NAME=create_versions`
+```ruby
+widget = Widget.find 42
+widget.versions
+# [<PaperTrail::Version>, <PaperTrail::Version>, ...]
+```
 
-3. Copy contents of [create_versions.rb][14]
-into the `create_versions` migration that was generated into your `db/migrate` directory.
+Once you have a version, you can find out what happened:
 
-4. Run the migration.
+```ruby
+v = widget.versions.last
+v.event                     # 'update', 'create', or 'destroy'
+v.created_at                # When the `event` occurred
+v.whodunnit                 # If the update was via a controller and the
+                            # controller has a current_user method, returns the
+                            # id of the current user as a string.
+widget = v.reify            # The widget as it was before the update
+                            # (nil for a create event)
+```
 
-    `bundle exec rake db:migrate`
+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.
 
-5. Add `has_paper_trail` to the models you want to track.
+```ruby
+widget = Widget.find 153
+widget.name                                 # 'Doobly'
 
+# Add has_paper_trail to Widget model.
 
-PaperTrail provides a helper extension that acts similar to the controller mixin
-it provides for `Rails` applications.
+widget.versions                             # []
+widget.update_attributes :name => 'Wotsit'
+widget.versions.last.reify.name             # 'Doobly'
+widget.versions.last.event                  # 'update'
+```
 
-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`)
+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.
 
-If you're using the modular [`Sinatra::Base`][15] style of application, you will
-need to register the extension:
+Here's a helpful table showing what PaperTrail stores:
 
-```ruby
-# bleh_app.rb
-require 'sinatra/base'
+| *Event*        | *create* | *update* | *destroy* |
+| -------------- | -------- | -------- | --------- |
+| *Model Before* | nil      | widget   | widget    |
+| *Model After*  | widget   | widget   | nil       |
 
-class BlehApp < Sinatra::Base
-  register PaperTrail::Sinatra
-end
-```
+PaperTrail stores the values in the Model Before column.  Most other
+auditing/versioning plugins store the After column.
 
-## API Summary
+### 1.d. API Summary
 
 When you declare `has_paper_trail` in your model, you get these methods:
 
 ```ruby
 class Widget < ActiveRecord::Base
-  has_paper_trail   # you can pass various options here
+  has_paper_trail
 end
 
-# Returns this widget's versions.  You can customise the name of the association.
+# Returns this widget's versions.  You can customise the name of the
+# association, but overriding this method is not supported.
 widget.versions
 
 # Return the version this widget was reified from, or nil if it is live.
 # You can customise the name of the method.
 widget.version
 
-# Returns true if this widget is the current, live one; or false if it is from a previous version.
+# Returns true if this widget is the current, live one; or false if it is from
+# a previous version.
 widget.live?
 
 # Returns who put the widget into its current state.
@@ -155,7 +185,8 @@ widget.previous_version
 # Returns the widget (not a version) as it became next.
 widget.next_version
 
-# Generates a version for a `touch` event (`widget.touch` does NOT generate a version)
+# Generates a version for a `touch` event (`widget.touch` does NOT generate a
+# version)
 widget.touch_with_version
 
 # Turn PaperTrail off for all widgets.
@@ -164,12 +195,15 @@ Widget.paper_trail_off!
 # Turn PaperTrail on for all widgets.
 Widget.paper_trail_on!
 
-# Check whether PaperTrail is enabled for all widgets.
+# Is PaperTrail enabled for Widget, the class?
 Widget.paper_trail_enabled_for_model?
-widget.paper_trail_enabled_for_model? # only available on instances of versioned models
+
+# Is PaperTrail enabled for widget, the instance?
+widget.paper_trail_enabled_for_model?
 ```
 
-And a `PaperTrail::Version` instance has these methods:
+And a `PaperTrail::Version` instance (which is just an ordinary ActiveRecord
+instance, with all the usual methods) adds these methods:
 
 ```ruby
 # Returns the item restored from this version.
@@ -198,13 +232,11 @@ version.index
 # Returns the event that caused this version (create|update|destroy).
 version.event
 
-# Query versions objects by attributes.
+# Query the `versions.object` column (or `object_changes` column), by
+# attributes, using the SQL LIKE operator. Known issue: inconsistent results for
+# numeric values due to limitations of SQL wildcard matchers against the
+# serialized objects.
 PaperTrail::Version.where_object(attr1: val1, attr2: val2)
-
-# Query versions object_changes field by attributes (requires
-# `object_changes` column on versions table).
-# Also can't guarantee consistent query results for numeric values
-# due to limitations of SQL wildcard matchers against the serialized objects.
 PaperTrail::Version.where_object_changes(attr1: val1)
 ```
 
@@ -220,90 +252,9 @@ user_for_paper_trail
 info_for_paper_trail
 ```
 
-## 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`.
+## 2. Limiting What is Versioned, and When
 
-```ruby
-class Widget < ActiveRecord::Base
-  has_paper_trail
-end
-```
-
-This gives you a `versions` method which returns the paper trail of changes to
-your model.
-
-```ruby
-widget = Widget.find 42
-widget.versions
-# [<PaperTrail::Version>, <PaperTrail::Version>, ...]
-```
-
-Once you have a version, you can find out what happened:
-
-```ruby
-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.
-
-```ruby
-widget = Widget.find 153
-widget.name                                 # 'Doobly'
-
-# Add has_paper_trail to Widget model.
-
-widget.versions                             # []
-widget.update_attributes :name => 'Wotsit'
-widget.versions.last.reify.name             # 'Doobly'
-widget.versions.last.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.
-
-
-## Choosing Lifecycle Events To Monitor
+### 2.a. Choosing Lifecycle Events To Monitor
 
 You can choose which events to track with the `on` option.  For example, to
 ignore `create` events:
@@ -314,6 +265,10 @@ class Article < ActiveRecord::Base
 end
 ```
 
+`has_paper_trail` installs callbacks for these lifecycle events. If there are
+other callbacks in your model, their order relative to those installed by
+PaperTrail may matter, so be aware of any potential interactions.
+
 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
@@ -334,7 +289,31 @@ a.versions.size                           # 3
 a.versions.last.event                     # 'update'
 ```
 
-## Choosing When To Save New Versions
+#### Controlling the Order of AR Callbacks
+
+The `has_paper_trail` method installs AR callbacks. If you need to control
+their order, use the `paper_trail_on_*` methods.
+
+```ruby
+class Article < ActiveRecord::Base
+
+  # Include PaperTrail, but do not add any callbacks yet. Passing the
+  # empty array to `:on` omits callbacks.
+  has_paper_trail :on => []
+
+  # Add callbacks in the order you need.
+  paper_trail_on_destroy    # add destroy callback
+  paper_trail_on_update     # etc.
+  paper_trail_on_create
+end
+```
+
+The `paper_trail_on_destroy` method can be further configured to happen
+`:before` or `:after` the destroy event. In PaperTrail 4, the default is
+`:after`. In PaperTrail 5, the default will be `:before`, to support
+ActiveRecord 5. (see https://github.com/airblade/paper_trail/pull/683)
+
+### 2.b. Choosing When To Save New Versions
 
 You can choose the conditions when to add new versions with the `if` and
 `unless` options. For example, to save versions only for US non-draft
@@ -347,8 +326,13 @@ class Translation < ActiveRecord::Base
 end
 ```
 
+#### Choosing Based on Changed Attributes
+
+Starting with PaperTrail 4.0, versions are saved during an after-callback. If
+you decide whether to save a new version based on changed attributes, please
+use attribute_name_was instead of attribute_name.
 
-## Choosing Attributes To Monitor
+### 2.c. Choosing Attributes To Monitor
 
 You can ignore changes to certain attributes like this:
 
@@ -435,7 +419,78 @@ class Article < ActiveRecord::Base
 end
 ```
 
-## Reverting And Undeleting A Model
+### 2.d. Turning PaperTrail Off
+
+PaperTrail is on by default, but sometimes you don't want to record versions.
+
+#### Per Process
+
+Turn PaperTrail off for all threads in a `ruby` process.
+
+```ruby
+PaperTrail.enabled = false
+```
+
+This is commonly used to speed up tests. See [Testing](#testing) below.
+
+There is also a rails config option that does the same thing.
+
+```ruby
+# in config/environments/test.rb
+config.paper_trail.enabled = false
+```
+
+#### Per Request
+
+Add a `paper_trail_enabled_for_controller` method to your controller.
+
+```ruby
+class ApplicationController < ActionController::Base
+  def paper_trail_enabled_for_controller
+    request.user_agent != 'Disable User-Agent'
+  end
+end
+```
+
+#### Per Class
+
+```ruby
+Widget.paper_trail_off!
+Widget.paper_trail_on!
+```
+
+#### Per Method
+
+You can call a method without creating a new version using `without_versioning`.
+ It takes either a method name as a symbol:
+
+```ruby
+@widget.without_versioning :destroy
+```
+
+Or a block:
+
+```ruby
+@widget.without_versioning do
+  @widget.update_attributes :name => 'Ford'
+end
+```
+
+### 2.e. Limiting the Number of Versions Created
+
+Configure `version_limit` to cap the number of versions saved per record. This
+does not apply to `create` events.
+
+```ruby
+# Limit: 4 versions per record (3 most recent, plus a `create` event)
+PaperTrail.config.version_limit = 3
+# Remove the limit
+PaperTrail.config.version_limit = nil
+```
+
+## 3. Working With Versions
+
+### 3.a. Reverting And Undeleting A Model
 
 PaperTrail makes reverting to a previous version easy:
 
@@ -472,7 +527,7 @@ You could even use PaperTrail to implement an undo system, [Ryan Bates has!][3]
 If your model uses [optimistic locking][1] don't forget to [increment your
 `lock_version`][2] before saving or you'll get a `StaleObjectError`.
 
-## Navigating Versions
+### 3.b. Navigating Versions
 
 You can call `previous_version` and `next_version` on an item to get it as it
 was/became.  Note that these methods reify the item for you.
@@ -528,25 +583,91 @@ And you can perform `WHERE` queries for object versions based on attributes:
 PaperTrail::Version.where_object(content: "Hello", title: "Article")
 ```
 
-## Finding Out Who Was Responsible For A Change
+### 3.c. Diffing Versions
 
-If your `ApplicationController` has a `current_user` method, PaperTrail will
-attempt to store the value returned by `current_user.id` in the version's
-`whodunnit` column.
+There are two scenarios: diffing adjacent versions and diffing non-adjacent
+versions.
 
-You may want PaperTrail to call a different method to find out who is
-responsible.  To do so, override the `user_for_paper_trail` method in your
-controller like this:
+The best way to diff adjacent versions is to get PaperTrail to do it for you.
+If you add an `object_changes` text column to your `versions` table, either at
+installation time with the `rails generate paper_trail:install --with-changes`
+option or manually, PaperTrail will store the `changes` diff (excluding any
+attributes PaperTrail is ignoring) in each `update` version.  You can use the
+`version.changeset` method to retrieve it.  For example:
 
 ```ruby
-class ApplicationController
-  def user_for_paper_trail
-    logged_in? ? current_member.id : 'Public user'  # or whatever
-  end
-end
+widget = Widget.create :name => 'Bob'
+widget.versions.last.changeset
+# {
+#   "name"=>[nil, "Bob"],
+#   "created_at"=>[nil, 2015-08-10 04:10:40 UTC],
+#   "updated_at"=>[nil, 2015-08-10 04:10:40 UTC],
+#   "id"=>[nil, 1]
+# }
+widget.update_attributes :name => 'Robert'
+widget.versions.last.changeset
+# {
+#   "name"=>["Bob", "Robert"],
+#   "updated_at"=>[2015-08-10 04:13:19 UTC, 2015-08-10 04:13:19 UTC]
+# }
+widget.destroy
+widget.versions.last.changeset
+# {}
+```
+
+The `object_changes` are only stored for creation and updates, not when an
+object is destroyed.
+
+Please be aware that PaperTrail doesn't use diffs internally.  When I designed
+PaperTrail I wanted simplicity and robustness so I decided to make each version
+of an object self-contained.  A version stores all of its object's data, not a
+diff from the previous version.  This means you can delete any version without
+affecting any other.
+
+To diff non-adjacent versions you'll have to write your own code.  These
+libraries may help:
+
+For diffing two strings:
+
+* [htmldiff][19]: expects but doesn't require HTML input and produces HTML
+  output.  Works very well but slows down significantly on large (e.g. 5,000
+  word) inputs.
+* [differ][20]: expects plain text input and produces plain
+  text/coloured/HTML/any output.  Can do character-wise, word-wise, line-wise,
+  or arbitrary-boundary-string-wise diffs.  Works very well on non-HTML input.
+* [diff-lcs][21]: old-school, line-wise diffs.
+
+For diffing two ActiveRecord objects:
+
+* [Jeremy Weiskotten's PaperTrail fork][22]: uses ActiveSupport's diff to return
+  an array of hashes of the changes.
+* [activerecord-diff][23]: rather like ActiveRecord::Dirty but also allows you
+  to specify which columns to compare.
+
+If you wish to selectively record changes for some models but not others you
+can opt out of recording changes by passing `:save_changes => false` to your
+`has_paper_trail` method declaration.
+
+### 3.d. Deleting Old Versions
+
+Over time your `versions` table will grow to an unwieldy size.  Because each
+version is self-contained (see the Diffing section above for more) you can
+simply delete any records you don't want any more.  For example:
+
+```sql
+sql> delete from versions where created_at < 2010-06-01;
+```
+
+```ruby
+PaperTrail::Version.delete_all ["created_at < ?", 1.week.ago]
 ```
 
-In a console session you can manually set who is responsible like this:
+## 4. Saving More Information About Versions
+
+### 4.a. Finding Out Who Was Responsible For A Change
+
+Set `PaperTrail.whodunnit=`, and that value will be stored in the version's
+`whodunnit` column.
 
 ```ruby
 PaperTrail.whodunnit = 'Andy Stewart'
@@ -554,6 +675,28 @@ widget.update_attributes :name => 'Wibble'
 widget.versions.last.whodunnit              # Andy Stewart
 ```
 
+If your controller has a `current_user` method, PaperTrail provides a
+`before_filter` that will assign `current_user.id` to `PaperTrail.whodunnit`.
+You can add this `before_filter` to your `ApplicationController`.
+
+```ruby
+class ApplicationController
+  before_filter :set_paper_trail_whodunnit
+end
+```
+
+You may want `set_paper_trail_whodunnit` to call a different method to find out
+who is responsible. To do so, override the `user_for_paper_trail` method in
+your controller like this:
+
+```ruby
+class ApplicationController
+  def user_for_paper_trail
+    logged_in? ? current_member.id : 'Public user'  # or whatever
+  end
+end
+```
+
 See also: [Setting whodunnit in the rails console][33]
 
 Sometimes you want to define who is responsible for a change in a small scope
@@ -586,7 +729,7 @@ like it does, call `paper_trail_originator` on the object.
 widget = Widget.find 153                    # assume widget has 0 versions
 PaperTrail.whodunnit = 'Alice'
 widget.update_attributes :name => 'Yankee'
-widget..paper_trail_originator              # 'Alice'
+widget.paper_trail_originator               # 'Alice'
 PaperTrail.whodunnit = 'Bob'
 widget.update_attributes :name => 'Zulu'
 widget.paper_trail_originator               # 'Bob'
@@ -595,80 +738,18 @@ first_version.whodunnit                     # 'Alice'
 first_version.paper_trail_originator        # nil
 first_version.terminator                    # 'Alice'
 last_version.whodunnit                      # 'Bob'
-last_version.paper_trail_originator         # 'Alice'
-last_version.terminator                     # 'Bob'
-```
-
-## Custom Version Classes
-
-You can specify custom version subclasses with the `:class_name` option:
-
-```ruby
-class PostVersion < PaperTrail::Version
-  # custom behaviour, e.g:
-  self.table_name = :post_versions
-end
-
-class Post < ActiveRecord::Base
-  has_paper_trail :class_name => 'PostVersion'
-end
-```
-
-Unlike ActiveRecord's `class_name`, you'll have to supply the complete module path to the class (e.g. `Foo::BarVersion` if your class is inside the module `Foo`).
-
-### Advantages
-
-1. For models which have a lot of versions, storing each model's versions in a
-   separate table can improve the performance of certain database queries.
-1. Store different version [metadata](#storing-metadata) for different models.
-
-### Configuration
-
-If you are using Postgres, you should also define the sequence that your custom
-version class will use:
-
-```ruby
-class PostVersion < PaperTrail::Version
-  self.table_name = :post_versions
-  self.sequence_name = :post_versions_id_seq
-end
-```
-
-If you only use custom version classes and don't have a `versions` table, you
-must let ActiveRecord know that the `PaperTrail::Version` class is an
-`abstract_class`.
-
-```ruby
-# app/models/paper_trail/version.rb
-module PaperTrail
-  class Version < ActiveRecord::Base
-    include PaperTrail::VersionConcern
-    self.abstract_class = true
-  end
-end
+last_version.paper_trail_originator         # 'Alice'
+last_version.terminator                     # 'Bob'
 ```
 
-You can also specify custom names for the versions and version associations.
-This is useful if you already have `versions` or/and `version` methods on your
-model.  For example:
+#### Storing an ActiveRecord globalid in whodunnit
 
-```ruby
-class Post < ActiveRecord::Base
-  has_paper_trail :versions => :paper_trail_versions,
-                  :version  => :paper_trail_version
+If you would like `whodunnit` to return an `ActiveRecord` object instead of a
+string, please try the [paper_trail-globalid][37] gem.
 
-  # Existing versions method.  We don't want to clash.
-  def versions
-    ...
-  end
-  # Existing version method.  We don't want to clash.
-  def version
-    ...
-  end
-end
-```
+### 4.b. Associations
 
-## Associations
+**Experimental feature**, see caveats below.
 
 PaperTrail can restore three types of associations: Has-One, Has-Many, and
 Has-Many-Through. In order to do this, you will need to create a
@@ -684,7 +765,8 @@ the association that are created in the same transaction.
 
 To restore Has-One associations as they were at the time, pass option `:has_one
 => true` to `reify`. To restore Has-Many and Has-Many-Through associations, use
-option `:has_many => true`.  For example:
+option `:has_many => true`. To restore Belongs-To association, use
+option `:belongs_to => true`. For example:
 
 ```ruby
 class Location < ActiveRecord::Base
@@ -760,14 +842,23 @@ widget.reload.wotsit                             # nil
 
 **Caveats:**
 
+1. Not compatible with [transactional tests][34], aka. transactional fixtures.
+   This is a known issue [#542](https://github.com/airblade/paper_trail/issues/542)
+   that we'd like to solve.
+1. Requires database timestamp columns with fractional second precision.
+   - Sqlite and postgres timestamps have fractional second precision by default.
+   [MySQL timestamps do not][35]. Furthermore, MySQL 5.5 and earlier do not
+   support fractional second precision at all.
+   - Also, support for fractional seconds in MySQL was not added to
+   rails until ActiveRecord 4.2 (https://github.com/rails/rails/pull/14359).
 1. PaperTrail can't restore an association properly if the association record
    can be updated to replace its parent model (by replacing the foreign key)
-2. Currently PaperTrail only support single `version_associations` table. The
+1. Currently PaperTrail only supports a single `version_associations` table. The
    implication is that you can only use a single table to store the versions for
    all related models. Sorry for those who use multiple version tables.
-3. PaperTrail only reifies the first level of associations, i.e., it does not
+1. PaperTrail only reifies the first level of associations, i.e., it does not
    reify any associations of its associations, and so on.
-4. PaperTrail relies on the callbacks on the association model (and the :through
+1. PaperTrail relies on the callbacks on the association model (and the :through
    association model for Has-Many-Through associations) to record the versions
    and the relationship between the versions. If the association is changed
    without invoking the callbacks, Reification won't work. Below are some
@@ -835,7 +926,7 @@ end
 
 See [issue 113][16] for a discussion about this.
 
-## Storing Metadata
+### 4.c. Storing Metadata
 
 You can store arbitrary model-level metadata alongside each version like this:
 
@@ -853,8 +944,9 @@ end
 
 PaperTrail will call your proc with the current article and store the result in
 the `author_id` column of the `versions` table.
+Don't forget to add any such columns to your `versions` table.
 
-### Advantages of Metadata
+#### Advantages of Metadata
 
 Why would you do this?  In this example, `author_id` is an attribute of
 `Article` and PaperTrail will store it anyway in a serialized form in the
@@ -868,7 +960,7 @@ those versions you want:
 PaperTrail::Version.where(:author_id => author_id)
 ```
 
-### Metadata from Controllers
+#### Metadata from Controllers
 
 You can also store any information you like from your controller.  Override
 the `info_for_paper_trail` method in your controller to return a hash whose keys
@@ -882,9 +974,9 @@ class ApplicationController
 end
 ```
 
-### Protected Attributes and Metadata
+#### Protected Attributes and Metadata
 
-If you are using rails 3 or the [protected_attributes][17] gem you must declare 
+If you are using rails 3 or the [protected_attributes][17] gem you must declare
 your metadata columns to be `attr_accessible`.
 
 ```ruby
@@ -900,165 +992,138 @@ end
 If you're using [strong_parameters][18] instead of [protected_attributes][17]
 then there is no need to use `attr_accessible`.
 
-## Diffing Versions
+## 5. ActiveRecord
 
-There are two scenarios: diffing adjacent versions and diffing non-adjacent
-versions.
+### 5.a. Single Table Inheritance (STI)
 
-The best way to diff adjacent versions is to get PaperTrail to do it for you.
-If you add an `object_changes` text column to your `versions` table, either at
-installation time with the `rails generate paper_trail:install --with-changes`
-option or manually, PaperTrail will store the `changes` diff (excluding any
-attributes PaperTrail is ignoring) in each `update` version.  You can use the
-`version.changeset` method to retrieve it.  For example:
+PaperTrail supports [Single Table Inheritance][39], and even supports an
+un-versioned base model, as of 23ffbdc7e1.
 
 ```ruby
-widget = Widget.create :name => 'Bob'
-widget.versions.last.changeset                # {'name' => [nil, 'Bob']}
-widget.update_attributes :name => 'Robert'
-widget.versions.last.changeset                # {'name' => ['Bob', 'Robert']}
-widget.destroy
-widget.versions.last.changeset                # {}
+class Fruit < ActiveRecord::Base
+  # un-versioned base model
+end
+class Banana < Fruit
+  has_paper_trail
+end
 ```
 
-Note PaperTrail only stores the changes for creation and updates; it doesn't
-store anything when an object is destroyed.
-
-Please be aware that PaperTrail doesn't use diffs internally.  When I designed
-PaperTrail I wanted simplicity and robustness so I decided to make each version
-of an object self-contained.  A version stores all of its object's data, not a
-diff from the previous version.  This means you can delete any version without
-affecting any other.
-
-To diff non-adjacent versions you'll have to write your own code.  These
-libraries may help:
+However, there is a known issue when reifying [associations](#associations),
+see https://github.com/airblade/paper_trail/issues/594
 
-For diffing two strings:
+### 5.b. Configuring the `versions` Association
 
-* [htmldiff][19]: expects but doesn't require HTML input and produces HTML
-  output.  Works very well but slows down significantly on large (e.g. 5,000
-  word) inputs.
-* [differ][20]: expects plain text input and produces plain
-  text/coloured/HTML/any output.  Can do character-wise, word-wise, line-wise,
-  or arbitrary-boundary-string-wise diffs.  Works very well on non-HTML input.
-* [diff-lcs][21]: old-school, line-wise diffs.
+You may configure the name of the `versions` association by passing
+a different name to `has_paper_trail`.
 
-For diffing two ActiveRecord objects:
+```ruby
+class Post < ActiveRecord::Base
+  has_paper_trail class_name: 'Version', versions: :drafts
+end
 
-* [Jeremy Weiskotten's PaperTrail fork][22]: uses ActiveSupport's diff to return
-  an array of hashes of the changes.
-* [activerecord-diff][23]: rather like ActiveRecord::Dirty but also allows you
-  to specify which columns to compare.
+Post.new.versions # => NoMethodError
+```
 
-If you wish to selectively record changes for some models but not others you
-can opt out of recording changes by passing `:save_changes => false` to your
-`has_paper_trail` method declaration.
+Overriding (instead of configuring) the `versions` method is not supported.
+Overriding associations is not recommended in general.
 
-## Turning PaperTrail Off/On
+### 5.c. Generators
 
-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 -- or when testing your application.
+PaperTrail has one generator, `paper_trail:install`. It writes, but does not
+run, a migration file. This migration adds (at least) the `versions` table. The
+most up-to-date documentation for this generator can be found by running `rails
+generate paper_trail:install --help`, but a copy is included here for
+convenience.
 
-You can turn PaperTrail on or off in three ways: globally, per request, or per
-class.
+```
+Usage:
+  rails generate paper_trail:install [options]
 
-### Globally
+Options:
+  [--with-changes], [--no-with-changes]            # Store changeset (diff) with each version
+  [--with-associations], [--no-with-associations]  # Store transactional IDs to support association restoration
 
-On a global level you can turn PaperTrail off like this:
+Runtime options:
+  -f, [--force]                    # Overwrite files that already exist
+  -p, [--pretend], [--no-pretend]  # Run but do not make any changes
+  -q, [--quiet], [--no-quiet]      # Suppress status output
+  -s, [--skip], [--no-skip]        # Skip files that already exist
 
-```ruby
-PaperTrail.enabled = false
+Generates (but does not run) a migration to add a versions table.
 ```
 
-For example, you might want to disable PaperTrail in your Rails application's
-test environment to speed up your tests.  This will do it (note: this gets done
-automatically for `RSpec` and `Cucumber`, please see the [Testing
-section](#testing)):
+## 6. Extensibility
 
-```ruby
-# in config/environments/test.rb
-config.after_initialize do
-  PaperTrail.enabled = false
-end
-```
+### 6.a. Custom Version Classes
 
-If you disable PaperTrail in your test environment but want to enable it for
-specific tests, you can add a helper like this to your test helper:
+You can specify custom version subclasses with the `:class_name` option:
 
 ```ruby
-# in test/test_helper.rb
-def with_versioning
-  was_enabled = PaperTrail.enabled?
-  was_enabled_for_controller = PaperTrail.enabled_for_controller?
-  PaperTrail.enabled = true
-  PaperTrail.enabled_for_controller = true
-  begin
-    yield
-  ensure
-    PaperTrail.enabled = was_enabled
-    PaperTrail.enabled_for_controller = was_enabled_for_controller
-  end
+class PostVersion < PaperTrail::Version
+  # custom behaviour, e.g:
+  self.table_name = :post_versions
 end
-```
 
-And then use it in your tests like this:
-
-```ruby
-test "something that needs versioning" do
-  with_versioning do
-    # your test
-  end
+class Post < ActiveRecord::Base
+  has_paper_trail :class_name => 'PostVersion'
 end
 ```
 
-### Per request
+Unlike ActiveRecord's `class_name`, you'll have to supply the complete module path to the class (e.g. `Foo::BarVersion` if your class is inside the module `Foo`).
 
-You can turn PaperTrail on or off per request by adding a
-`paper_trail_enabled_for_controller` method to your controller which returns
-`true` or `false`:
+#### Advantages
 
-```ruby
-class ApplicationController < ActionController::Base
-  def paper_trail_enabled_for_controller
-    request.user_agent != 'Disable User-Agent'
-  end
-end
-```
+1. For models which have a lot of versions, storing each model's versions in a
+   separate table can improve the performance of certain database queries.
+1. Store different version [metadata](#storing-metadata) for different models.
 
-### Per class
+#### Configuration
 
-If you are about to change some widgets and you don't want a paper trail of your
-changes, you can turn PaperTrail off like this:
+If you are using Postgres, you should also define the sequence that your custom
+version class will use:
 
 ```ruby
-Widget.paper_trail_off!
+class PostVersion < PaperTrail::Version
+  self.table_name = :post_versions
+  self.sequence_name = :post_versions_id_seq
+end
 ```
 
-And on again like this:
+If you only use custom version classes and don't have a `versions` table, you
+must let ActiveRecord know that the `PaperTrail::Version` class is an
+`abstract_class`.
 
 ```ruby
-Widget.paper_trail_on!
+# app/models/paper_trail/version.rb
+module PaperTrail
+  class Version < ActiveRecord::Base
+    include PaperTrail::VersionConcern
+    self.abstract_class = true
+  end
+end
 ```
 
-### Per method call
-
-You can call a method without creating a new version using `without_versioning`.
- It takes either a method name as a symbol:
+You can also specify custom names for the versions and version associations.
+This is useful if you already have `versions` or/and `version` methods on your
+model.  For example:
 
 ```ruby
-@widget.without_versioning :destroy
-```
-
-Or a block:
+class Post < ActiveRecord::Base
+  has_paper_trail :versions => :paper_trail_versions,
+                  :version  => :paper_trail_version
 
-```ruby
-@widget.without_versioning do
-  @widget.update_attributes :name => 'Ford'
+  # Existing versions method.  We don't want to clash.
+  def versions
+    ...
+  end
+  # Existing version method.  We don't want to clash.
+  def version
+    ...
+  end
 end
 ```
 
-## Using a custom serializer
+### 6.b. Custom Serializer
 
 By default, PaperTrail stores your changes as a `YAML` dump. You can override
 this with the serializer config option:
@@ -1073,10 +1138,10 @@ method.  These serializers are included in the gem for your convenience:
 * [PaperTrail::Serializers::YAML][24] - Default
 * [PaperTrail::Serializers::JSON][25]
 
-### PostgreSQL JSON column type support
+#### PostgreSQL JSON column type support
 
 If you use PostgreSQL, and would like to store your `object` (and/or
-`object_changes`) data in a column of [type `JSON` or type `JSONB`][26], specify
+`object_changes`) data in a column of [type `json` or type `jsonb`][26], specify
 `json` instead of `text` for these columns in your migration:
 
 ```ruby
@@ -1088,71 +1153,143 @@ create_table :versions do |t|
 end
 ```
 
-Note: You don't need to use a particular serializer for the PostgreSQL `JSON`
-column type.
+If you use the PostgreSQL `json` or `jsonb` column type, you do not need
+to specify a `PaperTrail.serializer`.
 
-## SerializedAttributes support
+##### Convert existing YAML data to JSON
 
-PaperTrail has a config option that can be used to enable/disable whether
-PaperTrail attempts to utilize `ActiveRecord`'s `serialized_attributes` feature.
-Note: This is enabled by default when PaperTrail is used with `ActiveRecord`
-version < `4.2`, and disabled by default when used with ActiveRecord `4.2.x`.
-Since `serialized_attributes` will be removed in `ActiveRecord` version `5.0`,
-this configuration value has no functionality when PaperTrail is used with
-version `5.0` or greater.
+If you've been using PaperTrail for a while with the default YAML serializer
+and you want to switch to JSON or JSONB, you're in a bit of a bind because
+there's no automatic way to migrate your data. The first (slow) option is to
+loop over every record and parse it in Ruby, then write to a temporary column:
 
 ```ruby
-# Enable support
-PaperTrail.config.serialized_attributes = true
-# Disable support
-PaperTrail.config.serialized_attributes = false
-# Get current setting
-PaperTrail.serialized_attributes?
+add_column :versions, :object, :new_object, :jsonb # or :json
+
+PaperTrail::Version.reset_column_information
+PaperTrail::Version.find_each do |version|
+  version.update_column :new_object, YAML.load(version.object)
+end
+
+remove_column :versions, :object
+rename_column :versions, :new_object, :object
 ```
 
-## Limiting the Number of Versions Created
+This technique can be very slow if you have a lot of data. Though slow, it is
+safe in databases where transactions are protected against DDL, such as
+Postgres. In databases without such protection, such as MySQL, a table lock may
+be necessary.
 
-Configure `version_limit` to cap the number of versions saved per record. This
-does not apply to `create` events.
+If the above technique is too slow for your needs, and you're okay doing without
+PaperTrail data temporarily, you can create the new column without converting
+the data.
 
 ```ruby
-# Limit: 4 versions per record (3 most recent, plus a `create` event)
-PaperTrail.config.version_limit = 3
-# Remove the limit
-PaperTrail.config.version_limit = nil
+rename_column :versions, :object, :old_object
+add_column :versions, :object, :jsonb # or :json
 ```
 
-## Deleting Old Versions
+After that migration, your historical data still exists as YAML, and new data
+will be stored as JSON. Next, convert records from YAML to JSON using a
+background script.
 
-Over time your `versions` table will grow to an unwieldy size.  Because each
-version is self-contained (see the Diffing section above for more) you can
-simply delete any records you don't want any more.  For example:
+```ruby
+PaperTrail::Version.where.not(old_object: nil).find_each do |version|
+  version.update_columns old_object: nil, object: YAML.load(version.old_object)
+end
+```
+
+Finally, in another migration, remove the old column.
+
+```ruby
+remove_column :versions, :old_object
+```
+
+If you use the optional `object_changes` column, don't forget to convert it
+also, using the same technique.
+
+##### Convert a Column from Text to JSON
+
+If your `object` column already contains JSON data, and you want to change its
+data type to `json` or `jsonb`, you can use the following [DDL][36]. Of course,
+if your `object` column contains YAML, you must first convert the data to JSON
+(see above) before you can change the column type.
+
+Using SQL:
 
 ```sql
-sql> delete from versions where created_at < 2010-06-01;
+alter table versions
+alter column object type jsonb
+using object::jsonb;
 ```
 
+Using ActiveRecord:
+
 ```ruby
-PaperTrail::Version.delete_all ["created_at < ?", 1.week.ago]
+class ConvertVersionsObjectToJson < ActiveRecord::Migration
+  def up
+    change_column :versions, :object, 'jsonb USING object::jsonb'
+  end
+
+  def down
+    change_column :versions, :object, 'text USING object::text'
+  end
+end
 ```
 
-## Testing
+## 7. Testing
 
-You may want to turn PaperTrail off to speed up your tests.  See the [Turning
-PaperTrail Off/On](#turning-papertrail-offon) section above for tips on usage
-with `Test::Unit`.
+You may want to turn PaperTrail off to speed up your tests.  See [Turning
+PaperTrail Off](#turning-papertrail-off) above.
 
-### RSpec
+### 7.a. Minitest
 
-PaperTrail provides a helper that works with [RSpec][27] to make it easier to
-control when `PaperTrail` is enabled during testing.
+First, disable PT for the entire `ruby` process.
 
-If you wish to use the helper, you will need to require it in your RSpec test
-helper like so:
+```ruby
+# in config/environments/test.rb
+config.after_initialize do
+  PaperTrail.enabled = false
+end
+```
+
+Then, to enable PT for specific tests, you can add a `with_versioning` test
+helper method.
 
 ```ruby
-# spec/rails_helper.rb
+# in test/test_helper.rb
+def with_versioning
+  was_enabled = PaperTrail.enabled?
+  was_enabled_for_controller = PaperTrail.enabled_for_controller?
+  PaperTrail.enabled = true
+  PaperTrail.enabled_for_controller = true
+  begin
+    yield
+  ensure
+    PaperTrail.enabled = was_enabled
+    PaperTrail.enabled_for_controller = was_enabled_for_controller
+  end
+end
+```
+
+Then, use the helper in your tests.
+
+```ruby
+test "something that needs versioning" do
+  with_versioning do
+    # your test
+  end
+end
+```
+
+### 7.b. RSpec
 
+PaperTrail provides a helper, `paper_trail/frameworks/rspec.rb`, that works with
+[RSpec][27] to make it easier to control when `PaperTrail` is enabled during
+testing.
+
+```ruby
+# spec/rails_helper.rb
 ENV["RAILS_ENV"] ||= 'test'
 require 'spec_helper'
 require File.expand_path("../../config/environment", __FILE__)
@@ -1161,10 +1298,10 @@ require 'rspec/rails'
 require 'paper_trail/frameworks/rspec'
 ```
 
-When the helper is loaded, PaperTrail will be turned off for all tests by
-default. When you wish to enable PaperTrail for a test you can either wrap the
+With the helper loaded, PaperTrail will be turned off for all tests by
+default. 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:
+spec block.
 
 ```ruby
 describe "RSpec test group" do
@@ -1235,7 +1372,7 @@ matcher
 
 ```
 
-### Cucumber
+### 7.c. Cucumber
 
 PaperTrail provides a helper for [Cucumber][28] that works similar to the RSpec
 helper.If you wish to use the helper, you will need to require in your cucumber
@@ -1268,7 +1405,7 @@ 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.
 
-### Spork
+### 7.d. Spork
 
 If you wish to use the `RSpec` or `Cucumber` helpers with [Spork][29], you will
 need to manually require the helper(s) in your `prefork` block on your test
@@ -1291,7 +1428,7 @@ Spork.prefork do
 end
 ```
 
-### Zeus or Spring
+### 7.e. Zeus or Spring
 
 If you wish to use the `RSpec` or `Cucumber` helpers with [Zeus][30] or
 [Spring][31], you will need to manually require the helper(s) in your test
@@ -1307,20 +1444,50 @@ require 'rspec/rails'
 require 'paper_trail/frameworks/rspec'
 ```
 
-## Testing PaperTrail
+## 8. Sinatra
+
+To configure PaperTrail for usage with [Sinatra][12], your `Sinatra`
+app must be using `ActiveRecord` 3 or 4. It is also recommended to use the
+[Sinatra ActiveRecord Extension][13] or something similar for managing your
+applications `ActiveRecord` connection in a manner similar to the way `Rails`
+does. If using the aforementioned `Sinatra ActiveRecord Extension`, steps for
+setting up your app with PaperTrail will look something like this:
 
-Paper Trail has facilities to test against Postgres, Mysql and SQLite. To switch
-between DB engines you will need to export the DB variable for the engine you
-wish to test aganist.
+1. Add PaperTrail to your `Gemfile`.
 
-Though be aware we do not have the abilty to create the db's (except sqlite) for
-you. You can look at .travis.yml before_script for an example of how to create
-the db's needed.
+    `gem 'paper_trail'`
 
-```
-export DB=postgres
-export DB=mysql
-export DB=sqlite # this is default
+2. Generate a migration to add a `versions` table to your database.
+
+    `bundle exec rake db:create_migration NAME=create_versions`
+
+3. Copy contents of [create_versions.rb][14]
+into the `create_versions` migration that was generated into your `db/migrate` directory.
+
+4. Run the migration.
+
+    `bundle exec rake db:migrate`
+
+5. Add `has_paper_trail` to the models you want to track.
+
+
+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`][15] style of application, you will
+need to register the extension:
+
+```ruby
+# bleh_app.rb
+require 'sinatra/base'
+
+class BlehApp < Sinatra::Base
+  register PaperTrail::Sinatra
+end
 ```
 
 ## Articles
@@ -1331,7 +1498,6 @@ export DB=sqlite # this is default
   [Ilya Bodrov](http://www.sitepoint.com/author/ibodrov), 10th April 2014
 * [Using PaperTrail to track stack traces](http://rubyrailsexpert.com/?p=36),
   T James Corcoran's blog, 1st October 2013.
-* [RailsCast #255 - Undo with Paper Trail][3], Feb 28, 2011
 * [RailsCast #255 - Undo with PaperTrail](http://railscasts.com/episodes/255-undo-with-paper-trail),
   28th February 2011.
 * [Keep a Paper Trail with PaperTrail](http://www.linux-mag.com/id/7528),
@@ -1341,7 +1507,6 @@ export DB=sqlite # this is default
 
 Please use GitHub's [issue tracker](http://github.com/airblade/paper_trail/issues).
 
-
 ## Contributors
 
 Many thanks to:
@@ -1405,7 +1570,6 @@ Many thanks to:
 * [Simply Versioned](http://github.com/github/simply_versioned)
 * [Acts As Audited](http://github.com/collectiveidea/acts_as_audited)
 
-
 ## Intellectual Property
 
 Copyright (c) 2011 Andy Stewart (boss@airbladesoftware.com).
@@ -1414,7 +1578,7 @@ Released under the MIT licence.
 [1]: http://api.rubyonrails.org/classes/ActiveRecord/Locking/Optimistic.html
 [2]: https://github.com/airblade/paper_trail/issues/163
 [3]: http://railscasts.com/episodes/255-undo-with-paper-trail
-[4]: https://img.shields.io/travis/airblade/paper_trail/master.svg
+[4]: https://api.travis-ci.org/airblade/paper_trail.svg?branch=master
 [5]: https://travis-ci.org/airblade/paper_trail
 [6]: https://img.shields.io/gemnasium/airblade/paper_trail.svg
 [7]: https://gemnasium.com/airblade/paper_trail
@@ -1443,3 +1607,10 @@ Released under the MIT licence.
 [31]: https://github.com/rails/spring
 [32]: http://api.rubyonrails.org/classes/ActiveRecord/AutosaveAssociation.html#method-i-mark_for_destruction
 [33]: https://github.com/airblade/paper_trail/wiki/Setting-whodunnit-in-the-rails-console
+[34]: https://github.com/rails/rails/blob/591a0bb87fff7583e01156696fbbf929d48d3e54/activerecord/lib/active_record/fixtures.rb#L142
+[35]: https://dev.mysql.com/doc/refman/5.6/en/fractional-seconds.html
+[36]: http://www.postgresql.org/docs/9.4/interactive/ddl.html
+[37]: https://github.com/ankit1910/paper_trail-globalid
+[38]: https://github.com/sferik/rails_admin
+[39]: http://api.rubyonrails.org/classes/ActiveRecord/Base.html#class-ActiveRecord::Base-label-Single+table+inheritance
+[40]: http://api.rubyonrails.org/classes/ActiveRecord/Associations/ClassMethods.html#module-ActiveRecord::Associations::ClassMethods-label-Polymorphic+Associations