Backport change for #479 (renaming of #originator to #paper_trail_ori…

…ginator)

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 3.0.9 (Unreleased)
+
+  - [#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) -
@@ -63,7 +71,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.
@@ -74,8 +82,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 `4.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
 

README.md

@@ -115,7 +115,7 @@ widget.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)
@@ -147,7 +147,7 @@ And a `PaperTrail::Version` instance has these methods:
 version.reify(options = {})
 
 # 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
@@ -504,22 +504,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.originator`.  And to find out who made a "live" object look like it does, use `originator` on the object.
+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.originator                           # 'Alice'
+>> widget..paper_trail_originator              # 'Alice'
 >> PaperTrail.whodunnit = 'Bob'
 >> widget.update_attributes :name => 'Zulu'
->> widget.originator                           # 'Bob'
+>> widget.paper_trail_originator               # 'Bob'
 >> first_version, last_version = widget.versions.first, widget.versions.last
 >> first_version.whodunnit                     # 'Alice'
->> first_version.originator                    # nil
+>> first_version.paper_trail_originator        # nil
 >> first_version.terminator                    # 'Alice'
 >> last_version.whodunnit                      # 'Bob'
->> last_version.originator                     # 'Alice'
+>> last_version.paper_trail_originator         # 'Alice'
 >> last_version.terminator                     # 'Bob'
 ```
 

lib/paper_trail/has_paper_trail.rb

@@ -1,3 +1,5 @@
+require 'active_support/core_ext/object' # provides the `try` method
+
 module PaperTrail
   module Model
 
@@ -173,10 +175,15 @@ def live?
       end
 
       # Returns who put the object into its current state.
-      def originator
+      def paper_trail_originator
         (source_version || send(self.class.versions_association_name).last).try(:whodunnit)
       end
 
+      def originator
+        warn "DEPRECATED: use `paper_trail_originator` instead of `originator`. Support for `originator` will be removed in PaperTrail 4.0"
+        self.paper_trail_originator
+      end
+
       # Returns the object (not a Version) as it was at the given timestamp.
       def version_at(timestamp, reify_options={})
         # Because a version stores how its object looked *before* the change,

lib/paper_trail/version_concern.rb

@@ -181,8 +181,13 @@ def changeset
     end
 
     # Returns who put the item into the state stored in this version.
+    def paper_trail_originator
+      @paper_trail_originator ||= previous.whodunnit rescue nil
+    end
+
     def originator
-      @originator ||= previous.whodunnit rescue nil
+      warn "DEPRECATED: use `paper_trail_originator` instead of `originator`. Support for `originator` will be removed in PaperTrail 4.0"
+      self.paper_trail_originator
     end
 
     # Returns who changed the item from the state it had in this version.

spec/models/version_spec.rb

@@ -22,13 +22,60 @@
     describe "Instance" do
       subject { PaperTrail::Version.new(attributes) rescue PaperTrail::Version.new }
 
-      describe :terminator do
+      describe '#paper_trail_originator' do
+        it { is_expected.to respond_to(:paper_trail_originator) }
+
+        context "No previous versions" do
+          specify { expect(subject.previous).to be_nil }
+
+          it "should return nil" do
+            expect(subject.paper_trail_originator).to be_nil
+          end
+        end
+
+        context "Has previous version", :versioning => true do
+          let(:name) { Faker::Name.name }
+          let(:widget) { Widget.create!(name: Faker::Name.name) }
+          before do
+            widget.versions.first.update_attributes!(:whodunnit => name)
+            widget.update_attributes!(name: Faker::Name.first_name)
+          end
+          subject { widget.versions.last }
+
+          specify { expect(subject.previous).to be_instance_of(PaperTrail::Version) }
+
+          it "should return nil" do
+            expect(subject.paper_trail_originator).to eq(name)
+          end
+        end
+      end
+
+      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)
+          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)
+          subject.originator
+        end
+      end
+
+      describe '#terminator' do
         it { should respond_to(:terminator) }
 
         let(:attributes) { {:whodunnit => Faker::Name.first_name} }
 
         it "is an alias for the `whodunnit` attribute" do
-          subject.whodunnit.should == attributes[:whodunnit]
+          subject.terminator.should == attributes[:whodunnit]
         end
       end
 

spec/models/widget_spec.rb

@@ -72,8 +72,8 @@
 
   describe "Methods" do
     describe "Instance", :versioning => true do
-      describe :originator do
-        it { should respond_to(:originator) }
+      describe '#paper_trail_originator' do
+        it { should respond_to(:paper_trail_originator) }
 
         describe "return value" do
           let(:orig_name) { Faker::Name.name }
@@ -84,9 +84,9 @@
             specify { widget.should be_live }
 
             it "should return the originator for the model at a given state" do
-              widget.originator.should == orig_name
+              widget.paper_trail_originator.should == orig_name
               widget.whodunnit(new_name) { |w| w.update_attributes(:name => 'Elizabeth') }
-              widget.originator.should == new_name
+              widget.paper_trail_originator.should == new_name
             end
           end
 
@@ -99,13 +99,34 @@
             let(:reified_widget) { widget.versions[1].reify }
 
             it "should return the appropriate originator" do
-              reified_widget.originator.should == orig_name
+              reified_widget.paper_trail_originator.should == orig_name
             end
           end
         end
       end
 
-      describe :version_at do
+      describe "#originator" do
+        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)
+          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)
+          subject.originator
+        end
+      end
+
+      describe '#version_at' do
         it { should respond_to(:version_at) }
 
         context "Timestamp argument is AFTER object has been destroyed" do

test/unit/model_test.rb

@@ -567,9 +567,9 @@ def without(&block)
 
       should 'track who made the change' do
         assert_equal 'Alice', @version.whodunnit
-        assert_nil   @version.originator
+        assert_nil   @version.paper_trail_originator
         assert_equal 'Alice', @version.terminator
-        assert_equal 'Alice', @widget.originator
+        assert_equal 'Alice', @widget.paper_trail_originator
       end
 
       context 'when a record is updated' do
@@ -581,9 +581,9 @@ def without(&block)
 
         should 'track who made the change' do
           assert_equal 'Bob',   @version.whodunnit
-          assert_equal 'Alice', @version.originator
+          assert_equal 'Alice', @version.paper_trail_originator
           assert_equal 'Bob',   @version.terminator
-          assert_equal 'Bob',   @widget.originator
+          assert_equal 'Bob',   @widget.paper_trail_originator
         end
 
         context 'when a record is destroyed' do
@@ -595,9 +595,9 @@ def without(&block)
 
           should 'track who made the change' do
             assert_equal 'Charlie', @version.whodunnit
-            assert_equal 'Bob',     @version.originator
+            assert_equal 'Bob',     @version.paper_trail_originator
             assert_equal 'Charlie', @version.terminator
-            assert_equal 'Charlie', @widget.originator
+            assert_equal 'Charlie', @widget.paper_trail_originator
           end
         end
       end
@@ -649,7 +649,7 @@ def without(&block)
     should 'should return the correct originator' do
       PaperTrail.whodunnit = 'Ben'
       @foo.update_attribute(:name, 'Geoffrey')
-      assert_equal PaperTrail.whodunnit, @foo.originator
+      assert_equal PaperTrail.whodunnit, @foo.paper_trail_originator
     end
 
     context 'when destroyed' do