diff --git a/core/src/docs/upgrade.md b/core/src/docs/upgrade.md
index c59c11004fe..e37e057b58f 100644
--- a/core/src/docs/upgrade.md
+++ b/core/src/docs/upgrade.md
@@ -1,3 +1,15 @@
+# Unreleased
+
+## Public API
+
+### RFC-2774 Lister API
+
+RFC-2774 proposes a new `lister` API to replace current `list` and `scan`. And we add a new API `list` to return entries directly.
+
+For users who want to list a directory at once, please use `Operator::list` and `Operator::list_with` for convenience.
+
+For users who want to list a directory in streaming, please use `Operator::lister` and `Operator::lister_with` instead.
+
 # Upgrade to v0.39
 
 ## Public API
diff --git a/core/src/types/operator/operator.rs b/core/src/types/operator/operator.rs
index 5ab22af5465..d18137cbce9 100644
--- a/core/src/types/operator/operator.rs
+++ b/core/src/types/operator/operator.rs
@@ -1270,6 +1270,14 @@ impl Operator {
     ///
     /// # Notes
     ///
+    /// ## For listing recursively
+    ///
+    /// This function only read the children of the given directory. To read
+    /// all entries recursively, use `Operator::list_with("path").delimiter("")`
+    /// instead.
+    ///
+    /// ## For streaming
+    ///
     /// This function will read all entries in the given directory. It could
     /// take very long time and consume a lot of memory if the directory
     /// contains a lot of entries.
@@ -1310,6 +1318,8 @@ impl Operator {
     ///
     /// # Notes
     ///
+    /// ## For streaming
+    ///
     /// This function will read all entries in the given directory. It could
     /// take very long time and consume a lot of memory if the directory
     /// contains a lot of entries.