From 9fa57fd24aa0a2de5fd5d8dbffc72be00fc2e178 Mon Sep 17 00:00:00 2001
From: Lauryn Menard <lauryn@zulip.com>
Date: Tue, 11 Feb 2025 20:37:33 +0100
Subject: [PATCH] api-docs: Update feature level 329 changelog entry and
 related notes.

Clarifies that the alert is shown if the current time displayed by
the time zone configured on the user's device differs from the
time displayed for the users's profile time zone.

Removes incorrectly having web_suggest_update_timezone as a separate
field returned by the POST /register response. It will only be a
field in the user_settings and realm_user_settings_defaults objects.
---
 api_docs/changelog.md     |  8 +++++---
 zerver/openapi/zulip.yaml | 31 ++++++++++++++++---------------
 2 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/api_docs/changelog.md b/api_docs/changelog.md
index d4da8d5590..f4580a10eb 100644
--- a/api_docs/changelog.md
+++ b/api_docs/changelog.md
@@ -301,9 +301,11 @@ deactivated groups.
 
 * [`PATCH /realm/user_settings_defaults`](/api/update-realm-user-settings-defaults),
   [`POST /register`](/api/register-queue), [`PATCH /settings`](/api/update-settings):
-  Added new `web_suggest_update_timezone` option to decide whether the user should be
-  shown an alert offering to update their profile time zone to the time zone of the
-  browser in case they differ.
+  Added new `web_suggest_update_timezone` user setting to indicate whether
+  the user should be shown an alert, offering to update their [profile
+  time zone](/help/change-your-timezone), when the time displayed for the
+  profile time zone differs from the current time displayed by the time
+  zone configured on their device.
 
 **Feature level 328**
 
diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index e1bc171f80..0fa59e0d08 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -12223,8 +12223,10 @@ paths:
                   example: true
                 web_suggest_update_timezone:
                   description: |
-                    Whether the user should be shown an alert offering to update their profile time zone
-                    to the time zone of the browser in case they differ.
+                    Whether the user should be shown an alert, offering to update their
+                    [profile time zone](/help/change-your-timezone), when the time displayed
+                    for the profile time zone differs from the current time displayed by the
+                    time zone configured on their device.
 
                     **Changes**: New in Zulip 10.0 (feature level 329).
                   type: boolean
@@ -15652,8 +15654,10 @@ paths:
                           web_suggest_update_timezone:
                             type: boolean
                             description: |
-                              Whether the user should be shown an alert offering to update their profile time zone
-                              to the time zone of the browser in case they differ.
+                              Whether the user should be shown an alert, offering to update their
+                              [profile time zone](/help/change-your-timezone), when the time displayed
+                              for the profile time zone differs from the current time displayed by the
+                              time zone configured on their device.
 
                               **Changes**: New in Zulip 10.0 (feature level 329).
                           fluid_layout_width:
@@ -16781,13 +16785,6 @@ paths:
 
                           **Changes**: New in Zulip 9.0 (feature level 253). Previously, there were
                           only options to disable sending typing notifications.
-                      web_suggest_update_timezone:
-                        type: boolean
-                        description: |
-                          Whether the user should be shown an alert offering to update their profile time zone
-                          to the time zone of the browser in case they differ.
-
-                          **Changes**: New in Zulip 10.0 (feature level 329).
                       enter_sends:
                         deprecated: true
                         type: boolean
@@ -18318,8 +18315,10 @@ paths:
                           web_suggest_update_timezone:
                             type: boolean
                             description: |
-                              Whether the user should be shown an alert offering to update their profile time zone
-                              to the time zone of the browser in case they differ.
+                              Whether the user should be shown an alert, offering to update their
+                              [profile time zone](/help/change-your-timezone), when the time displayed
+                              for the profile time zone differs from the current time displayed by the
+                              time zone configured on their device.
 
                               **Changes**: New in Zulip 10.0 (feature level 329).
                           fluid_layout_width:
@@ -19487,8 +19486,10 @@ paths:
                 web_suggest_update_timezone:
                   type: boolean
                   description: |
-                    Whether the user should be shown an alert offering to update their profile time zone
-                    to the time zone of the browser in case they differ.
+                    Whether the user should be shown an alert, offering to update their
+                    [profile time zone](/help/change-your-timezone), when the time displayed
+                    for the profile time zone differs from the current time displayed by the
+                    time zone configured on their device.
 
                     **Changes**: New in Zulip 10.0 (feature level 329).
                   example: true