paper_trail 3.0.6 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 342a6b8d2c4c6685107d14ae36f6711d7fe09d78
-  data.tar.gz: f7d83394a6bb503a898509b26e9adf0f712c1dfb
+  metadata.gz: e7937d44654d4f77422ffe61d4bc2d81b7ed4026
+  data.tar.gz: 9ec1f8bc013795818775e58e1cd9c33e5dd36499
 SHA512:
-  metadata.gz: d240d05e510adf0a4e178a27cda8e490b99750384a15af935daa6019f02f8ce944c7894fdea76fb970a07dde7bdbbf62de8c314a24f5684f961d8da949fe3b64
-  data.tar.gz: 078716e13039aebf41ea3c10e78180e78d1879ab30095a39298678bb88e6e5659a760f67449cbffee22492419943988df53eac04417fd8da8259804a08fe4732
+  metadata.gz: e546ad5e910cc2a08aeaaf0dca6754e05f3a89fbfb022b49a078025e09a623e359a552c2e52f3126c84662fad2cd804c34db709689211852ff43e32ff40db3a1
+  data.tar.gz: 0ef05118041333567e076bc8407330917cc36ec5d23aec22fd6dced9367b10a466c4284eccddbb3f4d0675c4154165f24097eafe4acf0135e133c426a2b71d4b

data/.gitignore

@@ -12,6 +12,11 @@ pkg/*
 .bundle
 .rbenv-version
 Gemfile.lock
+gemfiles/*.lock
 vendor/*
 .idea
 .rvmrc
+.tags
+.tags_sorted_by_file
+.ruby-version
+.ruby-gemset

data/.rspec

@@ -1,3 +1,2 @@
---format progress
 --color
-
+--require spec_helper

data/.travis.yml

@@ -6,21 +6,28 @@ rvm:
   - jruby-19mode
   - jruby-18mode
 env:
-  - DB=mysql
-  - DB=postgres
-  - DB=sqlite
+  global:
+    - TRAVIS=true
+  matrix:
+    - DB=mysql
+    - DB=postgres
+    - DB=sqlite
+
+sudo: false
 
 before_script:
+  - mysql --version
   - sh -c "if [ \"$DB\" = 'mysql' ]; then mysql   -e 'create database paper_trail_test;'; fi"
   - sh -c "if [ \"$DB\" = 'mysql' ]; then mysql   -e 'create database paper_trail_bar; '; fi"
   - sh -c "if [ \"$DB\" = 'mysql' ]; then mysql   -e 'create database paper_trail_foo; '; fi"
+  - psql --version
   - sh -c "if [ \"$DB\" = 'postgres' ]; then psql -c 'create database paper_trail_test;' -U postgres; fi"
   - sh -c "if [ \"$DB\" = 'postgres' ]; then psql -c 'create database paper_trail_bar;'  -U postgres; fi"
   - sh -c "if [ \"$DB\" = 'postgres' ]; then psql -c 'create database paper_trail_foo;'  -U postgres; fi"
 
 gemfile:
   - Gemfile
-  - gemfiles/3.0.gemfile
+  - gemfiles/ar3.gemfile
 
 matrix:
   fast_finish: true
@@ -29,4 +36,6 @@ matrix:
       gemfile: Gemfile
     - rvm: 1.8.7
       gemfile: Gemfile
-    
+
+addons:
+  postgresql: "9.4"

data/CHANGELOG.md

@@ -1,13 +1,220 @@
+## 4.2.0 (2016-05-31)
+
+### Breaking Changes
+
+- None
+
+### Added
+
+- [#808](https://github.com/airblade/paper_trail/pull/808) -
+  Warn when destroy callback is set to :after with ActiveRecord 5
+  option `belongs_to_required_by_default` set to `true`.
+
+### Fixed
+
+- None
+
+## 4.1.0 (2016-01-30)
+
+### Breaking Changes
+
+- None
+
+### Added
+
+- A way to control the order of AR callbacks.
+  [#614](https://github.com/airblade/paper_trail/pull/614)
+- Added `unversioned_attributes` option to `reify`.
+  [#579](https://github.com/airblade/paper_trail/pull/579)
+
+### Fixed
+
+- None
+
+## 4.0.2
+
+### Breaking Changes
+
+- None
+
+### Added
+
+- None
+
+### Fixed
+
+- [#696](https://github.com/airblade/paper_trail/issues/696) /
+  [#697](https://github.com/airblade/paper_trail/pull/697)
+  Bind JSON query parameters in `where_object` and `where_object_changes`.
+
+## 4.0.1
+
+### Breaking Changes
+
+- None
+
+### Added
+
+- None
+
+### Fixed
+
+- [#636](https://github.com/airblade/paper_trail/issues/636) -
+  Should compile assets without a db connection
+- [#589](https://github.com/airblade/paper_trail/pull/589) /
+  [#588](https://github.com/airblade/paper_trail/issues/588) -
+  Fixes timestamp for "create" versions
+
+## 4.0.0
+
+This major release adds JSON column support in PostgreSQL, limited support for
+versioning associations, various new configuration options, and a year's worth
+of bug fixes. Thanks to everyone who helped test the two betas and two release
+candidates.
+
+### Breaking Changes
+
+- Using a Rails initializer to reopen PaperTrail::Version or otherwise extend
+  PaperTrail is no longer recommended. An alternative is described in the
+  readme. See https://github.com/airblade/paper_trail/pull/557 and
+  https://github.com/airblade/paper_trail/pull/492.
+- If you depend on the `RSpec` or `Cucumber` helpers, you must
+  [require them in your test helper](https://github.com/airblade/paper_trail#testing).
+- [#566](https://github.com/airblade/paper_trail/pull/566) - Removed deprecated
+  methods `paper_trail_on` and `paper_trail_off`. Use `paper_trail_on!` and
+  `paper_trail_off!` instead.
+- [#458](https://github.com/airblade/paper_trail/pull/458) - Version metadata
+  (the `:meta` option) from AR attributes for `create` events will now save the
+  current value instead of `nil`.
+- [#391](https://github.com/airblade/paper_trail/issues/391) - `object_changes`
+  value should dump to `YAML` as a normal `Hash` instead of an
+  `ActiveSupport::HashWithIndifferentAccess`.
+- [#375](https://github.com/airblade/paper_trail/pull/375) /
+  [#374](https://github.com/airblade/paper_trail/issues/374) /
+  [#354](https://github.com/airblade/paper_trail/issues/354) /
+  [#131](https://github.com/airblade/paper_trail/issues/131) -
+  Versions are now saved with an `after_` callback, instead of a `before_`
+  callback. This ensures that the timestamp field for a version matches the
+  corresponding timestamp in the model.
+- `3da1f104` - `PaperTrail.config` and `PaperTrail.configure` are now
+  identical: both return the `PaperTrail::Config` instance and also
+  yield it if a block is provided.
+
+### Added
+
+- [#525](https://github.com/airblade/paper_trail/issues/525) /
+  [#512](https://github.com/airblade/paper_trail/pull/512) -
+  Support for virtual accessors and redefined setter and getter methods.
+- [#518](https://github.com/airblade/paper_trail/pull/518) - Support for
+  querying against PostgreSQL's
+  [`JSON` and `JSONB` column types](http://www.postgresql.org/docs/9.4/static/datatype-json.html)
+  via `PaperTrail::VersionConcern#where_object` and
+  `PaperTrail::VersionConcern#where_object_changes`
+- [#507](https://github.com/airblade/paper_trail/pull/507) -
+  New option: `:save_changes` controls whether or not to save changes to the
+  `object_changes` column (if it exists).
+- [#500](https://github.com/airblade/paper_trail/pull/500) - Support for
+  passing an empty array to the `on` option (`on: []`) to disable all
+  automatic versioning.
+- [#494](https://github.com/airblade/paper_trail/issues/494) - The install
+  generator will warn the user if the migration they are attempting to
+  generate already exists.
+- [#484](https://github.com/airblade/paper_trail/pull/484) - Support for
+  [PostgreSQL's `JSONB` Type](http://www.postgresql.org/docs/9.4/static/datatype-json.html)
+  for storing `object` and `object_changes`.
+- [#439](https://github.com/airblade/paper_trail/pull/439) /
+  [#12](https://github.com/airblade/paper_trail/issues/12) -
+  Support for versioning associations (has many, has one, etc.) one level deep.
+- [#420](https://github.com/airblade/paper_trail/issues/420) - Add
+  `VersionConcern#where_object_changes` instance method; acts as a helper for
+  querying against the `object_changes` column in versions table.
+- [#416](https://github.com/airblade/paper_trail/issues/416) - Added a
+  `config` option for enabling/disabling utilization of
+  `serialized_attributes` for `ActiveRecord`, necessary because
+  `serialized_attributes` has been deprecated in `ActiveRecord` version `4.2`
+  and will be removed in version `5.0`
+- [#399](https://github.com/airblade/paper_trail/pull/399) - Add `:dup`
+  argument for options hash to `reify` which forces a new model instance.
+- [#394](https://github.com/airblade/paper_trail/pull/394) - Add RSpec matcher
+  `have_a_version_with` for easier testing.
+- [#347](https://github.com/airblade/paper_trail/pull/347) - Autoload
+  `ActiveRecord` models in via a `Rails::Engine` when the gem is used with
+  `Rails`.
+
+### Fixed
+
+- [#563](https://github.com/airblade/paper_trail/pull/563) - Fixed a bug in
+  `touch_with_version` so that it will still create a version even when the
+  `on` option is, e.g. `[:create]`.
+- [#541](https://github.com/airblade/paper_trail/pull/541) -
+  `PaperTrail.config.enabled` should be Thread Safe
+- [#451](https://github.com/airblade/paper_trail/issues/451) - Fix `reify`
+  method in context of model where the base class has a default scope, and the
+  live instance is not scoped within that default scope.
+- [#440](https://github.com/airblade/paper_trail/pull/440) - `versions`
+  association should clear/reload after a transaction rollback.
+- [#438](https://github.com/airblade/paper_trail/issues/438) -
+  `ModelKlass.paper_trail_enabled_for_model?` should return `false` if
+  `has_paper_trail` has not been declared on the class.
+- [#404](https://github.com/airblade/paper_trail/issues/404) /
+  [#428](https://github.com/airblade/paper_trail/issues/428) -
+  `model_instance.dup` does not need to be invoked when examining what the
+  instance looked like before changes were persisted, which avoids issues if a
+  3rd party has overriden the `dup` behavior. Also fixes errors occuring when
+  a user attempts to update the inheritance column on an STI model instance in
+  `ActiveRecord` 4.1.x
+- [#427](https://github.com/airblade/paper_trail/pull/427) - Fix `reify`
+  method in context of model where a column has been removed.
+- [#414](https://github.com/airblade/paper_trail/issues/414) - Fix
+  functionality `ignore` argument to `has_paper_trail` in `ActiveRecord` 4.
+- [#413](https://github.com/airblade/paper_trail/issues/413) - Utilize
+  [RequestStore](https://github.com/steveklabnik/request_store) to ensure that
+  the `PaperTrail.whodunnit` is set in a thread safe manner within Rails and
+  Sinatra.
+- [#381](https://github.com/airblade/paper_trail/issues/381) - Fix `irb`
+  warning: `can't alias context from irb_context`. `Rspec` and `Cucumber`
+  helpers should not be loaded by default, regardless of whether those
+  libraries are loaded.
+- [#248](https://github.com/airblade/paper_trail/issues/248) - In MySQL, to
+  prevent truncation, generated migrations now use `longtext` instead of `text`.
+- Methods handling serialized attributes should fallback to the currently set
+  Serializer instead of always falling back to `PaperTrail::Serializers::YAML`.
+
+### Deprecated
+
+- [#479](https://github.com/airblade/paper_trail/issues/479) - Deprecated
+  `originator` method, use `paper_trail_originator`.
+
+## 3.0.9
+
+  - [#479](https://github.com/airblade/paper_trail/issues/479) - Deprecated
+    `originator` method in favor of `paper_trail_originator` Deprecation warning
+    informs users that the `originator` of the methods will be removed in
+    version `4.0`. (Backported from v4)
+  - Updated deprecation warnings for `Model.paper_trail_on` and
+    `Model.paper_trail_off` to have display correct version number the methods
+    will be removed (`4.0`)
+
+## 3.0.8
+
+  - [#525](https://github.com/airblade/paper_trail/issues/525) / [#512](https://github.com/airblade/paper_trail/pull/512) -
+    Support for virtual accessors and redefined setter and getter methods.
+
+## 3.0.7
+
+  - [#404](https://github.com/airblade/paper_trail/issues/404) / [#428](https://github.com/airblade/paper_trail/issues/428) -
+    Fix errors occuring when a user attempts to update the inheritance column on an STI model instance in `ActiveRecord` 4.1.x
+
 ## 3.0.6
 
-  - [#414](https://github.com/airblade/paper_trail/issues/414) - Fix functionality `ignore` argument to `has_paper_trail`
-    in `ActiveRecord` 4.
+  - [#414](https://github.com/airblade/paper_trail/issues/414) - Backport fix for `ignore` argument to `has_paper_trail` in
+    `ActiveRecord` 4.
 
 ## 3.0.5
 
-  - [#401](https://github.com/airblade/paper_trail/issues/401) / [#406](https://github.com/airblade/paper_trail/issues/406)
+  - [#401](https://github.com/airblade/paper_trail/issues/401) / [#406](https://github.com/airblade/paper_trail/issues/406) -
     `PaperTrail::Version` class is not loaded via a `Rails::Engine`, even when the gem is used with in Rails. This feature has
-    will be re-introduced in version `3.1.0`.
+    will be re-introduced in version `4.0`.
   - [#398](https://github.com/airblade/paper_trail/pull/398) - Only require the `RSpec` helper if `RSpec::Core` is required.
 
 ## 3.0.3
@@ -52,7 +259,7 @@ in the `PaperTrail::Version` class through a `Rails::Engine` when the gem is use
     with Rails `4.1.0.rc1`.
   - [#334](https://github.com/airblade/paper_trail/pull/334) - Add small-scope `whodunnit` method to `PaperTrail::Model::InstanceMethods`.
   - [#329](https://github.com/airblade/paper_trail/issues/329) - Add `touch_with_version` method to `PaperTrail::Model::InstanceMethods`,
-    to allow for generating a version `touch`ing a model.
+    to allow for generating a version while `touch`ing a model.
   - [#328](https://github.com/airblade/paper_trail/pull/328) / [#326](https://github.com/airblade/paper_trail/issues/326) /
     [#307](https://github.com/airblade/paper_trail/issues/307) - `Model.paper_trail_enabled_for_model?` and
     `model_instance.without_versioning` is now thread-safe.
@@ -63,8 +270,8 @@ in the `PaperTrail::Version` class through a `Rails::Engine` when the gem is use
   - [#312](https://github.com/airblade/paper_trail/issues/312) - Fix RSpec `with_versioning` class level helper method.
   - `model_instance.without_versioning` now yields the `model_instance`, enabling syntax like this:
     `model_instance.without_versioning { |obj| obj.update_attributes(:name => 'value') }`.
-  - Deprecated `Model.paper_trail_on` and `Model.paper_trail_off` in favor of bang versions of the methods. Deprecation warning
-    informs users that the non-bang versions of the methods will be removed in version `3.1.0`.
+  - Deprecated `Model.paper_trail_on` and `Model.paper_trail_off` in favor of bang versions of the methods.
+    Deprecation warning informs users that the non-bang versions of the methods will be removed in version `4.0`
 
 ## 3.0.0
 
@@ -91,7 +298,7 @@ in the `PaperTrail::Version` class through a `Rails::Engine` when the gem is use
   - [#216](https://github.com/airblade/paper_trail/pull/216) - Added helper & extension for [RSpec](https://github.com/rspec/rspec),
     and helper for [Cucumber](http://cukes.info).
   - [#212](https://github.com/airblade/paper_trail/pull/212) - Added `PaperTrail::Cleaner` module, useful for discarding draft versions.
-  - [#207](https://github.com/airblade/paper_trail/issues/207) - Versions for `'create'` events are now created with `create!` instead of 
+  - [#207](https://github.com/airblade/paper_trail/issues/207) - Versions for `'create'` events are now created with `create!` instead of
     `create` so that an exception gets raised if it is appropriate to do so.
   - [#199](https://github.com/airblade/paper_trail/pull/199) - Rails 4 compatibility.
   - [#165](https://github.com/airblade/paper_trail/pull/165) - Namespaced the `Version` class under the `PaperTrail` module.

data/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing
+
+Thanks for your interest in PaperTrail!
+
+Ask usage questions on Stack Overflow:
+http://stackoverflow.com/tags/papertrail
+
+**Please do not use github issues to ask usage questions.**
+
+On github, we appreciate bug reports, feature
+suggestions, and especially pull requests.
+
+Thanks, and happy (paper) trails :)
+
+## Reporting Bugs
+
+Please use our [bug report template][1].
+
+## Development
+
+Testing is a little awkward because the test suite:
+
+1. contains a rails app with three databases (test, foo, and bar)
+1. supports three different RDBMS': sqlite, mysql, and postgres
+
+Run tests with sqlite:
+
+```
+# Create the appropriate database config. file
+rm test/dummy/config/database.yml
+DB=sqlite bundle exec rake prepare
+
+# If this is the first test run ever, create databases
+cd test/dummy
+RAILS_ENV=test bundle exec rake db:setup
+RAILS_ENV=foo bundle exec rake db:setup
+RAILS_ENV=bar bundle exec rake db:setup
+cd ../..
+
+# Run tests
+DB=sqlite bundle exec rake
+```
+
+Run tests with mysql:
+
+```
+# Create the appropriate database config. file
+rm test/dummy/config/database.yml
+DB=mysql bundle exec rake prepare
+
+# If this is the first test run ever, create databases
+cd test/dummy
+RAILS_ENV=test bundle exec rake db:setup
+RAILS_ENV=foo bundle exec rake db:setup
+RAILS_ENV=bar bundle exec rake db:setup
+cd ../..
+
+# Run tests
+DB=mysql bundle exec rake
+```
+
+Run tests with postgres:
+
+```
+# Create the appropriate database config. file
+rm test/dummy/config/database.yml
+DB=postgres bundle exec rake prepare
+
+# If this is the first test run ever, create databases.
+# Unlike mysql, use create/migrate instead of setup.
+cd test/dummy
+RAILS_ENV=test bundle exec rake db:create
+RAILS_ENV=test bundle exec rake db:migrate
+RAILS_ENV=foo bundle exec rake db:create
+RAILS_ENV=foo bundle exec rake db:migrate
+RAILS_ENV=bar bundle exec rake db:create
+RAILS_ENV=bar bundle exec rake db:migrate
+cd ../..
+
+# Run tests
+DB=postgres bundle exec rake
+```
+
+[1]: https://github.com/airblade/paper_trail/blob/master/doc/bug_report_template.rb

data/README.md

@@ -1,99 +1,136 @@
-# PaperTrail [![Build Status](https://travis-ci.org/airblade/paper_trail.svg?branch=3.0-stable)](https://travis-ci.org/airblade/paper_trail) [![Dependency Status](https://img.shields.io/gemnasium/airblade/paper_trail.svg)](https://gemnasium.com/airblade/paper_trail)
-
-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.
-
-There's an excellent [RailsCast on implementing Undo with Paper Trail](http://railscasts.com/episodes/255-undo-with-paper-trail).
-
-## 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` 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.
-
+# 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 |
+| -------------- | ------------- |
+| 4              | https://github.com/airblade/paper_trail/blob/4-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
+
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [API Summary](#api-summary)
+- Limiting What is Versioned, and When
+  - [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)
+  - [Turning PaperTrail Off/On](#turning-papertrail-offon)
+  - [Limiting the Number of Versions Created](#limiting-the-number-of-versions-created)
+- Working With Versions
+  - [Reverting And Undeleting A Model](#reverting-and-undeleting-a-model)
+  - [Navigating Versions](#navigating-versions)
+  - [Diffing Versions](#diffing-versions)
+  - [Deleting Old Versions](#deleting-old-versions)
+- Saving More Information About Versions
+  - [Finding Out Who Was Responsible For A Change](#finding-out-who-was-responsible-for-a-change)
+  - [Associations](#associations)
+  - [Storing metadata](#storing-metadata)
+- Extensibility
+  - [Custom Version Classes](#custom-version-classes)
+  - [Custom Serializer](#using-a-custom-serializer)
+- [SerializedAttributes support](#serializedattributes-support)
+- [Testing](#testing)
+- [Sinatra](#sinatra)
 
 ## Compatibility
 
-Works with ActiveRecord 4 and ActiveRecord 3. Note: this code is on the `master` branch and tagged `v3.x`.
-
-Version 2 is on the branch named [`2.7-stable`](https://github.com/airblade/paper_trail/tree/2.7-stable) and is tagged `v2.x`, and works with Rails 3.
-
-The Rails 2.3 code is on the [`rails2`](https://github.com/airblade/paper_trail/tree/rails2) 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.
+| paper_trail | branch     | tags   | ruby     | activerecord |
+| ----------- | ---------- | ------ | -------- | ------------ |
+| 4           | 4-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  |
 
 ## Installation
 
-### Rails 3 & 4
-
 1. Add PaperTrail to your `Gemfile`.
 
-    `gem 'paper_trail', '~> 3.0.6'`
+    `gem 'paper_trail', '~> 4.2.0'`
 
-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`
-
-3. Run the migration.
-
-    `bundle exec rake db:migrate`
+    ```
+    bundle exec rails generate paper_trail:install
+    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
-
-In order to configure PaperTrail for usage with [Sinatra](http://www.sinatrarb.com),
-your `Sinatra` app must be using `ActiveRecord` 3 or 4. It is also recommended to use the
-[Sinatra ActiveRecord Extension](https://github.com/janko-m/sinatra-activerecord) 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:
+## Basic Usage
 
-1. Add PaperTrail to your `Gemfile`.
+Add `has_paper_trail` to your model to record every `create`, `update`,
+and `destroy`.
 
-    `gem 'paper_trail', '~> 3.0.6'`
+```ruby
+class Widget < ActiveRecord::Base
+  has_paper_trail
+end
+```
 
-2. Generate a migration to add a `versions` table to your database.
+This gives you 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](https://raw.github.com/airblade/paper_trail/master/lib/generators/paper_trail/templates/create_versions.rb)
-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`](http://www.sinatrarb.com/intro.html#Modular%20vs.%20Classic%20Style) 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
 
@@ -101,21 +138,23 @@ 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.
 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.
-widget.originator
+widget.paper_trail_originator
 
 # Returns the widget (not a version) as it looked at the given timestamp.
 widget.version_at(timestamp)
@@ -126,7 +165,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.
@@ -135,8 +175,10 @@ Widget.paper_trail_off!
 # Turn PaperTrail on for all widgets.
 Widget.paper_trail_on!
 
-# Check wheter PaperTrail is enabled for all widgets
+# Is PaperTrail enabled for Widget, the class?
 Widget.paper_trail_enabled_for_model?
+
+# Is PaperTrail enabled for widget, the instance?
 widget.paper_trail_enabled_for_model?
 ```
 
@@ -146,8 +188,11 @@ And a `PaperTrail::Version` instance has these methods:
 # Returns the item restored from this version.
 version.reify(options = {})
 
+# Return a new item from this version
+version.reify(dup: true)
+
 # Returns who put the item into the state stored in this version.
-version.originator
+version.paper_trail_originator
 
 # Returns who changed the item from the state it had in this version.
 version.terminator
@@ -165,6 +210,15 @@ version.index
 
 # Returns the event that caused this version (create|update|destroy).
 version.event
+
+# Query versions objects by attributes.
+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)
 ```
 
 In your controllers you can override these methods:
@@ -179,110 +233,70 @@ user_for_paper_trail
 info_for_paper_trail
 ```
 
-## Basic Usage
+## Choosing Lifecycle Events To Monitor
 
-PaperTrail is simple to use.  Just add 15 characters to a model to get a paper trail of every `create`, `update`, and `destroy`.
+You can choose which events to track with the `on` option.  For example, to
+ignore `create` events:
 
 ```ruby
-class Widget < ActiveRecord::Base
-  has_paper_trail
+class Article < ActiveRecord::Base
+  has_paper_trail :on => [:update, :destroy]
 end
 ```
 
-This gives you a `versions` method which returns the paper trail of changes to your model.
+`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.
 
-```ruby
->> widget = Widget.find 42
->> widget.versions             # [<PaperTrail::Version>, <PaperTrail::Version>, ...]
-```
-
-Once you have a version, you can find out what happened:
+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
+attempt to use to fill the `event` field before falling back on one of the
+default events.
 
 ```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
+a = Article.create
+a.versions.size                           # 1
+a.versions.last.event                     # 'create'
+a.paper_trail_event = 'update title'
+a.update_attributes :title => 'My Title'
+a.versions.size                           # 2
+a.versions.last.event                     # 'update title'
+a.paper_trail_event = nil
+a.update_attributes :title => "Alternate"
+a.versions.size                           # 3
+a.versions.last.event                     # 'update'
 ```
 
-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.
+### Controlling the Order of AR Callbacks
 
-
-## Choosing Lifecycle Events To Monitor
-
-You can choose which events to track with the `on` option.  For example, to ignore `create` events:
+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
-  has_paper_trail :on => [:update, :destroy]
-end
-```
 
-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 attempt to use to fill the `event` field before
-falling back on one of the default events.
+  # Include PaperTrail, but do not add any callbacks yet. Passing the
+  # empty array to `:on` omits callbacks.
+  has_paper_trail :on => []
 
-```ruby
->> a = Article.create
->> a.versions.size                           # 1
->> a.versions.last.event                     # 'create'
->> a.paper_trail_event = 'update title'
->> a.update_attributes :title => 'My Title'
->> a.versions.size                           # 2
->> a.versions.last.event                     # 'update title'
->> a.paper_trail_event = nil
->> a.update_attributes :title => "Alternate"
->> a.versions.size                           # 3
->> a.versions.last.event                     # 'update'
+  # 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)
+
 ## 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 translations:
+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
+translations:
 
 ```ruby
 class Translation < ActiveRecord::Base
@@ -302,16 +316,19 @@ class Article < ActiveRecord::Base
 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 `PaperTrail::Version` to be created.  For example:
+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
+`PaperTrail::Version` to be created.  For example:
 
 ```ruby
->> a = Article.create
->> a.versions.length                         # 1
->> a.update_attributes :title => 'My Title', :rating => 3
->> a.versions.length                         # 1
->> a.update_attributes :title => 'Greeting', :content => 'Hello'
->> a.versions.length                         # 2
->> a.previous_version.title                  # 'My Title'
+a = Article.create
+a.versions.length                         # 1
+a.update_attributes :title => 'My Title', :rating => 3
+a.versions.length                         # 1
+a.update_attributes :title => 'Greeting', :content => 'Hello'
+a.versions.length                         # 2
+a.previous_version.title                  # 'My Title'
 ```
 
 Or, you can specify a list of all attributes you care about:
@@ -325,13 +342,13 @@ end
 This means that only changes to the `title` will save a version of the article:
 
 ```ruby
->> a = Article.create
->> a.versions.length                         # 1
->> a.update_attributes :title => 'My Title'
->> a.versions.length                         # 2
->> a.update_attributes :content => 'Hello'
->> a.versions.length                         # 2
->> a.previous_version.content                # nil
+a = Article.create
+a.versions.length                         # 1
+a.update_attributes :title => 'My Title'
+a.versions.length                         # 2
+a.update_attributes :content => 'Hello'
+a.versions.length                         # 2
+a.previous_version.content                # nil
 ```
 
 The `:ignore` and `:only` options can also accept `Hash` arguments, where the :
@@ -342,26 +359,31 @@ class Article < ActiveRecord::Base
 end
 ```
 
-This means that if the `title` is not blank, then only changes to the `title` will save a version of the article:
+This means that if the `title` is not blank, then only changes to the `title`
+will save a version of the article:
 
 ```ruby
->> a = Article.create
->> a.versions.length                         # 1
->> a.update_attributes :content => 'Hello'
->> a.versions.length                         # 2
->> a.update_attributes :title => 'My Title'
->> a.versions.length                         # 3
->> a.update_attributes :content => 'Hai'
->> a.versions.length                         # 3
->> a.previous_version.content                # "Hello"
->> a.update_attributes :title => 'Dif Title'
->> a.versions.length                         # 4
->> a.previous_version.content                # "Hai"
+a = Article.create
+a.versions.length                         # 1
+a.update_attributes :content => 'Hello'
+a.versions.length                         # 2
+a.update_attributes :title => 'My Title'
+a.versions.length                         # 3
+a.update_attributes :content => 'Hai'
+a.versions.length                         # 3
+a.previous_version.content                # "Hello"
+a.update_attributes :title => 'Dif Title'
+a.versions.length                         # 4
+a.previous_version.content                # "Hai"
 ```
 
-Passing both `:ignore` and `:only` options will result in the article being saved if a changed attribute is included in `:only` but not in `:ignore`.
+Passing both `:ignore` and `:only` options will result in the article being
+saved if a changed attribute is included in `:only` but not in `:ignore`.
 
-You can skip fields altogether with the `:skip` option.  As with `:ignore`, updates to these fields will not create a new `PaperTrail::Version`.  In addition, these fields will not be included in the serialized version of the object whenever a new `PaperTrail::Version` is created.
+You can skip fields altogether with the `:skip` option.  As with `:ignore`,
+updates to these fields will not create a new `PaperTrail::Version`.  In
+addition, these fields will not be included in the serialized version of the
+object whenever a new `PaperTrail::Version` is created.
 
 For example:
 
@@ -371,226 +393,384 @@ class Article < ActiveRecord::Base
 end
 ```
 
-## Reverting And Undeleting A Model
+## Turning PaperTrail Off/On
 
-PaperTrail makes reverting to a previous version easy:
+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.
+
+You can turn PaperTrail on or off in three ways: globally, per request, or per
+class.
+
+### Globally
+
+On a global level you can turn PaperTrail off like this:
 
 ```ruby
->> widget = Widget.find 42
->> widget.update_attributes :name => 'Blah blah'
-# Time passes....
->> widget = widget.previous_version  # the widget as it was before the update
->> widget.save                       # reverted
+PaperTrail.enabled = false
 ```
 
-Alternatively you can find the version at a given time:
+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)):
 
 ```ruby
->> widget = widget.version_at(1.day.ago)  # the widget as it was one day ago
->> widget.save                            # reverted
+# in config/environments/test.rb
+config.after_initialize do
+  PaperTrail.enabled = false
+end
 ```
 
-Note `version_at` gives you the object, not a version, so you don't need to call `reify`.
-
-Undeleting is just as simple:
+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:
 
 ```ruby
->> widget = Widget.find 42
->> widget.destroy
-# Time passes....
->> widget = PaperTrail::Version.find(153).reify  # the widget as it was before destruction
->> widget.save                         # the widget lives!
+# 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
 ```
 
-In fact you could use PaperTrail to implement an undo system, though I haven't had the opportunity yet to do it myself.  However [Ryan Bates has](http://railscasts.com/episodes/255-undo-with-paper-trail)!
+And then use it in your tests like this:
 
+```ruby
+test "something that needs versioning" do
+  with_versioning do
+    # your test
+  end
+end
+```
 
-## Navigating Versions
+### Per request
 
-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.
+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`:
 
 ```ruby
->> live_widget = Widget.find 42
->> live_widget.versions.length           # 4 for example
->> widget = live_widget.previous_version # => widget == live_widget.versions.last.reify
->> widget = widget.previous_version      # => widget == live_widget.versions[-2].reify
->> widget = widget.next_version          # => widget == live_widget.versions.last.reify
->> widget.next_version                   # live_widget
+class ApplicationController < ActionController::Base
+  def paper_trail_enabled_for_controller
+    request.user_agent != 'Disable User-Agent'
+  end
+end
 ```
 
-If instead you have a particular `version` of an item you can navigate to the previous and next versions.
+### Per class
+
+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:
 
 ```ruby
->> widget = Widget.find 42
->> version = widget.versions[-2]    # assuming widget has several versions
->> previous = version.previous
->> next = version.next
+Widget.paper_trail_off!
 ```
 
-You can find out which of an item's versions yours is:
+And on again like this:
 
 ```ruby
->> current_version_number = version.index    # 0-based
+Widget.paper_trail_on!
 ```
 
-Finally, if you got an item by reifying one of its versions, you can navigate back to the version it came from:
+### 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:
 
 ```ruby
->> latest_version = Widget.find(42).versions.last
->> widget = latest_version.reify
->> widget.version == latest_version    # true
+@widget.without_versioning :destroy
 ```
 
-You can find out whether a model instance is the current, live one -- or whether it came instead from a previous version -- with `live?`:
+Or a block:
 
 ```ruby
->> widget = Widget.find 42
->> widget.live?                        # true
->> widget = widget.previous_version
->> widget.live?                        # false
+@widget.without_versioning do
+  @widget.update_attributes :name => 'Ford'
+end
 ```
 
-## Finding Out Who Was Responsible For A Change
+## Limiting the Number of Versions Created
 
-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 of type `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:
+Configure `version_limit` to cap the number of versions saved per record. This
+does not apply to `create` events.
 
 ```ruby
->> last_change = widget.versions.last
->> user_who_made_the_change = User.find last_change.whodunnit.to_i
+# 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
 ```
 
-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:
+## Reverting And Undeleting A Model
+
+PaperTrail makes reverting to a previous version easy:
 
 ```ruby
-class ApplicationController
-  def user_for_paper_trail
-    logged_in? ? current_member.id : 'Public user'  # or whatever
-  end
-end
+widget = Widget.find 42
+widget.update_attributes :name => 'Blah blah'
+# Time passes....
+widget = widget.previous_version  # the widget as it was before the update
+widget.save                       # reverted
 ```
 
-In a console session you can manually set who is responsible like this:
+Alternatively you can find the version at a given time:
 
 ```ruby
->> PaperTrail.whodunnit = 'Andy Stewart'
->> widget.update_attributes :name => 'Wibble'
->> widget.versions.last.whodunnit              # Andy Stewart
+widget = widget.version_at(1.day.ago)  # the widget as it was one day ago
+widget.save                            # reverted
 ```
 
-You can avoid having to do this manually by setting your initializer to pick up the username of the current user from the OS, like this:
+Note `version_at` gives you the object, not a version, so you don't need to call
+`reify`.
+
+Undeleting is just as simple:
 
 ```ruby
-# config/initializers/paper_trail.rb
-if defined?(::Rails::Console)
-  PaperTrail.whodunnit = "#{`whoami`.strip}: console"
-elsif File.basename($0) == "rake"
-  PaperTrail.whodunnit = "#{`whoami`.strip}: rake #{ARGV.join ' '}"
-end
+widget = Widget.find 42
+widget.destroy
+# Time passes....
+widget = PaperTrail::Version.find(153).reify  # the widget as it was before destruction
+widget.save                         # the widget lives!
 ```
 
-Sometimes you want to define who is responsible for a change in a small scope without overwriting value of `PaperTrail.whodunnit`. It is possible to define the `whodunnit` value for an operation inside a block like this:
+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
+
+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.
 
 ```ruby
->> PaperTrail.whodunnit = 'Andy Stewart'
->> widget.whodunnit('Lucas Souza') do
->>   widget.update_attributes :name => 'Wibble'
->> end
->> widget.versions.last.whodunnit              # Lucas Souza
->> widget.update_attributes :name => 'Clair'
->> widget.versions.last.whodunnit              # Andy Stewart
->> widget.whodunnit('Ben Atkins') { |w| w.update_attributes :name => 'Beth' } # this syntax also works
->> widget.versions.last.whodunnit              # Ben Atkins
+live_widget = Widget.find 42
+live_widget.versions.length           # 4 for example
+widget = live_widget.previous_version # => widget == live_widget.versions.last.reify
+widget = widget.previous_version      # => widget == live_widget.versions[-2].reify
+widget = widget.next_version          # => widget == live_widget.versions.last.reify
+widget.next_version                   # live_widget
 ```
 
-A version's `whodunnit` records who changed the object causing the `version` to be stored.  Because a version stores the object as it looked before the change (see the table above), `whodunnit` returns who stopped the object looking like this -- not who made it look like this.  Hence `whodunnit` is aliased as `terminator`.
+If instead you have a particular `version` of an item you can navigate to the
+previous and next versions.
 
-To find out who made a version's object look that way, use `version.originator`.  And to find out who made a "live" object look like it does, use `originator` on the object.
+```ruby
+widget = Widget.find 42
+version = widget.versions[-2]    # assuming widget has several versions
+previous = version.previous
+next = version.next
+```
+
+You can find out which of an item's versions yours is:
 
 ```ruby
->> widget = Widget.find 153                    # assume widget has 0 versions
->> PaperTrail.whodunnit = 'Alice'
->> widget.update_attributes :name => 'Yankee'
->> widget.originator                           # 'Alice'
->> PaperTrail.whodunnit = 'Bob'
->> widget.update_attributes :name => 'Zulu'
->> widget.originator                           # 'Bob'
->> first_version, last_version = widget.versions.first, widget.versions.last
->> first_version.whodunnit                     # 'Alice'
->> first_version.originator                    # nil
->> first_version.terminator                    # 'Alice'
->> last_version.whodunnit                      # 'Bob'
->> last_version.originator                     # 'Alice'
->> last_version.terminator                     # 'Bob'
+current_version_number = version.index    # 0-based
 ```
 
-## Custom Version Classes
+If you got an item by reifying one of its versions, you can navigate back to the
+version it came from:
 
-You can specify custom version subclasses with the `:class_name` option:
+```ruby
+latest_version = Widget.find(42).versions.last
+widget = latest_version.reify
+widget.version == latest_version    # true
+```
+
+You can find out whether a model instance is the current, live one -- or whether
+it came instead from a previous version -- with `live?`:
 
 ```ruby
-class PostVersion < PaperTrail::Version
-  # custom behaviour, e.g:
-  self.table_name = :post_versions
-end
+widget = Widget.find 42
+widget.live?                        # true
+widget = widget.previous_version
+widget.live?                        # false
+```
 
-class Post < ActiveRecord::Base
-  has_paper_trail :class_name => 'PostVersion'
-end
+And you can perform `WHERE` queries for object versions based on attributes:
+
+```ruby
+# All versions that meet these criteria.
+PaperTrail::Version.where_object(content: "Hello", title: "Article")
 ```
 
-This allows you to store each model's versions in a separate table, which is useful if you have a lot of versions being created.
+## Diffing Versions
+
+There are two scenarios: diffing adjacent versions and diffing non-adjacent
+versions.
+
+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
+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:
 
-If you are using Postgres, you should also define the sequence that your custom version class will use:
+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.
+
+## 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
-class PostVersion < PaperTrail::Version
-  self.table_name = :post_versions
-  self.sequence_name = :post_version_id_seq
-end
+PaperTrail::Version.delete_all ["created_at < ?", 1.week.ago]
 ```
 
-Alternatively you could store certain metadata for one type of version, and other metadata for other versions.
+## Finding Out Who Was Responsible For A Change
 
-If you only use custom version classes and don't use PaperTrail's built-in one, on Rails `>= 3.2` you must:
+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.
 
-- either declare the `PaperTrail::Version` class to be abstract like this (in an initializer):
+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:
 
 ```ruby
-PaperTrail::Version.module_eval do
-  self.abstract_class = true
+class ApplicationController
+  def user_for_paper_trail
+    logged_in? ? current_member.id : 'Public user'  # or whatever
+  end
 end
 ```
 
-- or create a `versions` table in the database so Rails can instantiate the `PaperTrail::Version` superclass.
-
-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:
+In a console session you can manually set who is responsible like this:
 
 ```ruby
-class Post < ActiveRecord::Base
-  has_paper_trail :versions => :paper_trail_versions,
-                  :version  => :paper_trail_version
+PaperTrail.whodunnit = 'Andy Stewart'
+widget.update_attributes :name => 'Wibble'
+widget.versions.last.whodunnit              # Andy Stewart
+```
 
-  # Existing versions method.  We don't want to clash.
-  def versions
-    ...
-  end
-  # Existing version method.  We don't want to clash.
-  def version
-    ...
-  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
+without overwriting value of `PaperTrail.whodunnit`. It is possible to define
+the `whodunnit` value for an operation inside a block like this:
+
+```ruby
+PaperTrail.whodunnit = 'Andy Stewart'
+widget.whodunnit('Lucas Souza') do
+  widget.update_attributes :name => 'Wibble'
 end
+widget.versions.last.whodunnit              # Lucas Souza
+widget.update_attributes :name => 'Clair'
+widget.versions.last.whodunnit              # Andy Stewart
+widget.whodunnit('Ben Atkins') { |w| w.update_attributes :name => 'Beth' } # this syntax also works
+widget.versions.last.whodunnit              # Ben Atkins
+```
+
+A version's `whodunnit` records who changed the object causing the `version` to
+be stored.  Because a version stores the object as it looked before the change
+(see the table above), `whodunnit` returns who stopped the object looking like
+this -- not who made it look like this.  Hence `whodunnit` is aliased as
+`terminator`.
+
+To find out who made a version's object look that way, use
+`version.paper_trail_originator`.  And to find out who made a "live" object look
+like it does, call `paper_trail_originator` on the object.
+
+```ruby
+widget = Widget.find 153                    # assume widget has 0 versions
+PaperTrail.whodunnit = 'Alice'
+widget.update_attributes :name => 'Yankee'
+widget.paper_trail_originator               # 'Alice'
+PaperTrail.whodunnit = 'Bob'
+widget.update_attributes :name => 'Zulu'
+widget.paper_trail_originator               # 'Bob'
+first_version, last_version = widget.versions.first, widget.versions.last
+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'
 ```
 
 ## Associations
 
-I haven't yet found a good way to get PaperTrail to automatically restore associations when you reify a model.  See [here for a little more info](http://airbladesoftware.com/notes/undo-and-redo-with-papertrail).
-
-If you can think of a good way to achieve this, please let me know.
-
+**Experimental feature**, see caveats below.
 
-## Has-One Associations
+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
+`version_associations` table, either at installation time with the `rails
+generate paper_trail:install --with-associations` option or manually. PaperTrail
+will store in that table additional information to correlate versions of the
+association and versions of the model when the associated record is changed.
+When reifying the model, PaperTrail can use this table, together with the
+`transaction_id` to find the correct version of the association and reify it.
+The `transaction_id` is a unique id for version records created in the same
+transaction. It is used to associate the version of the model and the version of
+the association that are created in the same transaction.
 
-PaperTrail can restore `:has_one` associations as they were at (actually, 3 seconds before) the time.
+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:
 
 ```ruby
 class Location < ActiveRecord::Base
@@ -603,32 +783,90 @@ class Treasure < ActiveRecord::Base
   has_paper_trail
 end
 
->> treasure.amount                  # 100
->> treasure.location.latitude       # 12.345
+treasure.amount                  # 100
+treasure.location.latitude       # 12.345
 
->> treasure.update_attributes :amount => 153
->> treasure.location.update_attributes :latitude => 54.321
+treasure.update_attributes :amount => 153
+treasure.location.update_attributes :latitude => 54.321
 
->> t = treasure.versions.last.reify(:has_one => true)
->> t.amount                         # 100
->> t.location.latitude              # 12.345
+t = treasure.versions.last.reify(:has_one => true)
+t.amount                         # 100
+t.location.latitude              # 12.345
 ```
 
-The implementation is complicated by the edge case where the parent and child are updated in one go, e.g. in one web request or database transaction.  PaperTrail doesn't know about different models being updated "together", so you can't ask it definitively to get the child as it was before the joint parent-and-child update.
-
-The correct solution is to make PaperTrail aware of requests or transactions (c.f. [Efficiency's transaction ID middleware](http://github.com/efficiency20/ops_middleware/blob/master/lib/e20/ops/middleware/transaction_id_middleware.rb)).  In the meantime we work around the problem by finding the child as it was a few seconds before the parent was updated.  By default we go 3 seconds before but you can change this by passing the desired number of seconds to the `:has_one` option:
+If the parent and child are updated in one go, PaperTrail can use the
+aforementioned `transaction_id` to reify the models as they were before the
+transaction (instead of before the update to the model).
 
 ```ruby
->> t = treasure.versions.last.reify(:has_one => 1)  # look back 1 second instead of 3
-```
+treasure.amount                  # 100
+treasure.location.latitude       # 12.345
+
+Treasure.transaction do
+treasure.location.update_attributes :latitude => 54.321
+treasure.update_attributes :amount => 153
+end
 
-If you are shuddering, take solace from knowing PaperTrail opts out of these shenanigans by default. This means your `:has_one` associated objects will be the live ones, not the ones the user saw at the time.  Since PaperTrail doesn't auto-restore `:has_many` associations (I can't get it to work) or `:belongs_to` (I ran out of time looking at `:has_many`), this at least makes your associations wrong consistently ;)
+t = treasure.versions.last.reify(:has_one => true)
+t.amount                         # 100
+t.location.latitude              # 12.345, instead of 54.321
+```
 
+By default, PaperTrail excludes an associated record from the reified parent
+model if the associated record exists in the live model but did not exist as at
+the time the version was created. This is usually what you want if you just want
+to look at the reified version. But if you want to persist it, it would be
+better to pass in option `:mark_for_destruction => true` so that the associated
+record is included and marked for destruction. Note that `mark_for_destruction`
+only has [an effect on associations marked with `autosave: true`][32].
 
+```ruby
+class Widget < ActiveRecord::Base
+  has_paper_trail
+  has_one :wotsit, autosave: true
+end
 
-## Has-Many-Through Associations
+class Wotsit < ActiveRecord::Base
+  has_paper_trail
+  belongs_to :widget
+end
 
-PaperTrail can track most changes to the join table.  Specifically it can track all additions but it can only track removals which fire the `after_destroy` callback on the join table.  Here are some examples:
+widget = Widget.create(:name => 'widget_0')
+widget.update_attributes(:name => 'widget_1')
+widget.create_wotsit(:name => 'wotsit')
+
+widget_0 = widget.versions.last.reify(:has_one => true)
+widget_0.wotsit                                  # nil
+
+widget_0 = widget.versions.last.reify(:has_one => true, :mark_for_destruction => true)
+widget_0.wotsit.marked_for_destruction?          # true
+widget_0.save!
+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)
+1. Currently PaperTrail only support 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.
+1. PaperTrail only reifies the first level of associations, i.e., it does not
+   reify any associations of its associations, and so on.
+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
+   examples:
 
 Given these models:
 
@@ -655,21 +893,23 @@ end
 Then each of the following will store authorship versions:
 
 ```ruby
->> @book.authors << @dostoyevsky
->> @book.authors.create :name => 'Tolstoy'
->> @book.authorships.last.destroy
->> @book.authorships.clear
+@book.authors << @dostoyevsky
+@book.authors.create :name => 'Tolstoy'
+@book.authorships.last.destroy
+@book.authorships.clear
+@book.author_ids = [@solzhenistyn.id, @dostoyevsky.id]
 ```
 
 But none of these will:
 
 ```ruby
->> @book.authors.delete @tolstoy
->> @book.author_ids = [@solzhenistyn.id, @dostoyevsky.id]
->> @book.authors = []
+@book.authors.delete @tolstoy
+@book.author_ids = []
+@book.authors = []
 ```
 
-Having said that, you can apparently get all these working (I haven't tested it myself) with this patch:
+Having said that, you can apparently get all these working (I haven't tested it
+myself) with this patch:
 
 ```ruby
 # In config/initializers/active_record_patch.rb
@@ -688,13 +928,9 @@ module ActiveRecord
 end
 ```
 
-See [issue 113](https://github.com/airblade/paper_trail/issues/113) for a discussion about this.
-
-There may be a way to store authorship versions, probably using association callbacks, no matter how the collection is manipulated but I haven't found it yet.  Let me know if you do.
+See [issue 113][16] for a discussion about this.
 
-There has been some discussion of how to implement PaperTrail to fully track HABTM associations. See [pull 90](https://github.com/airblade/paper_trail/pull/90) for an implementation that has worked for some.
-
-## Storing metadata
+## Storing Metadata
 
 You can store arbitrary model-level metadata alongside each version like this:
 
@@ -710,33 +946,29 @@ class Article < ActiveRecord::Base
 end
 ```
 
-PaperTrail will call your proc with the current article and store the result in the `author_id` column of the `versions` table.
-
-N.B.  You must also:
+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.
 
-* Add your metadata columns to the `versions` table.
-* Declare your metadata columns using `attr_accessible`. (If you are using `ActiveRecord 3`, or `ActiveRecord 4` with the [ProtectedAttributes](https://github.com/rails/protected_attributes) gem)
+### Advantages of Metadata
 
-For example:
-
-```ruby
-# config/initializers/paper_trail.rb
-module PaperTrail
-  class Version < ActiveRecord::Base
-    attr_accessible :author_id, :word_count, :answer
-  end
-end
-```
-
-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 `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:
+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
+`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:
 
 ```ruby
 PaperTrail::Version.where(:author_id => author_id)
 ```
 
-Note you can pass a symbol as a value in the `meta` hash to signal a method to call.
+### Metadata from Controllers
 
-You can also store any information you like from your controller.  Just override the `info_for_paper_trail` method in your controller to return a hash whose keys correspond to columns in your `versions` table.  E.g.:
+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
+correspond to columns in your `versions` table.
 
 ```ruby
 class ApplicationController
@@ -746,215 +978,271 @@ class ApplicationController
 end
 ```
 
-Remember to add those extra columns to your `versions` table and use `attr_accessible` ;)
-
-**NOTE FOR RAILS 4:** If you're using [Strong Parameters](https://github.com/rails/strong_parameters) in Rails 4 and have *not* included the `protected_attributes` gem, there's no need to declare your metadata columns using `attr_accessible`.
+### Protected Attributes and Metadata
 
-
-## Diffing Versions
-
-There are two scenarios: diffing adjacent versions and diffing non-adjacent versions.
-
-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:
+If you are using rails 3 or the [protected_attributes][17] gem you must declare
+your metadata columns to be `attr_accessible`.
 
 ```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                # {}
+# app/models/paper_trail/version.rb
+module PaperTrail
+  class Version < ActiveRecord::Base
+    include PaperTrail::VersionConcern
+    attr_accessible :author_id, :word_count, :answer
+  end
+end
 ```
 
-Note PaperTrail only stores the changes for creation and updates; it doesn't store anything when an object is destroyed.
+If you're using [strong_parameters][18] instead of [protected_attributes][17]
+then there is no need to use `attr_accessible`.
 
-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:
+## Custom Version Classes
 
-* [htmldiff](http://github.com/myobie/htmldiff): 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](http://github.com/pvande/differ): 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](https://github.com/halostatue/diff-lcs): old-school, line-wise diffs.
+You can specify custom version subclasses with the `:class_name` option:
 
-For diffing two ActiveRecord objects:
+```ruby
+class PostVersion < PaperTrail::Version
+  # custom behaviour, e.g:
+  self.table_name = :post_versions
+end
 
-* [Jeremy Weiskotten's PaperTrail fork](http://github.com/jeremyw/paper_trail/blob/master/lib/paper_trail/has_paper_trail.rb#L151-156): uses ActiveSupport's diff to return an array of hashes of the changes.
-* [activerecord-diff](http://github.com/tim/activerecord-diff): rather like ActiveRecord::Dirty but also allows you to specify which columns to compare.
+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`).
 
-## Turning PaperTrail Off/On
+### Advantages
 
-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.
+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.
 
-You can turn PaperTrail on or off in three ways: globally, per request, or per class.
+### Configuration
 
-### Globally
-
-On a global level 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
->> PaperTrail.enabled = false
+class PostVersion < PaperTrail::Version
+  self.table_name = :post_versions
+  self.sequence_name = :post_versions_id_seq
+end
 ```
 
-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)):
+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
-# in config/environments/test.rb
-config.after_initialize do
-  PaperTrail.enabled = false
+# app/models/paper_trail/version.rb
+module PaperTrail
+  class Version < ActiveRecord::Base
+    include PaperTrail::VersionConcern
+    self.abstract_class = true
+  end
 end
 ```
 
-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 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
-# 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
+class Post < ActiveRecord::Base
+  has_paper_trail :versions => :paper_trail_versions,
+                  :version  => :paper_trail_version
+
+  # 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
 ```
 
-And then use it in your tests like this:
+## Custom Serializer
+
+By default, PaperTrail stores your changes as a `YAML` dump. You can override
+this with the serializer config option:
 
 ```ruby
-test "something that needs versioning" do
-  with_versioning do
-    # your test
-  end
-end
+PaperTrail.serializer = MyCustomSerializer
 ```
 
-### Per request
+A valid serializer is a `module` (or `class`) that defines a `load` and `dump`
+method.  These serializers are included in the gem for your convenience:
+
+* [PaperTrail::Serializers::YAML][24] - Default
+* [PaperTrail::Serializers::JSON][25]
 
-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`:
+### 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
+`json` instead of `text` for these columns in your migration:
 
 ```ruby
-class ApplicationController < ActionController::Base
-  def paper_trail_enabled_for_controller
-    request.user_agent != 'Disable User-Agent'
-  end
+create_table :versions do |t|
+  ...
+  t.json :object          # Full object changes
+  t.json :object_changes  # Optional column-level changes
+  ...
 end
 ```
 
-### Per class
+If you use the PostgreSQL `json` or `jsonb` column type, you do not need
+to specify a `PaperTrail.serializer`.
+
+#### Convert existing YAML data to JSON
 
-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:
+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
->> Widget.paper_trail_off!
-```
+add_column :versions, :object, :new_object, :jsonb # or :json
 
-And on again like this:
+PaperTrail::Version.reset_column_information
+PaperTrail::Version.find_each do |version|
+  version.update_column :new_object, YAML.load(version.object)
+end
 
-```ruby
->> Widget.paper_trail_on!
+remove_column :versions, :object
+rename_column :versions, :new_object, :object
 ```
 
-### Per method call
+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.
 
-You can call a method without creating a new version using `without_versioning`.  It takes either a method name as a symbol:
+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 a converting
+the data.
 
 ```ruby
-@widget.without_versioning :destroy
+rename_column :versions, :object, :old_object
+add_column :versions, :object, :jsonb # or :json
 ```
 
-Or a block:
+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.
 
 ```ruby
-@widget.without_versioning do
-  @widget.update_attributes :name => 'Ford'
+PaperTrail::Version.where.not(old_object: nil).find_each do |version|
+  version.update_columns old_object: nil, object: YAML.load(version.old_object)
 end
 ```
 
-## Using a custom serializer
-
-By default, PaperTrail stores your changes as a `YAML` dump. You can override this with the serializer config option:
+Finally, in another migration, remove the old column.
 
 ```ruby
->> PaperTrail.serializer = MyCustomSerializer
+remove_column :versions, :old_object
 ```
 
-A valid serializer is a `module` (or `class`) that defines a `load` and `dump` method.  These serializers are included in the gem for your convenience:
-
-* [YAML](https://github.com/airblade/paper_trail/blob/master/lib/paper_trail/serializers/yaml.rb) - Default
-* [JSON](https://github.com/airblade/paper_trail/blob/master/lib/paper_trail/serializers/json.rb)
+If you use the optional `object_changes` column, don't forget to convert it
+also, using the same technique.
 
-## Limiting the number of versions created per object instance
+#### Convert a Column from Text to JSON
 
-If you are wary of your `versions` table growing to an unwieldy size, or just don't care to track more than a certain number of versions per object,
-there is a configuration option that can be set to cap the number of versions saved per object. Note that this value must be numeric, and it only applies to
-versions other than `create` events (which will always be preserved if they are stored).
-
-```ruby
-# will make it so that a maximum of 4 versions will be stored for each object
-# (the 3 most recent ones plus a `create` event)
->> PaperTrail.config.version_limit = 3
-# disables/removes the version limit
->> PaperTrail.config.version_limit = nil
-```
-
-## Deleting Old Versions
+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.
 
-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:
+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
 
-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 the [Turning
+PaperTrail Off/On](#turning-papertrail-offon) section above for tips on usage
+with `Test::Unit`.
 
 ### RSpec
 
-PaperTrail provides a helper that works with [RSpec](https://github.com/rspec/rspec) to make it easier to control when `PaperTrail` is enabled
-during testing. By default, PaperTrail will be turned off for all tests.
-When you wish 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:
+PaperTrail provides a helper that works with [RSpec][27] to make it easier to
+control when `PaperTrail` is enabled during testing.
+
+If you wish to use the helper, you will need to require it in your RSpec test
+helper like so:
+
+```ruby
+# spec/rails_helper.rb
+
+ENV["RAILS_ENV"] ||= 'test'
+require 'spec_helper'
+require File.expand_path("../../config/environment", __FILE__)
+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
+test in a `with_versioning` block, or pass in `:versioning => true` option to a
+spec block, like so:
 
 ```ruby
 describe "RSpec test group" do
   it 'by default, PaperTrail will be turned off' do
-    PaperTrail.should_not be_enabled
+    expect(PaperTrail).to_not be_enabled
   end
 
   with_versioning do
     it 'within a `with_versioning` block it will be turned on' do
-      PaperTrail.should be_enabled
+      expect(PaperTrail).to be_enabled
     end
   end
 
   it 'can be turned on at the `it` or `describe` level like this', :versioning => true do
-    PaperTrail.should be_enabled
+    expect(PaperTrail).to be_enabled
   end
 end
 ```
 
-The helper will also reset the `PaperTrail.whodunnit` value to `nil` before each 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.
+The helper will also reset the `PaperTrail.whodunnit` value to `nil` before each
+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.
 
-There is also a `be_versioned` matcher provided by PaperTrail's RSpec helper which can be leveraged like so:
+There is also a `be_versioned` matcher provided by PaperTrail's RSpec helper
+which can be leveraged like so:
 
 ```ruby
 class Widget < ActiveRecord::Base
 end
 
 describe Widget do
-  it { should_not be_versioned }
+  it "is not versioned by default" do
+    is_expected.to_not be_versioned
+  end
 
   describe "add versioning to the `Widget` class" do
     before(:all) do
@@ -963,16 +1251,52 @@ describe Widget do
       end
     end
 
-    it { should be_versioned }
+    it "enables paper trail" do
+      is_expected.to be_versioned
+    end
   end
 end
 ```
 
+It is also possible to do assertions on the versions using `have_a_version_with`
+matcher
+
+```
+ describe '`have_a_version_with` matcher' do
+    before do
+      widget.update_attributes!(:name => 'Leonard', :an_integer => 1 )
+      widget.update_attributes!(:name => 'Tom')
+      widget.update_attributes!(:name => 'Bob')
+    end
+
+    it "is possible to do assertions on versions" do
+       expect(widget).to have_a_version_with :name => 'Leonard', :an_integer => 1
+       expect(widget).to have_a_version_with :an_integer => 1
+       expect(widget).to have_a_version_with :name => 'Tom'
+    end
+  end
+
+```
+
 ### Cucumber
 
-PaperTrail provides a helper for [Cucumber](http://cukes.info) that works similar to the RSpec helper.
-By default, PaperTrail will be turned off for all scenarios by a `before` hook added by the helper.
-When you wish to enable PaperTrail for a scenario, you can wrap code in a `with_versioning` block in a step, like so:
+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
+helper like so:
+
+```ruby
+# features/support/env.rb
+
+ENV["RAILS_ENV"] ||= "cucumber"
+require File.expand_path(File.dirname(__FILE__) + '/../../config/environment')
+...
+require 'paper_trail/frameworks/cucumber'
+```
+
+When the helper is loaded, PaperTrail will be turned off for all scenarios by a
+`before` hook added by the helper by default. When you wish to enable PaperTrail
+for a scenario, you can wrap code in a `with_versioning` block in a step, like
+so:
 
 ```ruby
 Given /I want versioning on my model/ do
@@ -982,25 +1306,28 @@ Given /I want versioning on my model/ do
 end
 ```
 
-The helper will also reset the `PaperTrail.whodunnit` value to `nil` before each 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.
+The helper will also reset the `PaperTrail.whodunnit` value to `nil` before each
+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
 
-If you wish to use the `RSpec` or `Cucumber` helpers with [Spork](https://github.com/sporkrb/spork), you will need to
-manually require the helper(s) in your `prefork` block on your test helper, like so:
+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
+helper, like so:
 
 ```ruby
-# spec/spec_helper.rb
+# spec/rails_helper.rb
 
 require 'spork'
 
 Spork.prefork do
   # This file is copied to spec/ when you run 'rails generate rspec:install'
   ENV["RAILS_ENV"] ||= 'test'
+  require 'spec_helper'
   require File.expand_path("../../config/environment", __FILE__)
   require 'rspec/rails'
-  require 'rspec/autorun'
   require 'paper_trail/frameworks/rspec'
   require 'paper_trail/frameworks/cucumber'
   ...
@@ -1009,13 +1336,15 @@ end
 
 ### Zeus or Spring
 
-If you wish to use the `RSpec` or `Cucumber` helpers with [Zeus](https://github.com/burke/zeus) or [Spring](https://github.com/rails/spring), you will need to
-manually require the helper(s) in your test helper, like so:
+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
+helper, like so:
 
 ```ruby
-# spec/spec_helper.rb
+# spec/rails_helper.rb
 
 ENV["RAILS_ENV"] ||= 'test'
+require 'spec_helper'
 require File.expand_path("../../config/environment", __FILE__)
 require 'rspec/rails'
 require 'paper_trail/frameworks/rspec'
@@ -1023,9 +1352,13 @@ require 'paper_trail/frameworks/rspec'
 
 ## Testing PaperTrail
 
-Paper Trail has facilities to test aganist 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. 
+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 against.
 
-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.  
+Though be aware we do not have the ability 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.
 
 ```
 export DB=postgres
@@ -1033,19 +1366,70 @@ export DB=mysql
 export DB=sqlite # this is default
 ```
 
-## Articles
+## Sinatra
+
+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. Add PaperTrail to your `Gemfile`.
+
+    `gem 'paper_trail', '~> 4.2.0'`
 
-* [Versioning with PaperTrail](http://www.sitepoint.com/versioning-papertrail), [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 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), Linux Magazine, 16th September 2009.
+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
+
+* [Jutsu #8 - Version your RoR models with PaperTrail](http://samurails.com/gems/papertrail/),
+  [Thibault](http://samurails.com/about-me/), 29th September 2014
+* [Versioning with PaperTrail](http://www.sitepoint.com/versioning-papertrail),
+  [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),
+  Linux Magazine, 16th September 2009.
 
 ## Problems
 
 Please use GitHub's [issue tracker](http://github.com/airblade/paper_trail/issues).
 
-
 ## Contributors
 
 Many thanks to:
@@ -1101,15 +1485,51 @@ Many thanks to:
 * [Chulki Lee](https://github.com/chulkilee)
 * [Lucas Souza](https://github.com/lucasas)
 * [Russell Osborne](https://github.com/rposborne)
-
+* [Ben Li](https://github.com/bli)
+* [Felix Liu](https://github.com/lyfeyaj)
 
 ## Inspirations
 
 * [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).
 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://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
+[9]: https://github.com/airblade/paper_trail/tree/3.0-stable
+[10]: https://github.com/airblade/paper_trail/tree/2.7-stable
+[11]: https://github.com/airblade/paper_trail/tree/rails2
+[12]: http://www.sinatrarb.com
+[13]: https://github.com/janko-m/sinatra-activerecord
+[14]: https://raw.github.com/airblade/paper_trail/master/lib/generators/paper_trail/templates/create_versions.rb
+[15]: http://www.sinatrarb.com/intro.html#Modular%20vs.%20Classic%20Style
+[16]: https://github.com/airblade/paper_trail/issues/113
+[17]: https://github.com/rails/protected_attributes
+[18]: https://github.com/rails/strong_parameters
+[19]: http://github.com/myobie/htmldiff
+[20]: http://github.com/pvande/differ
+[21]: https://github.com/halostatue/diff-lcs
+[22]: http://github.com/jeremyw/paper_trail/blob/master/lib/paper_trail/has_paper_trail.rb#L151-156
+[23]: http://github.com/tim/activerecord-diff
+[24]: https://github.com/airblade/paper_trail/blob/master/lib/paper_trail/serializers/yaml.rb
+[25]: https://github.com/airblade/paper_trail/blob/master/lib/paper_trail/serializers/json.rb
+[26]: http://www.postgresql.org/docs/9.4/static/datatype-json.html
+[27]: https://github.com/rspec/rspec
+[28]: http://cukes.info
+[29]: https://github.com/sporkrb/spork
+[30]: https://github.com/burke/zeus
+[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