3 files changed, 35 insertions, 0 deletions
diff --git a/activesupport/CHANGELOG.md b/activesupport/CHANGELOG.md
index cdea917380..80e61f26eb 100644
--- a/activesupport/CHANGELOG.md
+++ b/activesupport/CHANGELOG.md
@@ -1,3 +1,8 @@
+*   Soft-deprecated the top-level `HashWithIndifferentAcces` constant.
+    `ActiveSupport::HashWithIndifferentAccess` should be used instead.
+
+    *Robin Dupret* (#28157)
+
 *   In Core Extensions, make `MarshalWithAutoloading#load` pass through the second, optional
     argument for `Marshal#load( source [, proc] )`. This way we don't have to do 
     `Marshal.method(:load).super_method.call(sourse, proc)` just to be able to pass a proc.
diff --git a/activesupport/lib/active_support/hash_with_indifferent_access.rb b/activesupport/lib/active_support/hash_with_indifferent_access.rb
index f9b269ad69..1927cddf34 100644
--- a/activesupport/lib/active_support/hash_with_indifferent_access.rb
+++ b/activesupport/lib/active_support/hash_with_indifferent_access.rb
@@ -316,4 +316,6 @@ module ActiveSupport
   end
 end
 
+# :stopdoc:
+
 HashWithIndifferentAccess = ActiveSupport::HashWithIndifferentAccess
diff --git a/activesupport/test/core_ext/hash_ext_test.rb b/activesupport/test/core_ext/hash_ext_test.rb
index a6e3e59433..525ea08abd 100644
--- a/activesupport/test/core_ext/hash_ext_test.rb
+++ b/activesupport/test/core_ext/hash_ext_test.rb
@@ -8,6 +8,8 @@ require "active_support/core_ext/object/deep_dup"
 require "active_support/inflections"
 
 class HashExtTest < ActiveSupport::TestCase
+  HashWithIndifferentAccess = ActiveSupport::HashWithIndifferentAccess
+
   class IndifferentHash < ActiveSupport::HashWithIndifferentAccess
   end
 
@@ -1088,6 +1090,30 @@ class HashExtTest < ActiveSupport::TestCase
     assert_equal 1, hash[:a]
     assert_equal 3, hash[:b]
   end
+
+  def test_inheriting_from_top_level_hash_with_indifferent_access_preserves_ancestors_chain
+    klass = Class.new(::HashWithIndifferentAccess)
+    assert_equal ActiveSupport::HashWithIndifferentAccess, klass.ancestors[1]
+  end
+
+  def test_inheriting_from_hash_with_indifferent_access_properly_dumps_ivars
+    klass = Class.new(::HashWithIndifferentAccess) do
+      def initialize(*)
+        @foo = "bar"
+        super
+      end
+    end
+
+    yaml_output = klass.new.to_yaml
+
+    # `hash-with-ivars` was introduced in 2.0.9 (https://git.io/vyUQW)
+    if Gem::Version.new(Psych::VERSION) >= Gem::Version.new("2.0.9")
+      assert_includes yaml_output, "hash-with-ivars"
+      assert_includes yaml_output, "@foo: bar"
+    else
+      assert_includes yaml_output, "hash"
+    end
+  end
 end
 
 class IWriteMyOwnXML
@@ -1133,6 +1159,8 @@ class HashExtToParamTests < ActiveSupport::TestCase
 end
 
 class HashToXmlTest < ActiveSupport::TestCase
+  HashWithIndifferentAccess = ActiveSupport::HashWithIndifferentAccess
+
   def setup
     @xml_options = { root: :person, skip_instruct: true, indent: 0 }
   end