Deprecate :paper_trail_on and :paper_trail_off methods in favor of bang versions

CHANGELOG.md

@@ -4,6 +4,8 @@
     instead of `current_user` (if `current_user` is defined).
   - [#313](https://github.com/airblade/paper_trail/pull/313) - Make the `Rails::Controller` helper compatible with
     `ActionController::API` for compatibility with the [`rails-api`](https://github.com/rails-api/rails-api) gem.
+  - 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`.
 
 ## 3.0.0
 

README.md

@@ -127,10 +127,10 @@ widget.previous_version
 widget.next_version
 
 # Turn PaperTrail off for all widgets.
-Widget.paper_trail_off
+Widget.paper_trail_off!
 
 # Turn PaperTrail on for all widgets.
-Widget.paper_trail_on
+Widget.paper_trail_on!
 ```
 
 And a `PaperTrail::Version` instance has these methods:
@@ -823,13 +823,13 @@ end
 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:
 
 ```ruby
->> Widget.paper_trail_off
+>> Widget.paper_trail_off!
 ```
 
 And on again like this:
 
 ```ruby
->> Widget.paper_trail_on
+>> Widget.paper_trail_on!
 ```
 
 ### Per method call

lib/paper_trail/has_paper_trail.rb

@@ -80,15 +80,25 @@ module PaperTrail
       end
 
       # Switches PaperTrail off for this class.
-      def paper_trail_off
+      def paper_trail_off!
         self.paper_trail_enabled_for_model = false
       end
 
+      def paper_trail_off
+        warn "DEPRECATED: use `paper_trail_off!` instead of `paper_trail_off`. Support for `paper_trail_off` will be removed in PaperTrail 3.1"
+        self.paper_trail_off!
+      end
+
       # Switches PaperTrail on for this class.
-      def paper_trail_on
+      def paper_trail_on!
         self.paper_trail_enabled_for_model = true
       end
 
+      def paper_trail_on
+        warn "DEPRECATED: use `paper_trail_on!` instead of `paper_trail_on`. Support for `paper_trail_on` will be removed in PaperTrail 3.1"
+        self.paper_trail_on!
+      end
+
       def paper_trail_version_class
         @paper_trail_version_class ||= version_class_name.constantize
       end
@@ -195,10 +205,10 @@ module PaperTrail
       # Executes the given method or block without creating a new version.
       def without_versioning(method = nil)
         paper_trail_was_enabled = self.paper_trail_enabled_for_model
-        self.class.paper_trail_off
+        self.class.paper_trail_off!
         method ? method.to_proc.call(self) : yield
       ensure
-        self.class.paper_trail_on if paper_trail_was_enabled
+        self.class.paper_trail_on! if paper_trail_was_enabled
       end
 
       private

spec/models/widget_spec.rb

@@ -20,4 +20,62 @@ describe Widget do
       end
     end
   end
+
+  describe "class methods" do
+    subject { Widget }
+
+    describe :paper_trail_off! do
+      it { should respond_to(:paper_trail_off!) }
+
+      it 'should set the `paper_trail_enabled_for_model` to `false`' do
+        subject.paper_trail_enabled_for_model.should be_true
+        subject.paper_trail_off!
+        subject.paper_trail_enabled_for_model.should be_false
+      end
+    end
+
+    describe :paper_trail_off do
+      it { should respond_to(:paper_trail_off) }
+
+      it 'should set the invoke `paper_trail_off!`' do
+        subject.should_receive(:warn)
+        subject.should_receive(:paper_trail_off!)
+        subject.paper_trail_off
+      end
+
+      it 'should display a deprecation warning' do
+        subject.should_receive(:warn).with("DEPRECATED: use `paper_trail_on!` instead of `paper_trail_on`. Support for `paper_trail_on` will be removed in PaperTrail 3.1")
+        subject.paper_trail_on
+      end
+    end
+
+    describe :paper_trail_on! do
+      before { subject.paper_trail_off! }
+
+      it { should respond_to(:paper_trail_on!) }
+
+      it 'should set the `paper_trail_enabled_for_model` to `true`' do
+        subject.paper_trail_enabled_for_model.should be_false
+        subject.paper_trail_on!
+        subject.paper_trail_enabled_for_model.should be_true
+      end
+    end
+
+    describe :paper_trail_on do
+      before { subject.paper_trail_off! }
+
+      it { should respond_to(:paper_trail_on) }
+
+      it 'should set the invoke `paper_trail_on!`' do
+        subject.should_receive(:warn)
+        subject.should_receive(:paper_trail_on!)
+        subject.paper_trail_on
+      end
+
+      it 'should display a deprecation warning' do
+        subject.should_receive(:warn).with("DEPRECATED: use `paper_trail_on!` instead of `paper_trail_on`. Support for `paper_trail_on` will be removed in PaperTrail 3.1")
+        subject.paper_trail_on
+      end
+    end
+  end
 end

test/dummy/app/models/elephant.rb

@@ -1,3 +1,3 @@
 class Elephant < Animal
-  paper_trail_off
+  paper_trail_off!
 end

test/unit/model_test.rb

@@ -478,11 +478,11 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
 
     context 'with its paper trail turned off' do
       setup do
-        Widget.paper_trail_off
+        Widget.paper_trail_off!
         @count = @widget.versions.length
       end
 
-      teardown { Widget.paper_trail_on }
+      teardown { Widget.paper_trail_on! }
 
       context 'when updated' do
         setup { @widget.update_attributes :name => 'Beeblebrox' }
@@ -500,7 +500,7 @@ class HasPaperTrailModelTest < ActiveSupport::TestCase
       end
 
       context 'and then its paper trail turned on' do
-        setup { Widget.paper_trail_on }
+        setup { Widget.paper_trail_on! }
 
         context 'when updated' do
           setup { @widget.update_attributes :name => 'Ford' }