From c0be6c6b9873e1fad3e3663b8cf1e24b007ece69 Mon Sep 17 00:00:00 2001 From: Lauryn Menard Date: Fri, 5 Jan 2024 17:07:50 +0100 Subject: [PATCH] api-docs: Clean up feature level 233 and 230 documentation. Updates the API changelog entries and changes notes for feature levels 233 and 230, which both are related to the onboarding steps (hotspots and one-time notices) updates. Feature level 233 was originally documented in commit 83bd9955e3 and ac8af3d6de. Feature level 230 was originally documented in commit 8d633cc36. --- api_docs/changelog.md | 35 +++++++++++--------- zerver/openapi/zulip.yaml | 68 +++++++++++++++++++++++++-------------- 2 files changed, 62 insertions(+), 41 deletions(-) diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 5bdc4ac60d..fd6bed63a1 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -172,20 +172,22 @@ No changes; feature level used for Zulip 8.0 release. **Feature level 233** * [`POST /register`](/api/register-queue), [`GET /events`](/api/get-events): - Renamed the event type `hotspots` and the `hotspots` array field in it - to `onboarding_steps` as this event is sent to clients with remaining - onboarding steps data that includes hotspots and one-time notices to display. - Earlier, we had hotspots only. Added a `type` field to the objects in - the renamed `onboarding_steps` array to distinguish between the two type - of onboarding steps. + Renamed the `hotspots` event type and the related `hotspots` object array + to `onboarding_steps`. These are sent to clients if there are onboarding + steps to display to the user. Onboarding steps now include + both hotspots and one-time notices. Prior to this, hotspots were the only + type of onboarding step. Also, added a `type` field to the objects + returned in the renamed `onboarding_steps` array to distinguish between + the two types of onboarding steps. -* `POST /users/me/onboarding_steps`: Added a new endpoint that - deprecates the `/users/me/hotspots` endpoint. Added support for - displaying one-time notices in addition to existing hotspots. - This is now used as a common endpoint to mark both types of - onboarding steps, i.e., 'hotspot' and 'one_time_notice'. - There is no compatibility support for `/users/me/hotspots` as - no client other than web app has this feature currently. +* `POST /users/me/onboarding_steps`: Added a new endpoint, which + deprecates the `/users/me/hotspots` endpoint, in order to support + displaying both one-time notices (which highlight new features for + existing users) and hotspots (which are used in new user tutorials). + This endpoint marks both types of onboarding steps, i.e. `hotspot` + and `one_time_notice`, as read by the user. There is no compatibility + support for `/users/me/hotspots` as no client other than the Zulip + web app used the endpoint prior to these changes. **Feature level 232** @@ -219,9 +221,10 @@ No changes; feature level used for Zulip 8.0 release. **Feature level 230** -* [`GET /events`](/api/get-events): Added `has_trigger` field in - hotspots events to identify if a hotspot will activate only when - some specific event occurs. +* [`POST /register`](/api/register-queue), [`GET /events`](/api/get-events): + Added `has_trigger` field to objects returned in the `hotspots` array to + identify if the hotspot will activate only when some specific event + occurs. **Feature level 229** diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index f5738a25cf..deacc30377 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -2291,14 +2291,15 @@ paths: - type: object additionalProperties: false description: | - Event sent when the set of onboarding steps to show for - the current user have changed (E.g. because the user dismissed one). + Event sent when the set of onboarding steps to show for the current user + has changed (e.g. because the user dismissed one). - Clients that feature a similar tutorial experience to the Zulip - web app may want to handle these events. + Clients that feature a similar tutorial experience to the Zulip web app + may want to handle these events. - **Changes**: Before Zulip 8.0 (feature level 233), this was named - as `Hotspots`. One-time notice wasn't available earlier. + **Changes**: Before Zulip 8.0 (feature level 233), this event was named + `hotspots`. Prior to this feature level, one-time notice onboarding + steps were not supported. properties: id: $ref: "#/components/schemas/EventIdSchema" @@ -2310,11 +2311,13 @@ paths: onboarding_steps: type: array description: | - An array of dictionaries where each - dictionary contains details about a single onboarding step. + An array of dictionaries where each dictionary contains details about a + single onboarding step. - **Changes**: Before Zulip 8.0 (feature level 233), this array - was named as `hotspots`. One-time notice wasn't available earlier. + **Changes**: Before Zulip 8.0 (feature level 233), this array was named + `hotspots`. Prior to this feature level, one-time notice onboarding + steps were not supported, and the `type` field in these objects did not + exist as all onboarding steps were implicitly hotspots. items: $ref: "#/components/schemas/OnboardingStep" example: @@ -2324,12 +2327,16 @@ paths: [ { "type": "hotspot", - "name": "intro_streams", - "title": "Catch up on a stream", - "description": "Messages sent to a stream are seen by everyone subscribed to that stream. Try clicking on one of the stream links below.", + "name": "intro_compose", + "title": "Compose", + "description": "Click here to start a new conversation. Pick a topic (2-3 words is best), and give it a go!", "delay": 0.5, "has_trigger": false, }, + { + "type": "one_time_notice", + "name": "visibility_policy_banner", + }, ], "id": 0, } @@ -12610,9 +12617,14 @@ paths: Present if `onboarding_steps` is present in `fetch_event_types`. An array of dictionaries, where each dictionary contains details about - a single onboarding step that should be shown to new users. + a single onboarding step that should be shown to the user. - We expect that only official Zulip clients will interact with these data. + We expect that only official Zulip clients will interact with this data. + + **Changes**: Before Zulip 8.0 (feature level 233), this array was named + `hotspots`. Prior to this feature level, one-time notice onboarding + steps were not supported, and the `type` field in these objects did not + exist as all onboarding steps were implicitly hotspots. items: $ref: "#/components/schemas/OnboardingStep" max_message_id: @@ -19574,39 +19586,45 @@ components: additionalProperties: false description: | Dictionary containing details of a single onboarding step. - - **Changes**: Before Zulip 8.0 (feature level 233), this was - named as `Hotspot`. One-time notice wasn't available earlier. properties: type: type: string description: | The type of the onboarding step. Valid values are either - 'hotspot' or 'one_time_notice'. + `"hotspot"` or `"one_time_notice"`. **Changes**: New in Zulip 8.0 (feature level 233). name: type: string description: | - The name of the hotspot. + The name of the onboarding step. title: type: string description: | - The title of the hotspot, as will be displayed to the user. + The title of the onboarding step, as displayed to the user. + + Only present for onboarding steps with type `"hotspot"`. description: type: string description: | - The description of the hotspot, as will be displayed to the + The description of the onboarding step, as displayed to the user. + + Only present for onboarding steps with type `"hotspot"`. delay: type: number description: | - The delay after which the user should be shown the hotspot. + The delay, in seconds, after which the user should be shown + the onboarding step. + + Only present for onboarding steps with type `"hotspot"`. has_trigger: type: boolean description: | - The has_trigger is used to identify if the hotspot will activate - only when some specific event occurs. + Identifies if the onboarding step will activate only when some + specific event occurs. + + Only present for onboarding steps with type `"hotspot"`. **Changes**: New in Zulip 8.0 (feature level 230). RealmAuthenticationMethod: