From 3de346259b36bc7aef10de71c48cfcda6064a972 Mon Sep 17 00:00:00 2001
From: Benjamin Wang <wachao@vmware.com>
Date: Thu, 23 Feb 2023 09:58:48 +0800
Subject: [PATCH] clientv3: update etcdctl's readme and comment of
 clientv3.WithSerializable to clarify the use cases

Signed-off-by: Benjamin Wang <wachao@vmware.com>
---
 client/v3/op.go   | 12 +++++++++---
 etcdctl/README.md | 19 ++++++++++++++++---
 2 files changed, 25 insertions(+), 6 deletions(-)

diff --git a/client/v3/op.go b/client/v3/op.go
index 6193d090a..1b08db5b3 100644
--- a/client/v3/op.go
+++ b/client/v3/op.go
@@ -418,9 +418,15 @@ func WithFromKey() OpOption {
 	}
 }
 
-// WithSerializable makes 'Get' request serializable. By default,
-// it's linearizable. Serializable requests are better for lower latency
-// requirement.
+// WithSerializable makes `Get` and `MemberList` requests serializable.
+// By default, they are linearizable. Serializable requests are better
+// for lower latency requirement, but users should be aware that they
+// could get stale data with serializable requests.
+//
+// In some situations users may want to use serializable requests. For
+// example, when adding a new member to a one-node cluster, it's reasonable
+// and safe to use serializable request before the new added member gets
+// started.
 func WithSerializable() OpOption {
 	return func(op *Op) { op.serializable = true }
 }
diff --git a/etcdctl/README.md b/etcdctl/README.md
index a25e05132..efff407cf 100644
--- a/etcdctl/README.md
+++ b/etcdctl/README.md
@@ -119,15 +119,22 @@ RPC: Range
 
 - print-value-only -- print only value when used with write-out=simple
 
-- consistency -- Linearizable(l) or Serializable(s)
+- consistency -- Linearizable(l) or Serializable(s), defaults to Linearizable(l).
 
 - from-key -- Get keys that are greater than or equal to the given key using byte compare
 
 - keys-only -- Get only the keys
 
 #### Output
-
+Prints the data in format below,
+```
 \<key\>\n\<value\>\n\<next_key\>\n\<next_value\>...
+```
+
+Note serializable requests are better for lower latency requirement, but
+stale data might be returned if serializable option (`--consistency=s`)
+is specified.
+
 
 #### Examples
 
@@ -712,12 +719,18 @@ MEMBER LIST prints the member details for all members associated with an etcd cl
 RPC: MemberList
 
 #### Options
-- consistency -- Linearizable(l) or Serializable(s)
+- consistency -- Linearizable(l) or Serializable(s), defaults to Linearizable(l).
 
 #### Output
 
 Prints a humanized table of the member IDs, statuses, names, peer addresses, and client addresses.
 
+Note serializable requests are better for lower latency requirement, but
+stale member list might be returned if serializable option (`--consistency=s`)
+is specified. In some situations users may want to use serializable requests.
+For example, when adding a new member to a one-node cluster, it's reasonable
+and safe to use serializable request before the new added member gets started.
+
 #### Examples
 
 ```bash