Add CHANGELOG entry for #43688 [ci-skip]

activemodel/CHANGELOG.md

@@ -1,3 +1,56 @@
+*   `has_secure_password` now supports password challenges via a
+    `password_challenge` accessor and validation.
+
+    A password challenge is a safeguard to verify that the current user is
+    actually the password owner.  It can be used when changing sensitive model
+    fields, such as the password itself.  It is different than a password
+    confirmation, which is used to prevent password typos.
+
+    When `password_challenge` is set, the validation checks that the value's
+    digest matches the *currently persisted* `password_digest` (i.e.
+    `password_digest_was`).
+
+    This allows a password challenge to be done as part of a typical `update`
+    call, just like a password confirmation.  It also allows a password
+    challenge error to be handled in the same way as other validation errors.
+
+    For example, in the controller, instead of:
+
+    ```ruby
+    password_params = params.require(:password).permit(
+      :password_challenge,
+      :password,
+      :password_confirmation,
+    )
+
+    password_challenge = password_params.delete(:password_challenge)
+    @password_challenge_failed = !current_user.authenticate(password_challenge)
+
+    if !@password_challenge_failed && current_user.update(password_params)
+      # ...
+    end
+    ```
+
+    You can now write:
+
+    ```ruby
+    password_params = params.require(:password).permit(
+      :password_challenge,
+      :password,
+      :password_confirmation,
+    ).with_defaults(password_challenge: "")
+
+    if current_user.update(password_params)
+      # ...
+    end
+    ```
+
+    And, in the view, instead of checking `@password_challenge_failed`, you can
+    render an error for the `password_challenge` field just as you would for
+    other form fields, including utilizing `config.action_view.field_error_proc`.
+
+    *Jonathan Hefner*
+
 *   Support infinite ranges for `LengthValidator`s `:in`/`:within` options
 
     ```ruby