paper_trail 3.0.9 → 4.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: de205e84196241d1165f38050f43114114b47cca
-  data.tar.gz: 2401292c3098d9050260528490556294f8034a6d
+  metadata.gz: 5a4a5a1bfd11ee6bc8acabb03cb262fe4691951a
+  data.tar.gz: 6854403b0c404645e52c94154d4d8268642969c1
 SHA512:
-  metadata.gz: 89b14153e1f66e8e043532c78a6cda7033e2aa902c9d191fddc29ece1a4036c9808c26e345ca3360d4c70f6d1193eac14eb5884025a45750361419e290217d2f
-  data.tar.gz: 531199dd212d76562c9baed8033fd3ca765b5458b19c3b8029e89c8cd3f7a44202cdcb5efd3ad979022c5e4386e47e042fab2617470134a52d3ee6b328779f65
+  metadata.gz: 891aa4e3758245d09974c472c49506a4b49b2ac565018acc1afbebe40907c91729b450e45dd9e5c501c6781f7a673f15f9d3f0b43a3fbfe65fbe9a0db079a24d
+  data.tar.gz: c0ae097eaa91467cd5bc5d944aa65ba9cd43899d8498725c900c6a96bcd8c332a8fedd0610f0c092a5df444e500c4a72119ee3de29df92d5748c4990c2f86282

data/.gitignore

@@ -15,3 +15,5 @@ Gemfile.lock
 vendor/*
 .idea
 .rvmrc
+.tags
+.tags_sorted_by_file

data/.rspec

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

data/.travis.yml

@@ -10,6 +10,8 @@ env:
   - DB=postgres
   - DB=sqlite
 
+sudo: false
+
 before_script:
   - 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"
@@ -25,6 +27,9 @@ gemfile:
 matrix:
   fast_finish: true
   allow_failures:
+    - rvm: jruby-19mode
+      env: DB=postgres
+      gemfile: Gemfile
     - rvm: jruby-18mode
       gemfile: Gemfile
     - rvm: 1.8.7

data/CHANGELOG.md

@@ -1,30 +1,44 @@
-## 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. (Backported from v4)
-
-## 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.
-    (Backported from v4)
+## 4.0.0 (Unreleased)
+
+##### Breaking change: if you use a custom initializer for PaperTrail in conjunction with Rails, you will need to add this line of code to the beginning of it:
+```ruby
+PaperTrail::Rails::Engine.eager_load!
+```
+
+  - [#439](https://github.com/airblade/paper_trail/pull/439) / [#12](https://github.com/airblade/paper_trail/issues/12) -
+    Support for versioning of associations (Has Many, Has One, HABTM, etc.)
+  - [#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) - `Model.paper_trail_enabled_for_model?` should return `false` if
+    `has_paper_trail` has not been declared on the class.
+  - [#427](https://github.com/airblade/paper_trail/pull/427) - Fix `reify` method in context of model where a column has been removed.
+  - [#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`
+  - [#414](https://github.com/airblade/paper_trail/issues/414) - Fix functionality `ignore` argument to `has_paper_trail`
+    in `ActiveRecord` 4.
+  - [#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.
+  - [#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`.
+  - [#381](https://github.com/airblade/paper_trail/issues/381) - `Rspec` and `Cucumber` helpers should not be loaded by
+    default, regardless of whether those libraries are loaded.
+  - [#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 should be built with `after_` callbacks so the timestamp field for a version can be forced to match the
+    corresponding timestamp in the database for the state persistence of a change to the base (versioned) model.
+  - [#347](https://github.com/airblade/paper_trail/pull/347) - Autoload `ActiveRecord` models in via a `Rails::Engine` when
+    the gem is used with `Rails`.
+  - Methods handling serialized attributes should fallback to the currently set Serializer instead of always falling back
+    to `PaperTrail::Serializers::YAML`.
 
 ## 3.0.6
 
-  - [#414](https://github.com/airblade/paper_trail/issues/414) - Fix functionality `ignore` argument to `has_paper_trail`
-    in `ActiveRecord` 4. (Backported from v4)
+  - [#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 `4.0`.
   - [#398](https://github.com/airblade/paper_trail/pull/398) - Only require the `RSpec` helper if `RSpec::Core` is required.
@@ -39,7 +53,7 @@ in the `PaperTrail::Version` class through a `Rails::Engine` when the gem is use
   - [#383](https://github.com/airblade/paper_trail/pull/383) - Make gem compatible with `ActiveRecord::Enum` (available in `ActiveRecord` 4.1+).
   - [#380](https://github.com/airblade/paper_trail/pull/380) / [#377](https://github.com/airblade/paper_trail/issues/377) -
     Add `VersionConcern#where_object` instance method; acts as a helper for querying against the `object` column in versions table.
-  - [#373](https://github.com/airblade/paper_trail/pull/373) - Fix default sort order for the `versions` association in `ActiveRecord` 4.1+
+  - [#373](https://github.com/airblade/paper_trail/pull/373) - Fix default sort order for the `versions` association in `ActiveRecord` 4.1.
   - [#372](https://github.com/airblade/paper_trail/pull/372) - Use [Arel](https://github.com/rails/arel) for SQL construction.
   - [#365](https://github.com/airblade/paper_trail/issues/365) - `VersionConcern#version_at` should return `nil` when receiving a timestamp
     that occured after the object was destroyed.
@@ -71,7 +85,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 while `touch`ing a model.
+    to allow for generating a version `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.

data/README.md

@@ -1,4 +1,4 @@
-# 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 [![Build Status](https://img.shields.io/travis/airblade/paper_trail/master.svg)](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.
 
@@ -12,7 +12,7 @@ There's an excellent [RailsCast on implementing Undo with Paper Trail](http://ra
 * 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.
+* Option to automatically restore `has_one`, `has_many` and `has_many :through` associations as they were at the time.
 * Automatically records who was responsible via your controller.  PaperTrail calls `current_user` by default, if it exists, but you can have it call any method you like.
 * Allows you to set who is responsible at model-level (useful for migrations).
 * Allows you to store arbitrary model-level metadata with each version (useful for filtering versions).
@@ -30,7 +30,9 @@ There's an excellent [RailsCast on implementing Undo with Paper Trail](http://ra
 
 ## Compatibility
 
-Works with ActiveRecord 4 and ActiveRecord 3. Note: this code is on the `master` branch and tagged `v3.x`.
+Works with `ActiveRecord` 3+. Note: this code is on the `master` branch and tagged `v4.x`.
+
+Version 3 is on the branch named [`3.0-stable`](https://github.com/airblade/paper_trail/tree/3.0-stable) and is tagged `v3.x`, and works ActiveRecord 4 and ActiveRecord 3.
 
 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.
 
@@ -42,7 +44,7 @@ The Rails 2.3 code is on the [`rails2`](https://github.com/airblade/paper_trail/
 
 1. Add PaperTrail to your `Gemfile`.
 
-    `gem 'paper_trail', '~> 3.0.9'`
+    `gem 'paper_trail', '~> 3.0.6'`
 
 2. Generate a migration which will add a `versions` table to your database.
 
@@ -64,7 +66,7 @@ your applications `ActiveRecord` connection in a manner similar to the way `Rail
 
 1. Add PaperTrail to your `Gemfile`.
 
-    `gem 'paper_trail', '~> 3.0.9'`
+    `gem 'paper_trail', '~> 3.0.6'`
 
 2. Generate a migration to add a `versions` table to your database.
 
@@ -115,7 +117,7 @@ widget.version
 widget.live?
 
 # Returns who put the widget into its current state.
-widget.paper_trail_originator
+widget.originator
 
 # Returns the widget (not a version) as it looked at the given timestamp.
 widget.version_at(timestamp)
@@ -135,7 +137,7 @@ Widget.paper_trail_off!
 # Turn PaperTrail on for all widgets.
 Widget.paper_trail_on!
 
-# Check wheter PaperTrail is enabled for all widgets
+# Check whether PaperTrail is enabled for all widgets.
 Widget.paper_trail_enabled_for_model?
 widget.paper_trail_enabled_for_model?
 ```
@@ -146,8 +148,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.paper_trail_originator
+version.originator
 
 # Returns who changed the item from the state it had in this version.
 version.terminator
@@ -165,6 +170,9 @@ 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)
 ```
 
 In your controllers you can override these methods:
@@ -241,7 +249,7 @@ Here's a helpful table showing what PaperTrail stores:
   <tr>
     <td>update</td>
     <td>widget</td>
-    <td>widget'</td>
+    <td>widget</td>
   <tr>
     <td>destroy</td>
     <td>widget</td>
@@ -433,7 +441,7 @@ You can find out which of an item's versions yours is:
 >> current_version_number = version.index    # 0-based
 ```
 
-Finally, if you got an item by reifying one of its versions, you can navigate back to the version it came from:
+If you got an item by reifying one of its versions, you can navigate back to the version it came from:
 
 ```ruby
 >> latest_version = Widget.find(42).versions.last
@@ -450,6 +458,13 @@ You can find out whether a model instance is the current, live one -- or whether
 >> widget.live?                        # false
 ```
 
+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")
+```
+
 ## Finding Out Who Was Responsible For A Change
 
 If your `ApplicationController` has a `current_user` method, PaperTrail will store the value it returns in the version's `whodunnit` column.  Note that this column is 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:
@@ -481,6 +496,10 @@ You can avoid having to do this manually by setting your initializer to pick up
 
 ```ruby
 # config/initializers/paper_trail.rb
+
+# the following line is required for PaperTrail >= 4.0.0 with Rails
+PaperTrail::Rails::Engine.eager_load!
+
 if defined?(::Rails::Console)
   PaperTrail.whodunnit = "#{`whoami`.strip}: console"
 elsif File.basename($0) == "rake"
@@ -504,22 +523,22 @@ Sometimes you want to define who is responsible for a change in a small scope wi
 
 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.
+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 153                    # assume widget has 0 versions
 >> PaperTrail.whodunnit = 'Alice'
 >> widget.update_attributes :name => 'Yankee'
->> widget..paper_trail_originator              # 'Alice'
+>> widget.originator                           # 'Alice'
 >> PaperTrail.whodunnit = 'Bob'
 >> widget.update_attributes :name => 'Zulu'
->> widget.paper_trail_originator               # 'Bob'
+>> widget.originator                           # 'Bob'
 >> first_version, last_version = widget.versions.first, widget.versions.last
 >> first_version.whodunnit                     # 'Alice'
->> first_version.paper_trail_originator        # nil
+>> first_version.originator                    # nil
 >> first_version.terminator                    # 'Alice'
 >> last_version.whodunnit                      # 'Bob'
->> last_version.paper_trail_originator         # 'Alice'
+>> last_version.originator                     # 'Alice'
 >> last_version.terminator                     # 'Bob'
 ```
 
@@ -545,7 +564,7 @@ If you are using Postgres, you should also define the sequence that your custom
 ```ruby
 class PostVersion < PaperTrail::Version
   self.table_name = :post_versions
-  self.sequence_name = :post_versions_id_seq
+  self.sequence_name = :post_version_id_seq
 end
 ```
 
@@ -556,6 +575,11 @@ If you only use custom version classes and don't use PaperTrail's built-in one,
 - either declare the `PaperTrail::Version` class to be abstract like this (in an initializer):
 
 ```ruby
+# config/initializers/paper_trail.rb
+
+# the following line is required for PaperTrail >= 4.0.0 with Rails
+PaperTrail::Rails::Engine.eager_load!
+
 PaperTrail::Version.module_eval do
   self.abstract_class = true
 end
@@ -583,14 +607,9 @@ end
 
 ## 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.
-
+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.
 
-## Has-One Associations
-
-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
@@ -614,21 +633,55 @@ end
 >> 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
+
+>> t = treasure.versions.last.reify(:has_one => true)
+>> t.amount                         # 100
+>> t.location.latitude              # 12.345, instead of 54.321
 ```
 
-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 ;)
+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.
+
+```ruby
+class Widget < ActiveRecord::Base
+  has_paper_trail
+  has_one :wotsit, autosave: true
+end
+
+class Wotsit < ActiveRecord::Base
+  has_paper_trail
+  belongs_to :widget
+end
+
+>> 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:**
 
-## Has-Many-Through Associations
+  1. PaperTrail can't restore an association properly if the association record can be updated to replace its parent model (by replacing the foreign key)  
+  2. Currently PaperTrail only support single `version_associations` table. The implication is that you can only use a single table to store the versions for all related models. Sorry for those who use multiple version tables.
+  3. PaperTrail only reifies the first level of associations, i.e., it does not reify any associations of its associations, and so on.
+  4. 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:  
 
-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:
 
 Given these models:
 
@@ -659,13 +712,14 @@ Then each of the following will store authorship versions:
 >> @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.author_ids = []
 >> @book.authors = []
 ```
 
@@ -690,9 +744,6 @@ 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.
-
-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
 
@@ -721,6 +772,10 @@ For example:
 
 ```ruby
 # config/initializers/paper_trail.rb
+
+# the following line is required for PaperTrail >= 4.0.0 with Rails
+PaperTrail::Rails::Engine.eager_load!
+
 module PaperTrail
   class Version < ActiveRecord::Base
     attr_accessible :author_id, :word_count, :answer
@@ -849,7 +904,7 @@ end
 
 ### Per class
 
-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 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.paper_trail_off!
@@ -887,26 +942,26 @@ By default, PaperTrail stores your changes as a `YAML` dump. You can override th
 
 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)
+* [PaperTrail::Serializers::YAML](https://github.com/airblade/paper_trail/blob/master/lib/paper_trail/serializers/yaml.rb) - Default
+* [PaperTrail::Serializers::JSON](https://github.com/airblade/paper_trail/blob/master/lib/paper_trail/serializers/json.rb)
 
-### PostgreSQL JSON column type support
+## SerializedAttributes support
 
-If you use PostgreSQL, and would like to store your `object` (and/or `object_changes`) data in a column of
-[type `JSON`](http://www.postgresql.org/docs/9.4/static/datatype-json.html),
-specify `json` instead of `text` for these columns in your migration:
+PaperTrail has a config option that can be used to enable/disable whether PaperTrail attempts to utilize
+`ActiveRecord`'s `serialized_attributes` feature. Note: This is enabled by default when PaperTrail is used
+with `ActiveRecord` version < `4.2`, and disabled by default when used with ActiveRecord `4.2.x`. Since
+`serialized_attributes` will be removed in `ActiveRecord` version `5.0`, this configuration value
+has no functionality when PaperTrail is used with version `5.0` or greater.
 
 ```ruby
-create_table :versions do |t|
-  ...
-  t.json :object          # Full object changes
-  t.json :object_changes  # Optional column-level changes
-  ...
-end
+# Enable support
+>> PaperTrail.config.serialized_attributes = true
+# Disable support
+>> PaperTrail.config.serialized_attributes = false
+# Get current setting
+>> PaperTrail.serialized_attributes?
 ```
 
-Note: You don't need to use a particular serializer for the PostgreSQL `JSON` column type.
-
 ## Limiting the number of versions created per object instance
 
 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,
@@ -939,24 +994,39 @@ You may want to turn PaperTrail off to speed up your tests.  See the [Turning Pa
 
 ### 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.
+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.
+
+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
 ```
@@ -971,7 +1041,9 @@ 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
@@ -980,15 +1052,47 @@ 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.
+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
@@ -1008,16 +1112,16 @@ If you wish to use the `RSpec` or `Cucumber` helpers with [Spork](https://github
 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'
   ...
@@ -1030,9 +1134,10 @@ If you wish to use the `RSpec` or `Cucumber` helpers with [Zeus](https://github.
 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'
@@ -1040,9 +1145,9 @@ 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 aganist.
 
-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 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.
 
 ```
 export DB=postgres
@@ -1052,6 +1157,7 @@ export DB=sqlite # this is default
 
 ## 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 PaperTrail](http://railscasts.com/episodes/255-undo-with-paper-trail), 28th February 2011.
@@ -1118,7 +1224,8 @@ 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