From f9d52189fcae82be9a4e7c9ff610d1888ef601f4 Mon Sep 17 00:00:00 2001
From: Vector73 <v.shm.kunal@gmail.com>
Date: Wed, 9 Jul 2025 06:33:52 +0000
Subject: [PATCH] github_actions: Check if feature levels are updated in API
 docs.

In the past, some API documentation changes were merged with
unresolved placeholders like "ZF-..." instead of actual feature level numbers.
This commit introduces a GitHub Action that scans the API docs for
any occurrence of "ZF-". If found, it will fail the CI check and block the
commit from being merged into main.

This ensures that all feature level references are properly updated before merging.
---
 .../workflows/check-feature-level-updated.yml | 46 +++++++++++++++++++
 tools/check-feature-level-updated             | 31 +++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 .github/workflows/check-feature-level-updated.yml
 create mode 100755 tools/check-feature-level-updated

diff --git a/.github/workflows/check-feature-level-updated.yml b/.github/workflows/check-feature-level-updated.yml
new file mode 100644
index 0000000000..f60c552b67
--- /dev/null
+++ b/.github/workflows/check-feature-level-updated.yml
@@ -0,0 +1,46 @@
+name: Check feature level updated
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "api_docs/**"
+  workflow_dispatch:
+
+jobs:
+  check-feature-level-updated:
+    runs-on: ubuntu-latest
+
+    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/check-feature-level-updated
+
+      - name: Run tools/check-feature-level-updated
+        id: run_check
+        run: ./tools/check-feature-level-updated >> $GITHUB_OUTPUT
+
+      - name: Report status to CZO
+        if: ${{ steps.run_check.outputs.fail == 'true' && 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: "automated testing"
+          topic: ${{ steps.run_check.outputs.topic }}
+          type: "stream"
+          content: ${{ steps.run_check.outputs.content }}
+
+      - name: Fail job if feature level not updated in API docs
+        if: ${{ steps.run_check.outputs.fail == 'true' }}
+        run: exit 1
diff --git a/tools/check-feature-level-updated b/tools/check-feature-level-updated
new file mode 100755
index 0000000000..99b2d6dfe5
--- /dev/null
+++ b/tools/check-feature-level-updated
@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+import os
+import sys
+from pathlib import Path
+
+
+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}"
+
+
+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")
+
+    api_docs_folder = Path("api_docs")
+    api_docs_paths = list(api_docs_folder.glob("*.md"))
+    api_docs_paths.append(Path("zerver/openapi/zulip.yaml"))
+
+    for api_docs_path in api_docs_paths:
+        with open(api_docs_path) as file:
+            if "ZF-" in file.read():
+                content = f"[Build]({build_url}) triggered by {github_actor} on branch `{branch}` has failed: Feature level not replaced in '{api_docs_path}'."
+                print(f"fail=true\ntopic={topic}\ncontent={content}")
+                sys.exit(0)
+
+    print("fail=false")