Skip to content

armgit / zulip

Public Imported from GitHub
0

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

tools: In new-feature-level bot posts, include `#api design` links.

Chris Bobbede2dbb995b70
diff --git a/docs/processes/api-design.md b/docs/processes/api-design.md
index 7ee244f985a..6bf5f509827 100644
--- a/docs/processes/api-design.md
+++ b/docs/processes/api-design.md
@@ -353,6 +353,8 @@ More details on the process are below.
If you're the author of a PR, please go ahead and
start the [#api design][] thread yourself.
Then put a link to it in the PR description.
+The bot that announces the change in [#api documentation][]
+picks the link up from there.
For any discussion that isn't specifically related to the API changes,
please use a different channel such as [#backend][]. (You can
@@ -445,7 +447,9 @@ and an API reviewer for most API changes.
See the corresponding subsections above.
After each API change is merged into the server,
-a bot will post a new thread in [#api documentation][].
+a bot will post a new thread in [#api documentation][],
+linking any [#api design][] discussions
+that the pull request's description mentions.
You should make sure you or someone else
replies to explicitly decide if there should be a mobile issue
to track making a corresponding change in the mobile app,
diff --git a/tools/lib/api_design_links.py b/tools/lib/api_design_links.py
new file mode 100644
index 00000000000..57e2e644428
--- /dev/null
+++ b/tools/lib/api_design_links.py
@@ -0,0 +1,66 @@
+"""Recognize links to conversations in the #api design channel.
+
+Our API-design policy asks that every API change be discussed and
+approved there; see docs/processes/api-design.md.
+"""
+
+import re
+from urllib.parse import urlsplit
+
+# The Zulip development community, where the #api design channel lives.
+CZO_URL = "https://chat.zulip.org"
+API_DESIGN_CHANNEL_ID = "378"
+
+# A candidate to examine: CZO_URL and everything up to the next
+# whitespace. Deliberately loose, since prose leaves punctuation stuck
+# to a link; is_api_design_link makes the real decision.
+CANDIDATE_LINK = re.compile(rf"{re.escape(CZO_URL)}/\S+")
+
+# Punctuation to strip from the end of a candidate link. A narrow link
+# never ends in one of these, because encodeHashComponent turns each into
+# a dot-escape like ".29" or ".3F", which ends in a hex digit. See
+# web/src/internal_url.ts.
+TRAILING_PUNCTUATION = ")]}>,;:!?'\"*."
+
+
+def is_api_design_link(candidate_url: str) -> bool:
+ """Whether this string is a link to a conversation in the #api design channel.
+
+ Returns False for anything else, including a string that isn't a URL.
+ """
+ try:
+ parts = urlsplit(candidate_url)
+ except ValueError:
+ # Some malformed URLs, like "https://[", can't be parsed at all.
+ return False
+ if f"{parts.scheme}://{parts.netloc}" != CZO_URL:
+ return False
+ if parts.path not in ("", "/"):
+ return False
+
+ # A narrow link's fragment is "narrow" followed by operator/operand
+ # pairs, like "narrow/channel/378-api-design/topic/some.20topic".
+ # See search_terms_to_hash in web/src/hash_util.ts.
+ segments = parts.fragment.split("/")
+ if segments[0] != "narrow":
+ return False
+ operands = {segments[i]: segments[i + 1] for i in range(1, len(segments) - 1, 2)}
+
+ # The operand is the channel's ID, optionally followed by its name.
+ # Zulip called channels streams until 2024 (see commit d3987f611).
+ channel = operands.get("channel", operands.get("stream"))
+ if channel is None or channel.split("-")[0] != API_DESIGN_CHANNEL_ID:
+ return False
+
+ # Require a topic.
+ return "topic" in operands
+
+
+def find_api_design_links(text: str) -> list[str]:
+ """Return the #api design conversations linked in this text, in order."""
+ links: list[str] = []
+ for candidate in CANDIDATE_LINK.findall(text):
+ link = candidate.rstrip(TRAILING_PUNCTUATION)
+ if is_api_design_link(link) and link not in links:
+ links.append(link)
+ return links
diff --git a/tools/notify-if-api-docs-changed b/tools/notify-if-api-docs-changed
index 97e88062c60..b9f7d6cf351 100755
--- a/tools/notify-if-api-docs-changed
+++ b/tools/notify-if-api-docs-changed
@@ -12,6 +12,7 @@ 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 tools.lib.api_design_links import find_api_design_links
from zerver.openapi.merge_api_changelogs import get_feature_level
@@ -104,7 +105,17 @@ if __name__ == "__main__":
)
changelog_entries = get_changelog_entries()
+ discussion_links: list[str] = []
+ if pull_request.body:
+ discussion_links = find_api_design_links(pull_request.body)
+
content = f"{pull_request_label} has updated the API documentation for the following endpoints: \n{changelog_entries}"
+ if len(discussion_links) == 1:
+ content += f"\n\nAPI design discussion: {discussion_links[0]}"
+ elif discussion_links:
+ content += "\n\nAPI design discussions:\n" + "\n".join(
+ f"- {link}" for link in discussion_links
+ )
github_output = os.environ.get("GITHUB_OUTPUT")
if github_output:
with open(github_output, "a") as f:
diff --git a/tools/tests/test_api_design_links.py b/tools/tests/test_api_design_links.py
new file mode 100644
index 00000000000..f9f30091592
--- /dev/null
+++ b/tools/tests/test_api_design_links.py
@@ -0,0 +1,103 @@
+import unittest
+
+from tools.lib.api_design_links import find_api_design_links, is_api_design_link
+
+API_DESIGN = "https://chat.zulip.org/#narrow/channel/378-api-design"
+
+
+class TestIsApiDesignLink(unittest.TestCase):
+ def test_conversations_in_the_channel(self) -> None:
+ for url in [
+ f"{API_DESIGN}/topic/some.20topic",
+ f"{API_DESIGN}/topic/some.20topic/near/12345",
+ f"{API_DESIGN}/topic/some.20topic/with/12345",
+ f"{API_DESIGN}/topic/some.20topic/",
+ # A link to the channel's "general chat", whose topic is empty.
+ f"{API_DESIGN}/topic/",
+ # The channel's ID identifies it; the name that follows is decoration.
+ "https://chat.zulip.org/#narrow/channel/378/topic/x",
+ # Zulip called channels streams until 2024.
+ "https://chat.zulip.org/#narrow/stream/378-api-design/topic/x",
+ ]:
+ with self.subTest(url=url):
+ self.assertTrue(is_api_design_link(url))
+
+ def test_other_links(self) -> None:
+ for url in [
+ # The channel as a whole, naming no conversation in it.
+ API_DESIGN,
+ f"{API_DESIGN}/",
+ "https://chat.zulip.org/#narrow/channel/3-backend/topic/x",
+ # A channel whose ID merely starts with the same digits.
+ "https://chat.zulip.org/#narrow/channel/3780-other/topic/x",
+ # A channel operator with no operand.
+ "https://chat.zulip.org/#narrow/channel",
+ "https://chat.zulip.org/#narrow",
+ "https://chat.zulip.org/",
+ "https://chat.zulip.org/api/get-messages",
+ # Not the realm's root, so not a narrow link.
+ "https://chat.zulip.org/somepage#narrow/channel/378-api-design",
+ "https://example.com/#narrow/channel/378-api-design/topic/x",
+ "not a URL at all",
+ "",
+ ]:
+ with self.subTest(url=url):
+ self.assertFalse(is_api_design_link(url))
+
+ def test_unparseable_urls(self) -> None:
+ # urlsplit rejects these outright, rather than returning parts.
+ for url in [
+ # An IPv6 host with no closing bracket.
+ "https://[",
+ "http://[::1",
+ # A host whose characters change under NFKC normalization.
+ "https://chat.zulip.org℀/#narrow/channel/378-api-design/topic/x",
+ ]:
+ with self.subTest(url=url):
+ self.assertFalse(is_api_design_link(url))
+
+
+class TestFindApiDesignLinks(unittest.TestCase):
+ def test_markdown_link(self) -> None:
+ text = f"Bug fix as discussed in [#api design > topic]({API_DESIGN}/topic/x/near/1)."
+ self.assertEqual(find_api_design_links(text), [f"{API_DESIGN}/topic/x/near/1"])
+
+ def test_trailing_punctuation(self) -> None:
+ # None of these characters can appear in a narrow link itself, so
+ # each came from the text around one.
+ for suffix in [".", ",", ")", "]", ">", "?", "!", "**", "'", '"', ");"]:
+ with self.subTest(suffix=suffix):
+ text = f"See {API_DESIGN}/topic/x{suffix} Thanks!"
+ self.assertEqual(find_api_design_links(text), [f"{API_DESIGN}/topic/x"])
+
+ def test_returns_each_link_once_in_order(self) -> None:
+ text = f"""
+ First {API_DESIGN}/topic/a/near/1
+ then {API_DESIGN}/topic/b/near/2
+ and {API_DESIGN}/topic/a/near/1 again.
+ """
+ self.assertEqual(
+ find_api_design_links(text),
+ [f"{API_DESIGN}/topic/a/near/1", f"{API_DESIGN}/topic/b/near/2"],
+ )
+
+ def test_link_to_the_channel_itself(self) -> None:
+ # A link to the channel names no discussion, so it's dropped even
+ # alongside a link to a real thread.
+ text = f"""
+ Discussed in [#api design > some topic]({API_DESIGN}/topic/x/near/1).
+
+ [#api design]: {API_DESIGN}
+ """
+ self.assertEqual(find_api_design_links(text), [f"{API_DESIGN}/topic/x/near/1"])
+
+ def test_links_to_elsewhere(self) -> None:
+ text = """
+ Fixes #1234. Discussed with the team in
+ https://chat.zulip.org/#narrow/channel/3-backend/topic/x
+ and see https://zulip.com/api/send-message .
+ """
+ self.assertEqual(find_api_design_links(text), [])
+
+ def test_no_text(self) -> None:
+ self.assertEqual(find_api_design_links(""), [])