deprecate AbC:Base::parent_prefixes.

rename ::_local_prefixes to ::local_prefixes to state the public attribute.
document the latter.
make ::local_prefixes private, test overriding it and remove documentation for overriding ::_parent_prefixes.

3 files changed, 69 insertions, 4 deletions

diff --git a/actionview/CHANGELOG.md b/actionview/CHANGELOG.md
index a6f6ac78db..bfd52f72bf 100644
--- a/actionview/CHANGELOG.md
+++ b/actionview/CHANGELOG.md
@@ -1,3 +1,7 @@
+* Deprecate `AbstractController::Base::parent_prefixes`. Override `AbstractController::Base::local_prefixes` when you want to change where to find views.
+
+    *Nick Sutterer*
+
 * Take label values into account when doing I18n lookups for model attributes.
 
     The following:
diff --git a/actionview/lib/action_view/view_paths.rb b/actionview/lib/action_view/view_paths.rb
index d96222e6dd..1fc4c7aa43 100644
--- a/actionview/lib/action_view/view_paths.rb
+++ b/actionview/lib/action_view/view_paths.rb
@@ -16,14 +16,26 @@ module ActionView
     module ClassMethods
       def _prefixes
         @_prefixes ||= begin
-          return _local_prefixes if superclass.abstract?
-          _local_prefixes + superclass._prefixes
+          deprecated_prefixes = handle_deprecated_parent_prefixes and return deprecated_prefixes
+
+          return local_prefixes if superclass.abstract?
+          local_prefixes + superclass._prefixes
         end
       end
 
-      def _local_prefixes
+      private
+
+      # Override this method in your controller if you want to change paths prefixes for finding views.
+      # Prefixes defined here will still be added to parents' <tt>::_prefixes</tt>.
+      def local_prefixes
         [controller_path]
       end
+
+      def handle_deprecated_parent_prefixes # TODO: remove in 4.3/5.0.
+        return unless respond_to?(:parent_prefixes)
+        ActiveSupport::Deprecation.warn "Overriding ActionController::Base::parent_prefixes is deprecated, override ::local_prefixes or ::_prefixes instead."
+        local_prefixes + parent_prefixes
+      end
     end
 
     # The prefixes used in render "foo" shortcuts.
@@ -88,4 +100,4 @@ module ActionView
       end
     end
   end
-end
+end
\ No newline at end of file
diff --git a/actionview/test/actionpack/abstract/abstract_controller_test.rb b/actionview/test/actionpack/abstract/abstract_controller_test.rb
index 40d3b17131..8a97b70901 100644
--- a/actionview/test/actionpack/abstract/abstract_controller_test.rb
+++ b/actionview/test/actionpack/abstract/abstract_controller_test.rb
@@ -150,6 +150,55 @@ module AbstractController
       end
     end
 
+    class OverridingLocalPrefixes < AbstractController::Base
+      include AbstractController::Rendering
+      include ActionView::Rendering
+      append_view_path File.expand_path(File.join(File.dirname(__FILE__), "views"))
+
+
+      def index
+        render
+      end
+
+      def self.local_prefixes
+        # this would usually return "abstract_controller/testing/overriding_local_prefixes"
+        super + ["abstract_controller/testing/me3"]
+      end
+
+      class Inheriting < self
+      end
+    end
+
+    class OverridingLocalPrefixesTest < ActiveSupport::TestCase # TODO: remove me in 5.0/4.3.
+      test "overriding ::local_prefixes adds prefix" do
+        @controller = OverridingLocalPrefixes.new
+        @controller.process(:index)
+        assert_equal "Hello from me3/index.erb", @controller.response_body
+      end
+
+      test "::local_prefixes is inherited" do
+        @controller = OverridingLocalPrefixes::Inheriting.new
+        @controller.process(:index)
+        assert_equal "Hello from me3/index.erb", @controller.response_body
+      end
+    end
+
+    class DeprecatedParentPrefixes < OverridingLocalPrefixes
+      def self.parent_prefixes
+        ["abstract_controller/testing/me3"]
+      end
+    end
+
+    class DeprecatedParentPrefixesTest < ActiveSupport::TestCase # TODO: remove me in 5.0/4.3.
+      test "overriding ::parent_prefixes is deprecated" do
+        @controller = DeprecatedParentPrefixes.new
+        assert_deprecated do
+          @controller.process(:index)
+        end
+        assert_equal "Hello from me3/index.erb", @controller.response_body
+      end
+    end
+
     # Test rendering with layouts
     # ====
     # self._layout is used when defined