feat(stack): improve stack comment design with table layout and branding (#1153)

Redesign the stack comment posted on PRs to use a markdown table instead
of a plain numbered list. The current PR is now bolded for better
scannability. The header links to Mergify Stacks documentation for
branding and discoverability.

The comment detection is backward-compatible: old-format comments
("part of a stack:") are still found and updated to the new format
on the next push.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jd

mergify_cli/stack/push.py

@@ -355,24 +355,33 @@ async def stack_push(
 class StackComment:
     pulls: list[github_types.PullRequest]
 
-    STACK_COMMENT_FIRST_LINE: typing.ClassVar[str] = (
+    _STACK_COMMENT_OLD_HEADER: typing.ClassVar[str] = (
         "This pull request is part of a stack:\n"
     )
 
+    STACK_COMMENT_HEADER: typing.ClassVar[str] = (
+        "This pull request is part of a [Mergify stack](https://docs.mergify.com/stacks/):\n"
+    )
+
     def body(self, current_pull: github_types.PullRequest) -> str:
-        body = self.STACK_COMMENT_FIRST_LINE
+        body = self.STACK_COMMENT_HEADER
+        body += "\n"
+        body += "| # | Pull Request | |\n"
+        body += "|--:|---|---|\n"
 
-        for pull in self.pulls:
-            body += f"1. {pull['title']} ([#{pull['number']}]({pull['html_url']}))"
-            if pull == current_pull:
-                body += " 👈"
-            body += "\n"
+        for i, pull in enumerate(self.pulls, 1):
+            title = pull["title"].replace("|", "\\|")
+            entry = f"{title} ([#{pull['number']}]({pull['html_url']}))"
+            status = "👈" if pull == current_pull else ""
+            body += f"| {i} | {entry} | {status} |\n"
 
         return body
 
     @staticmethod
     def is_stack_comment(comment: github_types.Comment) -> bool:
-        return comment["body"].startswith(StackComment.STACK_COMMENT_FIRST_LINE)
+        return comment["body"].startswith(
+            StackComment.STACK_COMMENT_HEADER,
+        ) or comment["body"].startswith(StackComment._STACK_COMMENT_OLD_HEADER)
 
 
 async def _update_comment_for_pull(

mergify_cli/tests/stack/test_push.py

@@ -155,19 +155,25 @@ async def test_stack_create(
 
     # First stack comment is created
     assert len(post_comment1_mock.calls) == 1
-    expected_body = """This pull request is part of a stack:
-1. Title commit 1 ([#1](https://github.com/repo/user/pull/1)) 👈
-1. Title commit 2 ([#2](https://github.com/repo/user/pull/2))
+    expected_body = """This pull request is part of a [Mergify stack](https://docs.mergify.com/stacks/):
+
+| # | Pull Request | |
+|--:|---|---|
+| 1 | Title commit 1 ([#1](https://github.com/repo/user/pull/1)) | 👈 |
+| 2 | Title commit 2 ([#2](https://github.com/repo/user/pull/2)) |  |
 """
     assert json.loads(post_comment1_mock.calls.last.request.content) == {
         "body": expected_body,
     }
 
     # Second stack comment is created
     assert len(post_comment2_mock.calls) == 1
-    expected_body = """This pull request is part of a stack:
-1. Title commit 1 ([#1](https://github.com/repo/user/pull/1))
-1. Title commit 2 ([#2](https://github.com/repo/user/pull/2)) 👈
+    expected_body = """This pull request is part of a [Mergify stack](https://docs.mergify.com/stacks/):
+
+| # | Pull Request | |
+|--:|---|---|
+| 1 | Title commit 1 ([#1](https://github.com/repo/user/pull/1)) |  |
+| 2 | Title commit 2 ([#2](https://github.com/repo/user/pull/2)) | 👈 |
 """
     assert json.loads(post_comment2_mock.calls.last.request.content) == {
         "body": expected_body,
@@ -297,7 +303,9 @@ async def test_stack_update_no_rebase(
             },
         ],
     )
-    respx_mock.patch("/repos/user/repo/issues/comments/456").respond(200)
+    patch_comment_mock = respx_mock.patch(
+        "/repos/user/repo/issues/comments/456",
+    ).respond(200)
 
     await push.stack_push(
         github_server="https://api.github.com/",
@@ -319,6 +327,13 @@ async def test_stack_update_no_rebase(
         "body": "Message",
     }
 
+    # Old-format stack comment is updated to new table format
+    assert len(patch_comment_mock.calls) == 1
+    comment_body = json.loads(patch_comment_mock.calls.last.request.content)["body"]
+    assert comment_body.startswith(
+        "This pull request is part of a [Mergify stack]",
+    )
+
 
 @pytest.mark.respx(base_url="https://api.github.com/")
 async def test_stack_update(