From a6d03aa674126474e8f3886830ac433942e5c6c2 Mon Sep 17 00:00:00 2001
From: Alex Hong <9397363+hongalex@users.noreply.github.com>
Date: Mon, 18 Apr 2022 15:07:54 -0700
Subject: [PATCH 1/3] feat(pubsub): deprecate synchronous mode

---
 pubsub/subscription.go | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/pubsub/subscription.go b/pubsub/subscription.go
index b3bb646a41ee..c784018ea9be 100644
--- a/pubsub/subscription.go
+++ b/pubsub/subscription.go
@@ -553,12 +553,18 @@ type ReceiveSettings struct {
 	// processed concurrently, set MaxOutstandingMessages.
 	NumGoroutines int
 
-	// If Synchronous is true, then no more than MaxOutstandingMessages will be in
-	// memory at one time. (In contrast, when Synchronous is false, more than
-	// MaxOutstandingMessages may have been received from the service and in memory
-	// before being processed.) MaxOutstandingBytes still refers to the total bytes
-	// processed, rather than in memory. NumGoroutines is ignored.
+	// Synchronous switches the underlying receiving mechanism to unary Pull.
+	// When Synchronous is false, the more performance StreamingPull is used.
+	// When in Synchronous mode, NumGoroutines is set to 1 and only one outstanding
+	// RPC will be made to poll messages.
 	// The default is false.
+	//
+	// Deprecated.
+	// Previously, users might use Synchronous mode since StreamingPull had a limitation
+	// where MaxOutstandingMessages was not always respected with large batches of
+	// small messsages. With server side flow control, this is no longer an issue
+	// and we recommend switching to the default StreamingPull mode by setting
+	// Synchronous to false.
 	Synchronous bool
 }
 

From a20d5be2701501b4c949e90bb0d3cd31e1eb1087 Mon Sep 17 00:00:00 2001
From: Alex Hong <9397363+hongalex@users.noreply.github.com>
Date: Mon, 18 Apr 2022 15:47:01 -0700
Subject: [PATCH 2/3] add back default comment

---
 pubsub/subscription.go | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pubsub/subscription.go b/pubsub/subscription.go
index c784018ea9be..dfb282b3f07d 100644
--- a/pubsub/subscription.go
+++ b/pubsub/subscription.go
@@ -554,7 +554,7 @@ type ReceiveSettings struct {
 	NumGoroutines int
 
 	// Synchronous switches the underlying receiving mechanism to unary Pull.
-	// When Synchronous is false, the more performance StreamingPull is used.
+	// When Synchronous is false, the more performant StreamingPull is used.
 	// When in Synchronous mode, NumGoroutines is set to 1 and only one outstanding
 	// RPC will be made to poll messages.
 	// The default is false.

From 716c13027dee2d9750e78dfd4268a416f2e8b937 Mon Sep 17 00:00:00 2001
From: Alex Hong <9397363+hongalex@users.noreply.github.com>
Date: Tue, 19 Apr 2022 15:38:21 -0700
Subject: [PATCH 3/3] add clarifying comment on subscriber affinity

---
 pubsub/subscription.go | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/pubsub/subscription.go b/pubsub/subscription.go
index dfb282b3f07d..535c8e810cbd 100644
--- a/pubsub/subscription.go
+++ b/pubsub/subscription.go
@@ -555,8 +555,10 @@ type ReceiveSettings struct {
 
 	// Synchronous switches the underlying receiving mechanism to unary Pull.
 	// When Synchronous is false, the more performant StreamingPull is used.
-	// When in Synchronous mode, NumGoroutines is set to 1 and only one outstanding
-	// RPC will be made to poll messages.
+	// StreamingPull also has the benefit of subscriber affinity when using
+	// ordered delivery.
+	// When Synchronous is true, NumGoroutines is set to 1 and only one Pull
+	// RPC will be made to poll messages at a time.
 	// The default is false.
 	//
 	// Deprecated.