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.mdindex 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 andstart 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 elsereplies to explicitly decide if there should be a mobile issueto track making a corresponding change in the mobile app,diff --git a/tools/lib/api_design_links.py b/tools/lib/api_design_links.pynew file mode 100644index 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 linksdiff --git a/tools/notify-if-api-docs-changed b/tools/notify-if-api-docs-changedindex 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_linksfrom 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.pynew file mode 100644index 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(""), [])