[google_sign_in] Add exception info to migration guide (#9574)

Adds discussion of the new exception flows to the migration guide.

Also makes the API comment discussion of initialize more thorough

Fixes flutter/flutter#171704
Fixes flutter/flutter#171746

## Pre-Review Checklist

[^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.

Author: stuartmorgan-g

packages/google_sign_in/google_sign_in/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 7.1.1
+
+* Adds more documentation about the requirement to call `initialize` exactly
+  once.
+* Adds information about `GoogleSignInException` to the migration guide.
+
 ## 7.1.0
 
 * Adds the missing export of `GoogleSignInExceptionCode`, to allow for

packages/google_sign_in/google_sign_in/MIGRATION.md

@@ -61,3 +61,10 @@ include:
   publishing, the only platform that does not support `authenticate` is web,
   where `google_sign_in_web`'s `renderButton` is used to create a sign-in
   button.
+* Outcomes other than successful authentication or authorization will throw
+  `GoogleSignInException`s in most cases, allowing a clear way to distinguish
+  different sign in failure outcomes. This includes the user canceling
+  sign-in, which will throw an exception with a `code` of
+  `GoogleSignInExceptionCode.canceled`.
+    * Similarly, the `authenticationEvents` will receive exceptions as
+      stream errors, unlike the event stream from version 6.x.

packages/google_sign_in/google_sign_in/lib/google_sign_in.dart

@@ -233,14 +233,16 @@ class GoogleSignIn {
 
   /// Returns the single [GoogleSignIn] instance.
   ///
-  /// [initialize] must be called on this instance, and its future allowed to
-  /// complete, before any other methods on the object are called.
+  /// [initialize] must be called on this instance exactly once, and its future
+  /// allowed to complete, before any other methods on the object are called.
   static final GoogleSignIn instance = GoogleSignIn._();
 
   /// Initializes the sign in manager with the given configuration.
   ///
   /// Clients must call this method exactly once, and wait for its future to
-  /// complete, before calling any other methods on this object.
+  /// complete, before calling any other methods on this object. Calling other
+  /// methods without waiting for this method to return, or calling this method
+  /// more than once, will result in undefined behavior.
   ///
   /// [clientId] is the identifier for your client application, as provided by
   /// the Google Sign In server configuration, if any. This does not need to be

packages/google_sign_in/google_sign_in/pubspec.yaml

@@ -3,7 +3,7 @@ description: Flutter plugin for Google Sign-In, a secure authentication system
   for signing in with a Google account.
 repository: https://github.com/flutter/packages/tree/main/packages/google_sign_in/google_sign_in
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+google_sign_in%22
-version: 7.1.0
+version: 7.1.1
 
 environment:
   sdk: ^3.6.0