paper_trail 4.2.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e7937d44654d4f77422ffe61d4bc2d81b7ed4026
-  data.tar.gz: 9ec1f8bc013795818775e58e1cd9c33e5dd36499
+  metadata.gz: a998b8383ac675662fac129fce0617b3c2f13351
+  data.tar.gz: c431eeedc5dec2b6882775a95ea6ef79df63f2a9
 SHA512:
-  metadata.gz: e546ad5e910cc2a08aeaaf0dca6754e05f3a89fbfb022b49a078025e09a623e359a552c2e52f3126c84662fad2cd804c34db709689211852ff43e32ff40db3a1
-  data.tar.gz: 0ef05118041333567e076bc8407330917cc36ec5d23aec22fd6dced9367b10a466c4284eccddbb3f4d0675c4154165f24097eafe4acf0135e133c426a2b71d4b
+  metadata.gz: 1108f2949a0a98f6ad9e7f75eba6b2d40d21209de2beb6c856142930aa58b8f0f7c65fa1cf9fe73dd9fc3b70c22afc8886846581d992eb0ac9934504205db960
+  data.tar.gz: 1db8e0b3427d3801672829e014dcf1035f55ea75fecb54bebbeb5d6d54f0203d57bedce6ed5307fd5dfa8a68ebd971bc16ed4ad923fac4d9a46ff1c9f1aea0e5

data/{CONTRIBUTING.md → .github/CONTRIBUTING.md}

@@ -3,7 +3,7 @@
 Thanks for your interest in PaperTrail!
 
 Ask usage questions on Stack Overflow:
-http://stackoverflow.com/tags/papertrail
+https://stackoverflow.com/tags/paper-trail-gem
 
 **Please do not use github issues to ask usage questions.**
 
@@ -20,8 +20,15 @@ Please use our [bug report template][1].
 
 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
+1. Supports three major versions of rails: 3, 4, 5
+1. Contains a "dummy" rails app with three databases (test, foo, and bar)
+1. Supports three different RDBMS': sqlite, mysql, and postgres
+
+Test against rails 3:
+
+```
+bundle exec appraisal ar3 rake
+```
 
 Run tests with sqlite:
 
@@ -69,16 +76,28 @@ 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
+DB=postgres RAILS_ENV=test bundle exec rake db:create
+DB=postgres RAILS_ENV=test bundle exec rake db:migrate
+DB=postgres RAILS_ENV=foo bundle exec rake db:create
+DB=postgres RAILS_ENV=foo bundle exec rake db:migrate
+DB=postgres RAILS_ENV=bar bundle exec rake db:create
+DB=postgres RAILS_ENV=bar bundle exec rake db:migrate
 cd ../..
 
 # Run tests
 DB=postgres bundle exec rake
 ```
 
+### Releases
+
+1. Set the version in lib/paper_trail/version_number.rb
+  - Set PRE to nil unless it's a pre-release (beta, rc, etc.)
+1. In the changelog, replace "Unreleased" with the date.
+1. In the readme,
+  - remove "unreleased" from the doc versions table
+  - update any other references to version number
+1. Commit and tag with `git tag -a -m "v5.0.0" "v5.0.0"`
+1. `git push --tags origin master`
+1. `gem push paper_trail`
+
 [1]: https://github.com/airblade/paper_trail/blob/master/doc/bug_report_template.rb

data/.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,13 @@
+Thanks for your interest in PaperTrail! Our volunteers' time is limited, so we
+can only respond on GitHub to bug reports and feature requests. Please ask
+*usage questions* on StackOverflow (https://stackoverflow.com/tags/paper-trail-gem)
+so that the whole community has a chance to answer your question.
+
+Please use our template
+(https://github.com/airblade/paper_trail/blob/master/doc/bug_report_template.rb)
+when reporting bugs.
+
+For other questions, please see our contributing guide.
+(https://github.com/airblade/paper_trail/blob/master/.github/CONTRIBUTING.MD)
+
+Thanks for your contribution!

data/.gitignore

@@ -1,3 +1,4 @@
+gemfiles/*.lock
 NOTES
 test/debug.log
 test/paper_trail_plugin.sqlite3.db
@@ -12,7 +13,6 @@ pkg/*
 .bundle
 .rbenv-version
 Gemfile.lock
-gemfiles/*.lock
 vendor/*
 .idea
 .rvmrc
@@ -20,3 +20,4 @@ vendor/*
 .tags_sorted_by_file
 .ruby-version
 .ruby-gemset
+.rbenv-gemsets

data/.rubocop.yml

@@ -0,0 +1,100 @@
+inherit_from: .rubocop_todo.yml
+
+# Please:
+#
+# - Comment any deviations from the Ruby Style Guide
+# - Alphabetize cops
+# - Only include permanent config; temporary goes in .rubocop_todo.yml
+
+# We do not control `schema.rb`. Exclude it from all cops.
+AllCops:
+  Exclude:
+    - test/dummy/db/schema.rb
+
+# Migrations often contain long up/down methods, and extracting smaller methods
+# from these is of questionable value.
+Metrics/AbcSize:
+  Exclude:
+    - 'test/dummy/db/migrate/*'
+
+Metrics/ClassLength:
+  Exclude:
+    - test/**/*
+
+# The Ruby Style Guide recommends to "Limit lines to 80 characters."
+# (https://github.com/bbatsov/ruby-style-guide#80-character-limits)
+# but 100 is also reasonable.
+Metrics/LineLength:
+  Max: 100
+
+# The number of lines in a method is not a useful metric compared to `AbcSize`.
+# It's common to have very long methods (> 50 lines) which are quite simple. For
+# example, a method that returns a long string with only a few interpolations.
+Metrics/MethodLength:
+  Enabled: false
+
+Style/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+
+# Please use semantic style, e.g. `do` when there's a side-effect, else `{}`.
+# The semantic style is too nuanced to lint, so the cop is disabled.
+Style/BlockDelimiters:
+  Enabled: false
+
+Style/DotPosition:
+  EnforcedStyle: trailing
+
+# Use double negation wherever it would otherwise be impractical to convert
+# a value to an actual boolean.
+Style/DoubleNegation:
+  Enabled: false
+
+# The decision of when to use a guard clause to improve readability is subtle,
+# and it's not clear that it can be linted. Certainly, the default
+# `MinBodyLength` of 1 can actually hurt readability.
+Style/GuardClause:
+  MinBodyLength: 3
+
+# Use postfix (modifier) conditionals for one-liners, unless doing so would
+# exceed 60 characters.
+Style/IfUnlessModifier:
+  MaxLineLength: 60
+
+# The Ruby Style Guide says:
+#
+# > Use \ instead of + or << to concatenate two string literals at line end.
+#
+# but in my experience the `\` style is rarely used and less readable. Please
+# concatenate multiline strings with `+` or use a HEREDOC.
+Style/LineEndConcatenation:
+  Enabled: false
+
+# Using `module_function` instead of `extend self` would make the instance
+# methods in these modules private. That would be a breaking change, so these
+# modules are excluded. See discussion in:
+# - https://github.com/airblade/paper_trail/pull/756
+# - https://github.com/bbatsov/ruby-style-guide/issues/556
+Style/ModuleFunction:
+  Exclude:
+    - 'lib/paper_trail/serializers/json.rb'
+    - 'lib/paper_trail/serializers/yaml.rb'
+
+Style/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Style/MultilineOperationIndentation:
+  EnforcedStyle: indented
+
+Style/PredicateName:
+  NameWhitelist: has_paper_trail
+
+# The Ruby Style Guide does not prescribe a particular quote character, only
+# that a project should pick one and be consistent. The decision has no
+# performance implications. Double quotes are slightly easier to read.
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+# Use exactly one space on each side of an operator. Do not align operators
+# because it makes the code harder to edit, and makes lines unnecessarily long.
+Style/SpaceAroundOperators:
+  AllowForAlignment: false

data/.rubocop_todo.yml

@@ -0,0 +1,14 @@
+# Remove these configuration records
+# one by one as the offenses are removed from the code base.
+
+Metrics/AbcSize:
+  Max: 30 # Goal: 15
+
+Metrics/CyclomaticComplexity:
+  Max: 13 # Goal: 6
+
+Metrics/ModuleLength:
+  Max: 299
+
+Metrics/PerceivedComplexity:
+  Max: 16 # Goal: 7

data/.travis.yml

@@ -1,10 +1,8 @@
 language: ruby
 rvm:
-  - 2.0.0
+  - 2.3.0
   - 1.9.3
-  - 1.8.7
   - jruby-19mode
-  - jruby-18mode
 env:
   global:
     - TRAVIS=true
@@ -26,16 +24,17 @@ before_script:
   - sh -c "if [ \"$DB\" = 'postgres' ]; then psql -c 'create database paper_trail_foo;'  -U postgres; fi"
 
 gemfile:
-  - Gemfile
   - gemfiles/ar3.gemfile
+  - gemfiles/ar4.gemfile
+  - gemfiles/ar5.gemfile
 
 matrix:
   fast_finish: true
-  allow_failures:
-    - rvm: jruby-18mode
-      gemfile: Gemfile
-    - rvm: 1.8.7
-      gemfile: Gemfile
+  exclude:
+    - gemfile: gemfiles/ar5.gemfile
+      rvm: 1.9.3
+    - gemfile: gemfiles/ar5.gemfile
+      rvm: jruby-19mode
 
 addons:
   postgresql: "9.4"

data/Appraisals

@@ -0,0 +1,41 @@
+# Specify here only version constraints that differ from
+# `paper_trail.gemspec`.
+#
+# > The dependencies in your Appraisals file are combined with dependencies in
+# > your Gemfile, so you don"t need to repeat anything that"s the same for each
+# > appraisal. If something is specified in both the Gemfile and an appraisal,
+# > the version from the appraisal takes precedence.
+# > https://github.com/thoughtbot/appraisal
+
+appraise "ar3" do
+  gem "activerecord", "~> 3.2.22"
+  gem "i18n", "~> 0.6.11"
+  gem "request_store", "~> 1.1.0"
+
+  group :development, :test do
+    gem 'railties', '~> 3.2.22'
+    gem 'test-unit', '~> 3.1.5'
+    platforms :ruby do
+      gem 'mysql2', '~> 0.3.20'
+    end
+  end
+end
+
+appraise "ar4" do
+  gem "activerecord", "~> 4.2"
+end
+
+appraise "ar5" do
+  gem "activerecord", "5.0.0.beta1"
+  gem "activemodel", "5.0.0.beta1"
+  gem "actionpack", "5.0.0.beta1"
+  gem "railties", "5.0.0.beta1"
+  gem "rspec-rails", github: "rspec/rspec-rails"
+  gem "rspec-core", github: "rspec/rspec-core"
+  gem "rspec-expectations", github: "rspec/rspec-expectations"
+  gem "rspec-mocks", github: "rspec/rspec-mocks"
+  gem "rspec-support", github: "rspec/rspec-support"
+  gem 'rails-controller-testing'
+  # Sinatra stable conflicts with AR5's rack dependency
+  gem 'sinatra', github: 'sinatra/sinatra'
+end

data/CHANGELOG.md

@@ -1,18 +1,58 @@
-## 4.2.0 (2016-05-31)
+## 5.0.0 (2016-05-02)
 
 ### Breaking Changes
 
-- None
+- [#758](https://github.com/airblade/paper_trail/pull/758) -
+  `PaperTrail.config.track_associations` getter method removed,
+  use `track_associations?` instead.
+- [#740](https://github.com/airblade/paper_trail/issues/740) -
+  `PaperTrail.config.track_associations?` now defaults to false
+- [#723](https://github.com/airblade/paper_trail/pull/723) -
+  `PaperTrail.enabled=` now affects all threads
+- [#556](https://github.com/airblade/paper_trail/pull/556) /
+  [#301](https://github.com/airblade/paper_trail/issues/301) -
+  If you are tracking who is responsible for changes with `whodunnit`, be aware
+  that PaperTrail no longer adds the `set_paper_trail_whodunnit` before_filter
+  for you. Please add this before_filter to your ApplicationController to
+  continue recording whodunnit. See the readme for an example.
+- [#683](https://github.com/airblade/paper_trail/pull/683) /
+  [#682](https://github.com/airblade/paper_trail/issues/682) -
+  Destroy callback default changed to :before to accommodate ActiveRecord 5
+  option `belongs_to_required_by_default` and new Rails 5 default.
 
 ### 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`.
+- [#771](https://github.com/airblade/paper_trail/pull/771) -
+  Added support for has_and_belongs_to_many associations
+- [#741](https://github.com/airblade/paper_trail/issues/741) /
+  [#681](https://github.com/airblade/paper_trail/pull/681)
+  MySQL unicode support in migration generator
+- [#689](https://github.com/airblade/paper_trail/pull/689) -
+  Rails 5 compatibility
+- Added a rails config option: `config.paper_trail.enabled`
+- [#503](https://github.com/airblade/paper_trail/pull/730) -
+  Support for reifying belongs_to associations.
 
 ### Fixed
 
-- None
+- [#777](https://github.com/airblade/paper_trail/issues/777) -
+  Support HMT associations with `:source` option.
+- [#738](https://github.com/airblade/paper_trail/issues/738) -
+  Rare bug where a non-versioned STI parent caused `changeset` to
+  return an empty hash.
+- [#731](https://github.com/airblade/paper_trail/pull/731) -
+  Map enums to database values before storing in `object_changes` column.
+- [#715](https://github.com/airblade/paper_trail/issues/715) -
+  Optimize post-rollback association reset.
+- [#701](https://github.com/airblade/paper_trail/pull/701) /
+  [#699](https://github.com/airblade/paper_trail/issues/699) -
+  Cleaning old versions explicitly preserves the most recent
+  versions instead of relying on database result ordering.
+- [#635](https://github.com/airblade/paper_trail/issues/635) -
+  A bug where it was not possible to disable PT when using a multi-threaded
+  webserver.
+- [#584](https://github.com/airblade/paper_trail/issues/584) -
+  Fixed deprecation warning for Active Record after_callback / after_commit
 
 ## 4.1.0 (2016-01-30)
 
@@ -31,7 +71,7 @@
 
 - None
 
-## 4.0.2
+## 4.0.2 (2016-01-19)
 
 ### Breaking Changes
 
@@ -47,7 +87,7 @@
   [#697](https://github.com/airblade/paper_trail/pull/697)
   Bind JSON query parameters in `where_object` and `where_object_changes`.
 
-## 4.0.1
+## 4.0.1 (2015-12-14)
 
 ### Breaking Changes
 
@@ -65,7 +105,7 @@
   [#588](https://github.com/airblade/paper_trail/issues/588) -
   Fixes timestamp for "create" versions
 
-## 4.0.0
+## 4.0.0 (2015-07-30)
 
 This major release adds JSON column support in PostgreSQL, limited support for
 versioning associations, various new configuration options, and a year's worth

data/Gemfile

@@ -1,2 +1,2 @@
-source 'https://rubygems.org'
+source "https://rubygems.org"
 gemspec

data/README.md

@@ -10,7 +10,9 @@ has been destroyed.
 
 | Version        | Documentation |
 | -------------- | ------------- |
-| 4              | https://github.com/airblade/paper_trail/blob/4-stable/README.md   |
+| 5              | https://github.com/airblade/paper_trail/blob/master/README.md |
+| 4.1            | https://github.com/airblade/paper_trail/blob/4.1-stable/README.md |
+| 4.0            | https://github.com/airblade/paper_trail/blob/4.0-stable/README.md |
 | 3              | https://github.com/airblade/paper_trail/blob/3.0-stable/README.md |
 | 2              | https://github.com/airblade/paper_trail/blob/2.7-stable/README.md |
 | 1              | https://github.com/airblade/paper_trail/blob/rails2/README.md |
@@ -25,7 +27,7 @@ has been destroyed.
   - [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)
+  - [Turning PaperTrail Off](#turning-papertrail-off)
   - [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)
@@ -38,25 +40,25 @@ has been destroyed.
   - [Storing metadata](#storing-metadata)
 - Extensibility
   - [Custom Version Classes](#custom-version-classes)
-  - [Custom Serializer](#using-a-custom-serializer)
-- [SerializedAttributes support](#serializedattributes-support)
+  - [Custom Serializer](#custom-serializer)
 - [Testing](#testing)
 - [Sinatra](#sinatra)
 
 ## Compatibility
 
-| 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  |
+| paper_trail    | branch     | tags   | ruby     | activerecord |
+| -------------- | ---------- | ------ | -------- | ------------ |
+| 5              | master     | v5.x   | >= 1.9.3 | >= 3.0, < 6  |
+| 4              | 4.0-stable | v4.x   | >= 1.8.7 | >= 3.0, < 6  |
+| 3              | 3.0-stable | v3.x   | >= 1.8.7 | >= 3.0, < 5  |
+| 2              | 2.7-stable | v2.x   | >= 1.8.7 | >= 3.0, < 4  |
+| 1              | rails2     | v1.x   | >= 1.8.7 | >= 2.3, < 3  |
 
 ## Installation
 
 1. Add PaperTrail to your `Gemfile`.
 
-    `gem 'paper_trail', '~> 4.2.0'`
+    `gem 'paper_trail'`
 
 1. Add a `versions` table to your database.
 
@@ -65,21 +67,31 @@ has been destroyed.
     bundle exec rake db:migrate
     ```
 
+    If using [rails_admin][38], you must enable the experimental
+    [Associations](#associations) feature.
+
 1. Add `has_paper_trail` to the models you want to track.
 
-## Basic Usage
+    ```ruby
+    class Widget < ActiveRecord::Base
+      has_paper_trail
+    end
+    ```
 
-Add `has_paper_trail` to your model to record every `create`, `update`,
-and `destroy`.
+1. If your controllers have a `current_user` method, you can easily [track who
+is responsible for changes](#finding-out-who-was-responsible-for-a-change)
+by adding a controller callback.
 
-```ruby
-class Widget < ActiveRecord::Base
-  has_paper_trail
-end
-```
+    ```ruby
+    class ApplicationController
+      before_filter :set_paper_trail_whodunnit
+    end
+    ```
 
-This gives you a `versions` method which returns the "paper trail" of changes to
-your model.
+## Basic Usage
+
+Your models now have a `versions` method which returns the "paper trail" of
+changes to your model.
 
 ```ruby
 widget = Widget.find 42
@@ -182,7 +194,8 @@ Widget.paper_trail_enabled_for_model?
 widget.paper_trail_enabled_for_model?
 ```
 
-And a `PaperTrail::Version` instance has these methods:
+And a `PaperTrail::Version` instance (which is just an ordinary ActiveRecord
+instance, with all the usual methods) adds these methods:
 
 ```ruby
 # Returns the item restored from this version.
@@ -305,6 +318,11 @@ class Translation < ActiveRecord::Base
 end
 ```
 
+### Choosing Based on Changed Attributes
+
+Starting with PaperTrail 4.0, versions are saved during an after-callback. If
+you decide whether to save a new version based on changed attributes, please
+use attribute_name_was instead of attribute_name.
 
 ## Choosing Attributes To Monitor
 
@@ -393,69 +411,30 @@ class Article < ActiveRecord::Base
 end
 ```
 
-## Turning PaperTrail Off/On
+## Turning PaperTrail Off
 
-Sometimes you don't want to store changes.  Perhaps you are only interested in
-changes made by your users and don't need to store changes you make yourself in,
-say, a migration -- or when testing your application.
+PaperTrail is on by default, but sometimes you don't want to record versions.
 
-You can turn PaperTrail on or off in three ways: globally, per request, or per
-class.
+### Per Process
 
-### Globally
-
-On a global level you can turn PaperTrail off like this:
+Turn PaperTrail off for all threads in a `ruby` process.
 
 ```ruby
 PaperTrail.enabled = false
 ```
 
-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
-# in config/environments/test.rb
-config.after_initialize do
-  PaperTrail.enabled = false
-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:
-
-```ruby
-# in test/test_helper.rb
-def with_versioning
-  was_enabled = PaperTrail.enabled?
-  was_enabled_for_controller = PaperTrail.enabled_for_controller?
-  PaperTrail.enabled = true
-  PaperTrail.enabled_for_controller = true
-  begin
-    yield
-  ensure
-    PaperTrail.enabled = was_enabled
-    PaperTrail.enabled_for_controller = was_enabled_for_controller
-  end
-end
-```
+This is commonly used to speed up tests. See [Testing](#testing) below.
 
-And then use it in your tests like this:
+There is also a rails config option that does the same thing.
 
 ```ruby
-test "something that needs versioning" do
-  with_versioning do
-    # your test
-  end
-end
+# in config/environments/test.rb
+config.paper_trail.enabled = false
 ```
 
-### Per request
+### Per Request
 
-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`:
+Add a `paper_trail_enabled_for_controller` method to your controller.
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -465,22 +444,14 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-### 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:
+### Per Class
 
 ```ruby
 Widget.paper_trail_off!
-```
-
-And on again like this:
-
-```ruby
 Widget.paper_trail_on!
 ```
 
-### Per method call
+### Per Method
 
 You can call a method without creating a new version using `without_versioning`.
  It takes either a method name as a symbol:
@@ -683,28 +654,35 @@ PaperTrail::Version.delete_all ["created_at < ?", 1.week.ago]
 
 ## Finding Out Who Was Responsible For A Change
 
-If your `ApplicationController` has a `current_user` method, PaperTrail will
-attempt to store the value returned by `current_user.id` in the version's
+Set `PaperTrail.whodunnit=`, and that value will be stored in the version's
 `whodunnit` column.
 
-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.whodunnit = 'Andy Stewart'
+widget.update_attributes :name => 'Wibble'
+widget.versions.last.whodunnit              # Andy Stewart
+```
+
+If your controller has a `current_user` method, PaperTrail provides a
+`before_filter` that will assign `current_user.id` to `PaperTrail.whodunnit`.
+You can add this `before_filter` to your `ApplicationController`.
 
 ```ruby
 class ApplicationController
-  def user_for_paper_trail
-    logged_in? ? current_member.id : 'Public user'  # or whatever
-  end
+  before_filter :set_paper_trail_whodunnit
 end
 ```
 
-In a console session you can manually set who is responsible like this:
+You may want `set_paper_trail_whodunnit` to call a different method to find out
+who is responsible. To do so, override the `user_for_paper_trail` method in
+your controller like this:
 
 ```ruby
-PaperTrail.whodunnit = 'Andy Stewart'
-widget.update_attributes :name => 'Wibble'
-widget.versions.last.whodunnit              # Andy Stewart
+class ApplicationController
+  def user_for_paper_trail
+    logged_in? ? current_member.id : 'Public user'  # or whatever
+  end
+end
 ```
 
 See also: [Setting whodunnit in the rails console][33]
@@ -752,6 +730,11 @@ last_version.paper_trail_originator         # 'Alice'
 last_version.terminator                     # 'Bob'
 ```
 
+### Storing an ActiveRecord globalid in whodunnit
+
+If you would like `whodunnit` to return an `ActiveRecord` object instead of a
+string, please try the [paper_trail-globalid][37] gem.
+
 ## Associations
 
 **Experimental feature**, see caveats below.
@@ -770,7 +753,8 @@ the association that are created in the same transaction.
 
 To restore Has-One associations as they were at the time, pass option `:has_one
 => true` to `reify`. To restore Has-Many and Has-Many-Through associations, use
-option `:has_many => true`.  For example:
+option `:has_many => true`. To restore Belongs-To association, use
+option `:belongs_to => true`. For example:
 
 ```ruby
 class Location < ActiveRecord::Base
@@ -1123,7 +1107,7 @@ Postgres. In databases without such protection, such as MySQL, a table lock may
 be necessary.
 
 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
+PaperTrail data temporarily, you can create the new column without converting
 the data.
 
 ```ruby
@@ -1181,21 +1165,57 @@ 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 [Turning
+PaperTrail Off](#turning-papertrail-off) above.
 
-### RSpec
+### Minitest
 
-PaperTrail provides a helper that works with [RSpec][27] to make it easier to
-control when `PaperTrail` is enabled during testing.
+First, disable PT for the entire `ruby` process.
 
-If you wish to use the helper, you will need to require it in your RSpec test
-helper like so:
+```ruby
+# in config/environments/test.rb
+config.after_initialize do
+  PaperTrail.enabled = false
+end
+```
+
+Then, to enable PT for specific tests, you can add a `with_versioning` test
+helper method.
 
 ```ruby
-# spec/rails_helper.rb
+# in test/test_helper.rb
+def with_versioning
+  was_enabled = PaperTrail.enabled?
+  was_enabled_for_controller = PaperTrail.enabled_for_controller?
+  PaperTrail.enabled = true
+  PaperTrail.enabled_for_controller = true
+  begin
+    yield
+  ensure
+    PaperTrail.enabled = was_enabled
+    PaperTrail.enabled_for_controller = was_enabled_for_controller
+  end
+end
+```
+
+Then, use the helper in your tests.
 
+```ruby
+test "something that needs versioning" do
+  with_versioning do
+    # your test
+  end
+end
+```
+
+### RSpec
+
+PaperTrail provides a helper, `paper_trail/frameworks/rspec.rb`, that works with
+[RSpec][27] to make it easier to control when `PaperTrail` is enabled during
+testing.
+
+```ruby
+# spec/rails_helper.rb
 ENV["RAILS_ENV"] ||= 'test'
 require 'spec_helper'
 require File.expand_path("../../config/environment", __FILE__)
@@ -1204,10 +1224,10 @@ require 'rspec/rails'
 require 'paper_trail/frameworks/rspec'
 ```
 
-When the helper is loaded, PaperTrail will be turned off for all tests by
-default. When you wish to enable PaperTrail for a test you can either wrap the
+With the helper loaded, PaperTrail will be turned off for all tests by
+default. To enable PaperTrail for a test you can either wrap the
 test in a `with_versioning` block, or pass in `:versioning => true` option to a
-spec block, like so:
+spec block.
 
 ```ruby
 describe "RSpec test group" do
@@ -1377,7 +1397,7 @@ setting up your app with PaperTrail will look something like this:
 
 1. Add PaperTrail to your `Gemfile`.
 
-    `gem 'paper_trail', '~> 4.2.0'`
+    `gem 'paper_trail'`
 
 2. Generate a migration to add a `versions` table to your database.
 
@@ -1420,7 +1440,6 @@ end
   [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),
@@ -1533,3 +1552,5 @@ Released under the MIT licence.
 [34]: https://github.com/rails/rails/blob/591a0bb87fff7583e01156696fbbf929d48d3e54/activerecord/lib/active_record/fixtures.rb#L142
 [35]: https://dev.mysql.com/doc/refman/5.6/en/fractional-seconds.html
 [36]: http://www.postgresql.org/docs/9.4/interactive/ddl.html
+[37]: https://github.com/ankit1910/paper_trail-globalid
+[38]: https://github.com/sferik/rails_admin