feat: preview the next release's announcement in a test group, without releasing

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Krzysztof Rudnicki 2026-08-30 21:41:44 +02:00
parent 9c6dbe7748
commit 69bd651ef9
2 changed files with 164 additions and 0 deletions

View File

@ -32,6 +32,15 @@ releases is free. The heading *name* is checked rather than trusted —
and the announcement reads `popes.json` regardless, so a typo here fails the
suite instead of reaching a group.
**Preview the announcement before you bump.** Because a bump is a publish,
the announcement was the one feature that could never be exercised first.
`tool/preview_release.py testbot` posts exactly what the next release would
say, into one test group, touching neither `RELEASE_ORDINAL` nor any
`announced_version` row; `--print-only` renders it without sending. It is
fail-closed on `SELFTEST_GROUPS`, so it cannot post a release that does not
exist into the group that would believe it. Write the `##` section below
first -- the preview reads it, so what you see is what ships.
**A release announcement is a photo now.** It carries the pope's portrait, his
Latin name and his pl.wikipedia article, the same three things `!papież` posts.
Only for the pope in the header: a backlog announcement lists up to ten
@ -62,6 +71,14 @@ this repo: describe what changes for them. 0.0.1 shipped a bullet about
`/healthz`, an endpoint bound to 127.0.0.1 that nobody in a Signal group can
reach, and it was rightly called out.
## 0.1.5 — Victor I
- ogłoszenie nowej wersji przychodzi teraz ze zdjęciem papieża, po którym ta
wersja się nazywa, i z linkiem do jego strony na polskiej Wikipedii —
dokładnie tak, jak robi to `!papież`
- wersje nazywają się od teraz po łacinie: ta jest «Victor I», a nie
«Wiktor I», a poprzednia była «Eleutherius», nie «Eleuteriusz»
## 0.1.4 — Eleutherius
- `!pomoc` (albo `!help`) wypisuje wszystkie komendy i mówi jednym zdaniem,

147
tool/preview_release.py Executable file
View File

@ -0,0 +1,147 @@
#!/usr/bin/env python3
# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence.
"""Post the *next* release's announcement into a test group, without releasing.
DOCS-changelog.md says a version bump is a publish, not a checkpoint: bumping
RELEASE_ORDINAL and restarting posts into every watched group at once,
including the real one. That leaves the announcement itself as the one feature
which could never be exercised before it shipped -- and it is now the feature
carrying a portrait, a Latin name and a link, so "it renders fine" is no longer
a safe assumption.
This sends exactly the bytes the real announcement would send, to one named
test group, and touches nothing else: RELEASE_ORDINAL is not bumped, no
group_meta row is written or read, and every other group hears nothing. Run it,
look at Signal, then bump for real.
tool/preview_release.py testbot
tool/preview_release.py testbot --ordinal 20 --print-only
Fail-closed the same way scripts/selftest.sh is: the group must be named in
SELFTEST_GROUPS, so this cannot post a release that does not exist into the
group that would believe it.
"""
from __future__ import annotations
import argparse
import asyncio
import os
import sys
from typing import Final
import httpx
from signal_bot.announce import render
from signal_bot.changelog import load, since
from signal_bot.config_env import load_config
from signal_bot.http_client import ImageFetcher
from signal_bot.portraits import PortraitCache
from signal_bot.selftest import allowed_groups
from signal_bot.transport_rest import RestTransport
from signal_bot.versioning import (
POPES,
RELEASE_ORDINAL,
__version__,
latin_name,
pope_for,
version_for,
)
EXIT_REFUSED: Final = 2
class PreviewError(RuntimeError):
"""Raised when the preview cannot be sent as asked."""
async def group_id_for(client: httpx.AsyncClient, groups_url: str, name: str) -> str:
"""Return the `group.<base64>=` id the transport addresses a group by.
Not internal_id, which is what selftest.resolve_group wants: that one goes
into an inbound envelope, this one goes into an outbound send.
"""
response = await client.get(groups_url)
response.raise_for_status()
for entry in response.json():
if entry.get("name") == name:
group_id = str(entry.get("id") or "")
if not group_id:
message = f"group {name!r} has no addressable id"
raise PreviewError(message)
return group_id
message = f"no group named {name!r}"
raise PreviewError(message)
def announcement_for(ordinal: int) -> str:
"""Return the message a release at ``ordinal`` would post, for a group here.
Keyed off the running version, because that is what every group is
recorded at, so this is the delta they would actually be shown.
"""
if not 1 <= ordinal <= len(POPES):
message = f"no pope with ordinal {ordinal}; the list has {len(POPES)}"
raise PreviewError(message)
pending = since(load(), __version__)
if not pending:
message = (
f"DOCS-changelog.md has nothing newer than {__version__}; "
f"add the ## {version_for(ordinal)} section first"
)
raise PreviewError(message)
return render(pope_for(ordinal), pending)
async def send_preview(group: str, ordinal: int, *, print_only: bool) -> None:
"""Render the announcement and, unless asked not to, post it."""
permitted = allowed_groups(os.environ)
if group not in permitted:
listed = ", ".join(sorted(permitted)) or "(none)"
message = f"{group!r} is not in SELFTEST_GROUPS; allowed: {listed}"
raise PreviewError(message)
pope = pope_for(ordinal)
text = announcement_for(ordinal)
sys.stdout.write(f"== {version_for(ordinal)} «{latin_name(pope)}» -> {group}\n")
sys.stdout.write(f"== caption: {len(text)} chars, {len(text.encode())} bytes\n")
sys.stdout.write(f"{text}\n")
if print_only:
sys.stdout.write("== not sent (--print-only)\n")
return
config = load_config()
async with httpx.AsyncClient(timeout=60.0) as client:
group_id = await group_id_for(client, config.groups_url, group)
portraits = PortraitCache(ImageFetcher(client), config.commons_api_url)
image = await portraits.get_base64(pope)
await RestTransport(config, client).send_image(image, group_id, caption=text)
sys.stdout.write(f"== sent to {group}; look at it in Signal\n")
def main() -> int:
"""Parse arguments and run one preview."""
parser = argparse.ArgumentParser(
description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter,
)
parser.add_argument("group", help="test group name; must be in SELFTEST_GROUPS")
parser.add_argument(
"--ordinal",
type=int,
default=None,
help="papal ordinal to preview (default: the next one after this build)",
)
parser.add_argument("--print-only", action="store_true", help="render it, send nothing")
args = parser.parse_args()
ordinal = RELEASE_ORDINAL + 1 if args.ordinal is None else args.ordinal
try:
asyncio.run(send_preview(args.group, ordinal, print_only=args.print_only))
except (PreviewError, httpx.HTTPError) as error:
sys.stderr.write(f"preview_release: {error}\n")
return EXIT_REFUSED
return 0
if __name__ == "__main__":
raise SystemExit(main())