From c5c1b7958071632a54c6843169062fa32afa7259 Mon Sep 17 00:00:00 2001
From: Vector73 <v.shm.kunal@gmail.com>
Date: Wed, 21 May 2025 13:36:33 +0000
Subject: [PATCH] tools: Update docs for create-api-changelog tool.

---
 docs/documentation/api.md  | 23 ++++++++++++++++-------
 tools/create-api-changelog |  3 +++
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/docs/documentation/api.md b/docs/documentation/api.md
index 608d82d59f..3a030a67eb 100644
--- a/docs/documentation/api.md
+++ b/docs/documentation/api.md
@@ -334,14 +334,23 @@ above.
    post an example of the output in the pull request.
 
 1. Run `./tools/create-api-changelog` which will create a new empty
-   changelog file in `api_docs/unmerged.d/` directory. Open this
-   file and document the API changes. The content of this file will be
-   merged into `api_docs/changelog.md` when your commit is merged into the
-   `main` branch.
+   markdown file in `api_docs/unmerged.d/` directory
+   (e.g., `api_docs/unmerged.d/ZF-1f4a39.md`). Open this
+   file and document the API changes, formatted as an unordered list
+   (`*` bullets). The raw content of this file will be merged into
+   `api_docs/changelog.md` when your commit is merged into the `main`
+   branch. Therefore, keep the formatting and line wrapping consistent
+   with the content in `api_docs/changelog.md`.
 
-1. Add a `**Changes**` entry in the description of the new API/event in
-   `zerver/openapi/zulip.yaml`, and mention the name of the file generated
-   in the previous step in place of the API feature level.
+1. Add a `**Changes**` note in the description of all updates and
+   additions to the API documentation (`zerver/openapi/zulip.yaml`),
+   and mention the name of the file generated in the previous step
+   (without the `.md` extension) in place of the API feature level,
+   for example:
+
+   ```yaml
+   **Changes**: New in Zulip 11.0 (feature level ZF-1f4a39).
+   ```
 
 ## Why a custom system?
 
diff --git a/tools/create-api-changelog b/tools/create-api-changelog
index 37ee373277..269f313966 100755
--- a/tools/create-api-changelog
+++ b/tools/create-api-changelog
@@ -28,5 +28,8 @@ if __name__ == "__main__":
         f"""Created an empty API changelog file.
 If you've made changes to the API, document them here:
 {file_path}
+
+For help, see:
+    https://zulip.readthedocs.io/en/latest/documentation/api.html#step-by-step-guide
 """
     )