Document where support for AR normalizes

Also some other small changelog tweak:
* Add normalize_value_for to the activerecord changelog
* Fix a wrong method reference in the 7.1 release notes

activerecord/CHANGELOG.md

@@ -856,6 +856,7 @@
       ```ruby
       class User < ActiveRecord::Base
         normalizes :email, with: -> email { email.strip.downcase }
+        normalizes :phone, with: -> phone { phone.delete("^0-9").delete_prefix("1") }
       end
 
       user = User.create(email: " CRUISE-CONTROL@EXAMPLE.COM\n")
@@ -865,8 +866,12 @@
       user.email                  # => "cruise-control@example.com"
       user.email_before_type_cast # => "cruise-control@example.com"
 
+      User.where(email: "\tCRUISE-CONTROL@EXAMPLE.COM ").count # => 1
+
       User.exists?(email: "\tCRUISE-CONTROL@EXAMPLE.COM ")         # => true
       User.exists?(["email = ?", "\tCRUISE-CONTROL@EXAMPLE.COM "]) # => false
+
+      User.normalize_value_for(:phone, "+1 (555) 867-5309") # => "5558675309"
       ```
 
     *Jonathan Hefner*

activerecord/lib/active_record/normalization.rb

@@ -69,6 +69,8 @@ module ClassMethods
       #   user.email                  # => "cruise-control@example.com"
       #   user.email_before_type_cast # => "cruise-control@example.com"
       #
+      #   User.where(email: "\tCRUISE-CONTROL@EXAMPLE.COM ").count # => 1
+      #
       #   User.exists?(email: "\tCRUISE-CONTROL@EXAMPLE.COM ")         # => true
       #   User.exists?(["email = ?", "\tCRUISE-CONTROL@EXAMPLE.COM "]) # => false
       #

activerecord/test/cases/normalized_attribute_test.rb

@@ -83,6 +83,16 @@ class NormalizedAircraft < Aircraft
     assert_equal @aircraft, NormalizedAircraft.find_by(manufactured_at: @time.to_s)
   end
 
+  test "searches a record by normalized value" do
+    from_database = NormalizedAircraft.where(name: "fly HIGH")
+    assert_equal [@aircraft], from_database
+  end
+
+  test "searches a record by normalized values" do
+    from_database = NormalizedAircraft.where(name: ["fly LOW", "fly HIGH"])
+    assert_equal [@aircraft], from_database
+  end
+
   test "can stack normalizations" do
     titlecase_then_reverse = Class.new(NormalizedAircraft) do
       normalizes :name, with: -> name { name.reverse }

guides/source/7_1_release_notes.md

@@ -78,10 +78,12 @@ user = User.find_by(email: "\tCRUISE-CONTROL@EXAMPLE.COM ")
 user.email                  # => "cruise-control@example.com"
 user.email_before_type_cast # => "cruise-control@example.com"
 
+User.where(email: "\tCRUISE-CONTROL@EXAMPLE.COM ").count # => 1
+
 User.exists?(email: "\tCRUISE-CONTROL@EXAMPLE.COM ")         # => true
 User.exists?(["email = ?", "\tCRUISE-CONTROL@EXAMPLE.COM "]) # => false
 
-User.normalize(:phone, "+1 (555) 867-5309") # => "5558675309"
+User.normalize_value_for(:phone, "+1 (555) 867-5309") # => "5558675309"
 ```
 
 ### Add `ActiveRecord::Base.generates_token_for`