Merge pull request #567 from airblade/various_doc_updates

Various doc updates

CHANGELOG.md

@@ -1,76 +1,111 @@
 ## 4.0.0 (Unreleased)
 
-### Changes
+### Changed
 
-- If you use a Rails initializer for PaperTrail add
-  `PaperTrail::Rails::Engine.eager_load!` to the beginning of it.
-  See the readme for an example.
+- 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).
 
-### Enhancements
+### Added
 
-If you depend on the `RSpec` or `Cucumber` helpers, you will need to [manually load them into your test helper](https://github.com/airblade/paper_trail#testing).
-
-  - [#563](https://github.com/airblade/paper_trail/pull/563) - Fixed a bug in 
-    `PaperTrail::Model::InstanceMethods#touch_with_version` so that it will trigger a version when the `on` option
-    was set to `[:create]`
-  - [#541](https://github.com/airblade/paper_trail/pull/541) - `PaperTrail.config.enabled` should be Thread Safe
-  - [#525](https://github.com/airblade/paper_trail/issues/525) / [#512](https://github.com/airblade/paper_trail/pull/512) -
+  - [#541](https://github.com/airblade/paper_trail/pull/541) -
+    `PaperTrail.config.enabled` should be Thread Safe
+  - [#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) - Support for opting out of saving changesets on models by choice
-    when the `object_changes` column exists on the default `versions` table.
-  - [#500](https://github.com/airblade/paper_trail/pull/500) - Support for passing `on: []` as an argument, with only manual
-    versioning via calls to `touch_with_version`
-  - [#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.
+  - [#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) - Support for
+    opting out of saving changesets on models by choice when the
+    `object_changes` column exists on the default `versions` table.
+  - [#500](https://github.com/airblade/paper_trail/pull/500) - Support for
+    passing `on: []` as an argument, with only manual versioning via calls to
+    `touch_with_version`
+  - [#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`.
-  - [#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`
-  - [#458](https://github.com/airblade/paper_trail/pull/458) - For `create` events, metadata pointing at attributes should attempt
-    to grab the current value instead of looking at the value prior to the change (which would always be `nil`)
-  - [#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.
-  - [#439](https://github.com/airblade/paper_trail/pull/439) / [#12](https://github.com/airblade/paper_trail/issues/12) -
+    [PostgreSQL's `JSONB` Type](http://www.postgresql.org/docs/9.4/static/datatype-json.html)
+    for storing `object` and `object_changes`.
+  - [#479](https://github.com/airblade/paper_trail/issues/479) - Deprecated
+    `originator` method, use `paper_trail_originator`.
+  - [#458](https://github.com/airblade/paper_trail/pull/458) - For `create`
+    events, metadata pointing at attributes should attempt to grab the current
+    value instead of looking at the value prior to the change (which would
+    always be `nil`)
+  - [#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.
+  - [#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.)
-  - [#438](https://github.com/airblade/paper_trail/issues/438) - `ModelKlass.paper_trail_enabled_for_model?` should return `false` if
+  - [#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.
-  - [#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`
-  - [#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 & Sinatra.
-  - [#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`.
-  - Both `PaperTrail.config` and `PaperTrail.configure` are now identical, and will both return the `PaperTrail::Config`
-    instance and also yield it if a block is provided.
-  - [#248](https://github.com/airblade/paper_trail/issues/248) - The migrations
-    created by the generator now use `longtext` instead of `text` in MySQL.
+  - [#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.
+  - [#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`
+  - [#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.
+  - [#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`.
+  - Both `PaperTrail.config` and `PaperTrail.configure` are now identical, and
+    will both return the `PaperTrail::Config` instance and also yield it if a
+    block is provided.
+
+### 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]`.
+  - [#248](https://github.com/airblade/paper_trail/issues/248) - In MySQL, to
+    prevent truncation, generated migrations now use `longtext` instead of `text`.
 
 ## 3.0.8
 

README.md

@@ -554,21 +554,7 @@ widget.update_attributes :name => 'Wibble'
 widget.versions.last.whodunnit              # Andy Stewart
 ```
 
-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:
-
-```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"
-  PaperTrail.whodunnit = "#{`whoami`.strip}: rake #{ARGV.join ' '}"
-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
@@ -1456,3 +1442,4 @@ Released under the MIT licence.
 [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

lib/paper_trail/config.rb

@@ -22,9 +22,11 @@ def initialize
 
     def serialized_attributes=(value)
       if ::ActiveRecord::VERSION::MAJOR >= 5
-        warn("DEPRECATED: ActiveRecord 5.0 deprecated `serialized_attributes` "  +
+        ::ActiveSupport::Deprecation.warn(
+          "ActiveRecord 5.0 deprecated `serialized_attributes` "  +
           "without replacement, so this PaperTrail config setting does " +
-          "nothing with this version, and is always turned off")
+          "nothing with this version, and is always turned off"
+        )
       end
       @serialized_attributes = value
     end
@@ -33,12 +35,12 @@ def track_associations
       @track_associations ||= PaperTrail::VersionAssociation.table_exists?
     end
     alias_method :track_associations?, :track_associations
-    
+
     # Indicates whether PaperTrail is on or off.
     def enabled
       PaperTrail.paper_trail_store[:paper_trail_enabled].nil? || PaperTrail.paper_trail_store[:paper_trail_enabled]
     end
-    
+
     def enabled= enable
       PaperTrail.paper_trail_store[:paper_trail_enabled] = enable
     end

lib/paper_trail/has_paper_trail.rb

@@ -192,7 +192,7 @@ def paper_trail_originator
       end
 
       def originator
-        warn "DEPRECATED: use `paper_trail_originator` instead of `originator`. Support for `originator` will be removed in PaperTrail 4.0"
+        ::ActiveSupport::Deprecation.warn "Use paper_trail_originator instead of originator."
         self.paper_trail_originator
       end
 

lib/paper_trail/version_concern.rb

@@ -257,7 +257,7 @@ def paper_trail_originator
     end
 
     def originator
-      warn "DEPRECATED: use `paper_trail_originator` instead of `originator`. Support for `originator` will be removed in PaperTrail 4.0"
+      ::ActiveSupport::Deprecation.warn "Use paper_trail_originator instead of originator."
       self.paper_trail_originator
     end
 

spec/models/version_spec.rb

@@ -75,19 +75,16 @@
 
       describe "#originator" do
         it { is_expected.to respond_to(:originator) }
-        let(:warning_msg) do
-          "DEPRECATED: use `paper_trail_originator` instead of `originator`." +
-          " Support for `originator` will be removed in PaperTrail 4.0"
-        end
 
         it 'should set the invoke `paper_trail_originator`' do
-          is_expected.to receive(:warn)
+          allow(ActiveSupport::Deprecation).to receive(:warn)
           is_expected.to receive(:paper_trail_originator)
           subject.originator
         end
 
         it 'should display a deprecation warning' do
-          is_expected.to receive(:warn).with(warning_msg)
+          expect(ActiveSupport::Deprecation).to receive(:warn).
+            with(/Use paper_trail_originator instead of originator/)
           subject.originator
         end
       end

spec/models/widget_spec.rb

@@ -177,19 +177,16 @@
         subject { widget }
 
         it { is_expected.to respond_to(:originator) }
-        let(:warning_msg) do
-          "DEPRECATED: use `paper_trail_originator` instead of `originator`." +
-          " Support for `originator` will be removed in PaperTrail 4.0"
-        end
 
         it 'should set the invoke `paper_trail_originator`' do
-          is_expected.to receive(:warn)
+          allow(::ActiveSupport::Deprecation).to receive(:warn)
           is_expected.to receive(:paper_trail_originator)
           subject.originator
         end
 
         it 'should display a deprecation warning' do
-          is_expected.to receive(:warn).with(warning_msg)
+          expect(::ActiveSupport::Deprecation).to receive(:warn).
+            with(/Use paper_trail_originator instead of originator/)
           subject.originator
         end
       end