diff --git a/lib/api/model/model.dart b/lib/api/model/model.dart
index c93c024852..169bc618f1 100644
--- a/lib/api/model/model.dart
+++ b/lib/api/model/model.dart
@@ -312,6 +312,14 @@ enum UserRole{
 /// in <https://zulip.com/api/register-queue>.
 @JsonSerializable(fieldRename: FieldRename.snake)
 class ZulipStream {
+  // When adding a field to this class:
+  //  * If a [ChannelUpdateEvent] can update it, be sure to add
+  //    that case as a field of [ChannelUpdateEvent] or as a new value to
+  //    [ChannelPropertyName] enum; based on what the stream-update API suggests.
+  //  * If the field can never change for a given Zulip stream, mark it final.
+  //  * (If it can change but [ChannelUpdateEvent] doesn't cover that,
+  //    then that's a bug in the API; raise it in `#api design`.)
+
   final int streamId;
   String name;
   String description;