Add new method to update User's email (#956)

Author: a-maurice

auth/src/FirebaseUser.cs

@@ -278,10 +278,14 @@ public Task<string> TokenAsync(bool forceRefresh) {
     return GetValidFirebaseUserInternal().TokenAsync(forceRefresh);
   }
 
+  /// @deprecated This method is deprecated. Please use
+  /// @ref SendEmailVerificationBeforeUpdatingEmailAsync(string) instead.
+  /// 
   /// Sets the email address for the user.
   ///
   /// May fail if there is already an email/password-based account for the same
   /// email address.
+  [System.Obsolete("Please use `Task SendEmailVerificationBeforeUpdatingEmailAsync(string)` instead", false)]
   public Task UpdateEmailAsync(string email) {
     return GetValidFirebaseUserInternal().UpdateEmailAsync(email);
   }
@@ -309,6 +313,12 @@ public Task SendEmailVerificationAsync() {
     return GetValidFirebaseUserInternal().SendEmailVerificationAsync();
   }
 
+  /// Send an email to verify the ownership of the account, then update
+  /// to the new email.
+  public Task SendEmailVerificationBeforeUpdatingEmailAsync(string email) {
+    return GetValidFirebaseUserInternal().SendEmailVerificationBeforeUpdatingEmailAsync(email);
+  }
+
   /// Updates a subset of user profile information.
   public Task UpdateUserProfileAsync(UserProfile profile) {
     return GetValidFirebaseUserInternal().UpdateUserProfileAsync(profile);

docs/readme.md

@@ -74,6 +74,9 @@ Release Notes
 ### Upcoming release
 - Changes
     - General (Android): Improve how property tag logic handles Unity 2022+.
+    - Auth: Add FirebaseUser.SendEmailVerificationBeforeUpdatingEmailAsync,
+      a new method to verify and change the User's email.
+    - Auth: Deprecate the older method of updating emails, UpdateEmail.
     - Dynamic Links: The Dynamic Links SDK is now deprecated. See the [support
       documentation](https://firebase.google.com/support/dynamic-links-faq)
       for more information.