github_actions: Add a GitHub action for notifying if API docs changed.

.github/workflows/api-docs-update-check.yml

@@ -1,4 +1,4 @@
-name: Check feature level updated
+name: API Documentation Update Check
 
 on:
   push:
@@ -7,6 +7,9 @@ on:
       - "api_docs/**"
   workflow_dispatch:
 
+permissions:
+  contents: read
+
 jobs:
   check-feature-level-updated:
     runs-on: ubuntu-latest
@@ -22,9 +25,6 @@ jobs:
         with:
           python-version: "3.x"
 
-      - name: Add required permissions
-        run: chmod +x ./tools/check-feature-level-updated
-
       - name: Run tools/check-feature-level-updated
         id: run_check
         run: ./tools/check-feature-level-updated >> $GITHUB_OUTPUT
@@ -44,3 +44,37 @@ jobs:
       - name: Fail job if feature level not updated in API docs
         if: ${{ steps.run_check.outputs.fail == 'true' }}
         run: exit 1
+
+  notify-if-api-docs-changed:
+    runs-on: ubuntu-latest
+    needs: check-feature-level-updated
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+
+      - name: Add required permissions
+        run: chmod +x ./tools/notify-if-api-docs-changed
+
+      - name: Run tools/notify-if-api-docs-changed
+        id: run_check
+        run: ./tools/notify-if-api-docs-changed >> $GITHUB_OUTPUT
+
+      - name: Report status to CZO
+        if: ${{github.repository == 'zulip/zulip'}}
+        uses: zulip/github-actions-zulip/send-message@v1
+        with:
+          api-key: ${{ secrets.ZULIP_BOT_KEY }}
+          email: "github-actions-bot@chat.zulip.org"
+          organization-url: "https://chat.zulip.org"
+          to: "api documentation"
+          topic: ${{ steps.run_check.outputs.topic }}
+          type: "stream"
+          content: ${{ steps.run_check.outputs.content }}

tools/notify-if-api-docs-changed

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+import os
+import re
+import sys
+from pathlib import Path
+
+TOOLS_DIR = os.path.dirname(os.path.abspath(__file__))
+os.chdir(os.path.dirname(TOOLS_DIR))
+sys.path.insert(0, os.path.dirname(TOOLS_DIR))
+
+from zerver.openapi.merge_api_changelogs import get_feature_level
+
+
+def get_build_url_from_environment() -> str:
+    server = os.environ["GITHUB_SERVER_URL"]
+    repo = os.environ["GITHUB_REPOSITORY"]
+    run_id = os.environ["GITHUB_RUN_ID"]
+    return f"{server}/{repo}/actions/runs/{run_id}"
+
+
+def get_changed_api_endpoints() -> list[str]:
+    changelog_path = Path("api_docs/changelog.md")
+    feature_level_pattern = re.compile(r"\*\*Feature level \d+\*\*")
+    link_pattern = re.compile(r"(\[[^\]]+\]\([^)]+\))")
+
+    current_feature_level_found = False
+    endpoints = []
+
+    with open(changelog_path) as file:
+        for line in file:
+            if re.fullmatch(feature_level_pattern, line.strip()):
+                if current_feature_level_found:
+                    break
+                current_feature_level_found = True
+                continue
+
+            if current_feature_level_found and line.strip().startswith("*"):
+                endpoints.extend(link_pattern.findall(line.split(":", 1)[0]))
+
+    return endpoints
+
+
+if __name__ == "__main__":
+    branch = os.environ.get("GITHUB_REF", "unknown branch").split("/")[-1]
+    topic = f"{branch} failing"
+    build_url = get_build_url_from_environment()
+    github_actor = os.environ.get("GITHUB_ACTOR", "unknown user")
+
+    feature_level = get_feature_level(update_feature_level=False)
+    endpoints = get_changed_api_endpoints()
+    topic = f"new feature level: {feature_level}"
+    endpoints_string = ", ".join(endpoints)
+
+    content = f"[Build]({build_url}) triggered by {github_actor} on branch `{branch}` has updated the API documentation for the following endpoints: {endpoints_string}."
+    print(f"topic={topic}\ncontent={content}")