Deprecate the bypass option of sign_in (#4078)

The sign_in method permits the bypass option
that ignore the others options used. This behavior
has lead some users to a misconfusion what the
method really does.

This change deprecate the bypass option in favor
of a method that only does the sign in with bypass.

Closes #3981

app/controllers/devise/registrations_controller.rb

@@ -53,7 +53,7 @@ class Devise::RegistrationsController < DeviseController
           :update_needs_confirmation : :updated
         set_flash_message :notice, flash_key
       end
-      sign_in resource_name, resource, bypass: true
+      bypass_sign_in resource, scope: resource_name
       respond_with resource, location: after_update_path_for(resource)
     else
       clean_up_passwords resource

lib/devise/controllers/sign_in_out.rb

@@ -12,20 +12,15 @@ module Devise
       end
 
       # Sign in a user that already was authenticated. This helper is useful for logging
-      # users in after sign up.
-      #
-      # All options given to sign_in is passed forward to the set_user method in warden.
-      # The only exception is the :bypass option, which bypass warden callbacks and stores
-      # the user straight in session. This option is useful in cases the user is already
-      # signed in, but we want to refresh the credentials in session.
+      # users in after sign up. All options given to sign_in is passed forward
+      # to the set_user method in warden.
       #
       # Examples:
       #
       #   sign_in :user, @user                      # sign_in(scope, resource)
       #   sign_in @user                             # sign_in(resource)
-      #   sign_in @user, event: :authentication  # sign_in(resource, options)
-      #   sign_in @user, store: false            # sign_in(resource, options)
-      #   sign_in @user, bypass: true            # sign_in(resource, options)
+      #   sign_in @user, event: :authentication     # sign_in(resource, options)
+      #   sign_in @user, store: false               # sign_in(resource, options)
       #
       def sign_in(resource_or_scope, *args)
         options  = args.extract_options!
@@ -35,6 +30,13 @@ module Devise
         expire_data_after_sign_in!
 
         if options[:bypass]
+          ActiveSupport::Deprecation.warn(<<-DEPRECATION.strip_heredoc, caller)
+          [Devise] bypass option is deprecated and it will be removed in future version of Devise.
+          Please use bypass_sign_in method instead.
+          Example:
+
+            bypass_sign_in(user)
+          DEPRECATION
           warden.session_serializer.store(resource, scope)
         elsif warden.user(scope) == resource && !options.delete(:force)
           # Do nothing. User already signed in and we are not forcing it.
@@ -44,6 +46,20 @@ module Devise
         end
       end
 
+      # Sign in a user bypassing the warden callbacks and stores the user
+      # straight in session. This option is useful in cases the user is already
+      # signed in, but we want to refresh the credentials in session.
+      #
+      # Examples:
+      #
+      #   bypass_sign_in @user, scope: :user
+      #   bypass_sign_in @user
+      def bypass_sign_in(resource, scope: nil)
+        scope ||= Devise::Mapping.find_scope!(resource)
+        expire_data_after_sign_in!
+        warden.session_serializer.store(resource, scope)
+      end
+
       # Sign out a given user or scope. This helper is useful for signing out a user
       # after deleting accounts. Returns true if there was a logout and false if there
       # is no user logged in on the referred scope

test/controllers/helpers_test.rb

@@ -150,11 +150,11 @@ class ControllerAuthenticatableTest < Devise::ControllerTestCase
     @controller.sign_in(user, force: true)
   end
 
-  test 'sign in accepts bypass as option' do
+  test 'bypass the sign in' do
     user = User.new
     @mock_warden.expects(:session_serializer).returns(serializer = mock())
     serializer.expects(:store).with(user, :user)
-    @controller.sign_in(user, bypass: true)
+    @controller.bypass_sign_in(user)
   end
 
   test 'sign out clears up any signed in user from all scopes' do