mirror of
https://github.com/Abdess/retroarch_system.git
synced 2026-11-16 06:44:43 -06:00
docs: lead the release notes with the command
The notes open on the command and the handheld app, then the full packs for a device without internet, the setups the command alone serves, what changed, everyone who helped since the start (read with gh, --thanks FILE for a checked list) in a folded block, and the full changelog from the previous release's record commit.
This commit is contained in:
1 parent
962f18ac3f
commit
d5c2ba266f
2 files changed
+282
-16
No files matched your search
+143
-12
@@ -11,6 +11,14 @@ idea per line, plain words (owner, 2026-11-10). The maintainer writes
|
||||
what changed, and that text is appended as given once it holds none of the
|
||||
REFUSED phrases.
|
||||
|
||||
The notes end with the people to thank and the full changelog, from the
|
||||
previous release's record commit (the first commit release.json gave the
|
||||
previous tag) to the new tag. The thanks name everyone who helped since the
|
||||
repository started, read with gh: a login is only ever the one GitHub links
|
||||
to the work, never one guessed from a git author name. The owner, bots and
|
||||
spam are left out (LEFT_OUT). --thanks FILE passes a checked list instead
|
||||
of the one gh gives.
|
||||
|
||||
Usage:
|
||||
python scripts/release_notes.py --whats-new tmp/whats-new.md --output notes.md
|
||||
"""
|
||||
@@ -18,8 +26,11 @@ Usage:
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from collections.abc import Callable
|
||||
from pathlib import Path
|
||||
|
||||
import release_record
|
||||
@@ -34,7 +45,12 @@ from common import (
|
||||
from siteguides import install_command
|
||||
|
||||
REPO = "Abdess/retrobios"
|
||||
OWNER = "Abdess"
|
||||
SITE = "https://abdess.github.io/retrobios/"
|
||||
# The handheld app is served by the site, built from its own commit, never
|
||||
# attached to a release. The installer's handheld section opens on the
|
||||
# download of every system.
|
||||
HANDHELD_PAGE = "wiki/installer/#on-a-handheld-the-retrobios-port"
|
||||
|
||||
|
||||
def _size(count: int) -> str:
|
||||
@@ -79,14 +95,18 @@ def without_pack(platforms_dir: str) -> list[str]:
|
||||
|
||||
|
||||
def no_pack_paragraph(platforms_dir: str) -> list[str]:
|
||||
"""One paragraph naming the setups served by the command alone."""
|
||||
"""One paragraph naming the setups served by the command alone. The
|
||||
packs published are the most downloaded ones (wiki/release-process.md,
|
||||
"Which platforms get a pack"). The command reads the install manifest,
|
||||
which the pack builder writes from the same resolution as the pack."""
|
||||
names = without_pack(platforms_dir)
|
||||
if not names:
|
||||
return []
|
||||
listed = ", ".join(names[:-1]) + f" and {names[-1]}" if len(names) > 1 else names[0]
|
||||
return [
|
||||
(f"No ZIP for {listed}. The command above installs them."
|
||||
" Add `--dry-run` to see what it would do."),
|
||||
("Only the most used setups have a pack, to keep the release small."
|
||||
f" For {listed}, use the command above. It reads the same file list a pack"
|
||||
" is built from."),
|
||||
"",
|
||||
]
|
||||
|
||||
@@ -119,31 +139,126 @@ def refused_words(text: str) -> list[str]:
|
||||
return [phrase for phrase in REFUSED if phrase in lowered]
|
||||
|
||||
|
||||
def render(record: dict, platforms_dir: str, whats_new: str) -> str:
|
||||
Run = Callable[[list[str]], str]
|
||||
|
||||
|
||||
def _run(argv: list[str]) -> str:
|
||||
return subprocess.run(argv, capture_output=True, text=True, check=True).stdout
|
||||
|
||||
|
||||
def previous_record_commit(tag: str, run: Run | None = None) -> str:
|
||||
"""The commit that recorded the release before *tag*: the oldest commit
|
||||
of the run of release.json changes that name the previous tag."""
|
||||
run = run or _run
|
||||
shas = run(["git", "log", "--format=%H", "--", "release.json"]).split()
|
||||
previous, base = None, None
|
||||
for sha in shas:
|
||||
recorded = json.loads(run(["git", "show", f"{sha}:release.json"])).get("tag")
|
||||
if previous is None:
|
||||
if recorded != tag:
|
||||
previous, base = recorded, sha
|
||||
elif recorded == previous:
|
||||
base = sha
|
||||
else:
|
||||
break
|
||||
if base is None:
|
||||
raise ValueError(f"release.json records no release before {tag}")
|
||||
return base
|
||||
|
||||
|
||||
# Accounts that never helped: the owner's own, GitHub's placeholder for a
|
||||
# deleted account, and spam (issue 32 by Bappo0 and pull request 67 by
|
||||
# prakashmagat50-byte, both empty or garbage).
|
||||
LEFT_OUT = frozenset(("Abdess", "Abdess76", "ghost", "Bappo0", "prakashmagat50-byte"))
|
||||
|
||||
|
||||
def _person(login: str | None) -> str | None:
|
||||
"""The login to thank, None for the owner, a bot, a deleted account,
|
||||
spam, or work GitHub links to no account."""
|
||||
if not login or login in LEFT_OUT or login.endswith("[bot]") or login.startswith("app/"):
|
||||
return None
|
||||
return login
|
||||
|
||||
|
||||
def _logins(text: str) -> set[str]:
|
||||
"""One login per line, as `gh api --paginate --jq` prints them."""
|
||||
return {person for line in text.splitlines() if (person := _person(line.strip()))}
|
||||
|
||||
|
||||
def _authors(text: str) -> set[str]:
|
||||
"""The authors of a `gh pr list` or `gh issue list --json author`."""
|
||||
return {person for item in json.loads(text)
|
||||
if not (item.get("author") or {}).get("is_bot")
|
||||
and (person := _person((item.get("author") or {}).get("login")))}
|
||||
|
||||
|
||||
def gather_thanks(run: Run | None = None, repo: str = REPO) -> list[str]:
|
||||
"""Everyone who helped since the repository started, each named once:
|
||||
commit authors as the commits API links them to an account and every
|
||||
pull request author, merged or not, then issue authors, then whoever
|
||||
commented on an issue or a pull request."""
|
||||
run = run or _run
|
||||
code = _logins(run(["gh", "api", "--paginate", f"repos/{repo}/commits",
|
||||
"--jq", ".[] | .author.login // empty"]))
|
||||
code |= _authors(run(["gh", "pr", "list", "-R", repo, "--state", "all",
|
||||
"--limit", "10000", "--json", "number,author"]))
|
||||
reports = _authors(run(["gh", "issue", "list", "-R", repo, "--state", "all",
|
||||
"--limit", "10000", "--json", "number,author"])) - code
|
||||
helped = set()
|
||||
for path in (f"repos/{repo}/issues/comments", f"repos/{repo}/pulls/comments"):
|
||||
helped |= _logins(run(["gh", "api", "--paginate", path, "--jq", ".[] | .user.login"]))
|
||||
helped -= code | reports
|
||||
lines = []
|
||||
for label, people in (("Code and data", code), ("Reports", reports),
|
||||
("Help in issues", helped)):
|
||||
if people:
|
||||
names = [f"@{login}" for login in sorted(people, key=str.casefold)]
|
||||
listed = names[0] if len(names) == 1 else f"{', '.join(names[:-1])} and {names[-1]}"
|
||||
lines.append(f"- **{label}**: {listed}.")
|
||||
return lines
|
||||
|
||||
|
||||
def changelog_url(base: str, tag: str, repo: str = REPO) -> str:
|
||||
return f"https://github.com/{repo}/compare/{base[:9]}...{tag}"
|
||||
|
||||
|
||||
def closing_lines(thanks: list[str], changelog: str) -> list[str]:
|
||||
"""The Thanks section, left out when nobody is to thank, and the full
|
||||
changelog line."""
|
||||
# Folded: the lists run to a hundred names. GitHub renders the markdown
|
||||
# inside only with a blank line on each side of it.
|
||||
lines = (["### Thanks", "", "<details>",
|
||||
"<summary>Everyone who helped since the start</summary>", "",
|
||||
*thanks, "", "</details>", ""]
|
||||
if thanks else [])
|
||||
return [*lines, f"**Full changelog**: {changelog}", ""]
|
||||
|
||||
|
||||
def render(record: dict, platforms_dir: str, whats_new: str,
|
||||
closing: list[str] | None = None) -> str:
|
||||
packs = record.get("packs", {})
|
||||
folders = _extract_folders(record, platforms_dir)
|
||||
tag = str(record.get("tag", ""))
|
||||
lines = [
|
||||
"### Install in one command",
|
||||
"### Get your BIOS",
|
||||
"",
|
||||
"It finds your setup and its BIOS folder, then downloads only what is missing.",
|
||||
"Paste this in a terminal. It finds your setup and installs the missing BIOS files.",
|
||||
"",
|
||||
"**Linux, macOS, Steam Deck**",
|
||||
"```sh",
|
||||
install_command("sh"),
|
||||
"```",
|
||||
"",
|
||||
"**Windows (PowerShell)**",
|
||||
"**Windows**",
|
||||
"```powershell",
|
||||
install_command("powershell"),
|
||||
"```",
|
||||
"",
|
||||
(f"**On a handheld**: copy the `RetroBIOS` file for your system to the card"
|
||||
f" ([which one]({SITE}wiki/installer/#on-a-handheld-the-retrobios-port))."),
|
||||
f"**On a handheld**: [get the app for your system]({SITE}{HANDHELD_PAGE}).",
|
||||
"",
|
||||
"### Or download a pack",
|
||||
"### Full packs",
|
||||
"",
|
||||
"Extract it into your BIOS folder.",
|
||||
"Large downloads, for a device without internet. Extract into your BIOS folder.",
|
||||
"",
|
||||
]
|
||||
if any(len(pack["assets"]) > 1 for pack in packs.values()):
|
||||
@@ -170,6 +285,7 @@ def render(record: dict, platforms_dir: str, whats_new: str) -> str:
|
||||
*no_pack_paragraph(platforms_dir),
|
||||
whats_new.strip(),
|
||||
"",
|
||||
*(closing or []),
|
||||
]
|
||||
return "\n".join(lines)
|
||||
|
||||
@@ -182,6 +298,8 @@ def main() -> int:
|
||||
help="what changed since the previous release, written by hand")
|
||||
parser.add_argument("--platforms-dir", default="platforms",
|
||||
help="registry read for each pack's extract folder (default: %(default)s)")
|
||||
parser.add_argument("--thanks", type=Path,
|
||||
help="checked Thanks lines to print instead of the ones gh gives")
|
||||
parser.add_argument("--output", required=True, type=Path,
|
||||
help="notes file to write, passed to gh release create --notes-file")
|
||||
args = parser.parse_args()
|
||||
@@ -201,7 +319,20 @@ def main() -> int:
|
||||
" changed and how it was checked, not a verdict on other projects or a"
|
||||
" promise the gap analysis contradicts", file=sys.stderr)
|
||||
return 1
|
||||
write_text_atomic(str(args.output), render(record, args.platforms_dir, whats_new))
|
||||
try:
|
||||
base = previous_record_commit(record["tag"])
|
||||
if args.thanks:
|
||||
thanks = [line for line in args.thanks.read_text(encoding="utf-8").splitlines()
|
||||
if line.strip()]
|
||||
else:
|
||||
thanks = gather_thanks()
|
||||
except (subprocess.CalledProcessError, ValueError, KeyError, OSError) as exc:
|
||||
detail = getattr(exc, "stderr", "") or exc
|
||||
print(f"Error: cannot gather the thanks: {str(detail).strip()}. Pass a checked list"
|
||||
" with --thanks FILE", file=sys.stderr)
|
||||
return 1
|
||||
closing = closing_lines(thanks, changelog_url(base, record["tag"]))
|
||||
write_text_atomic(str(args.output), render(record, args.platforms_dir, whats_new, closing))
|
||||
print(f"Wrote {args.output} for {record['tag']}, {len(record['packs'])} packs")
|
||||
return 0
|
||||
|
||||
|
||||
+139
-4
@@ -313,13 +313,14 @@ class TheReleaseNotesNameTheSetupsWithoutAZip(unittest.TestCase):
|
||||
import release_notes
|
||||
|
||||
text = release_notes.render(self.RECORD, PLATFORMS, "### What changed\n\n- x\n")
|
||||
paragraph = next(line for line in text.splitlines() if line.startswith("No ZIP for "))
|
||||
paragraph = next(line for line in text.splitlines()
|
||||
if line.startswith("Only the most used setups have a pack"))
|
||||
for name in ("KNULLI", "Recalbox", "RetroPie", "Lakka"):
|
||||
self.assertIn(name, paragraph)
|
||||
for name in ("RetroArch", "Batocera", "RomM"):
|
||||
self.assertNotIn(f" {name},", paragraph)
|
||||
self.assertIn("The command above", paragraph)
|
||||
self.assertIn("--dry-run", paragraph)
|
||||
self.assertIn("use the command above", paragraph)
|
||||
self.assertLess(text.index("| Platform"), text.index(paragraph))
|
||||
self.assertLess(text.index(paragraph), text.index("### What changed"))
|
||||
|
||||
def test_the_rows_link_this_release_files(self):
|
||||
@@ -331,7 +332,141 @@ class TheReleaseNotesNameTheSetupsWithoutAZip(unittest.TestCase):
|
||||
self.assertIn(
|
||||
"[Download](https://github.com/Abdess/retrobios/releases/download/"
|
||||
"v2026.10.24/RomM_5_BIOS_Pack.zip)", text)
|
||||
self.assertNotIn(f"{SITE}get/", text)
|
||||
rows = [line for line in text.splitlines() if line.startswith("| ")]
|
||||
self.assertTrue(rows)
|
||||
for row in rows:
|
||||
self.assertNotIn(f"{SITE}get/", row)
|
||||
|
||||
def test_the_command_comes_before_the_packs(self):
|
||||
"""Most readers need a few files, not a pack of several GB (owner,
|
||||
2026-11-10): the command and the handheld app open the notes."""
|
||||
import release_notes
|
||||
|
||||
text = release_notes.render(self.RECORD, PLATFORMS, "### What changed\n\n- x\n")
|
||||
command = text.index("```sh")
|
||||
# The installer's handheld section, which opens on every download.
|
||||
handheld = text.index(f"{SITE}wiki/installer/#on-a-handheld-the-retrobios-port")
|
||||
packs = text.index("### Full packs")
|
||||
self.assertLess(text.index("### Get your BIOS"), command)
|
||||
self.assertLess(command, handheld)
|
||||
self.assertLess(handheld, packs)
|
||||
self.assertLess(packs, text.index("| Platform"))
|
||||
self.assertLess(packs, text.index("### What changed"))
|
||||
self.assertNotIn("releases/download/", text[:packs])
|
||||
|
||||
|
||||
class TheReleaseNotesThankPeople(unittest.TestCase):
|
||||
"""The notes end with everyone who helped since the repository started
|
||||
and the full changelog, read from gh and git (owner, 2026-11-10).
|
||||
Fixtures stand in for both."""
|
||||
|
||||
TAGS = {"c4": "v2026.11.10", "c3": "v2026.10.10", "c2": "v2026.10.10",
|
||||
"c1": "v2026.10.10", "c0": "v2026.09.04"}
|
||||
# `gh api --paginate --jq` prints one login per line, none for a
|
||||
# commit GitHub links to no account.
|
||||
COMMIT_AUTHORS = "Abdess\nhabib256\nAbdess76\ndependabot[bot]\nzed\nhabib256\n"
|
||||
PULLS = [
|
||||
{"number": 84, "author": {"login": "dajiaohuang", "is_bot": False}},
|
||||
{"number": 86, "author": {"login": "habib256", "is_bot": False}},
|
||||
{"number": 80, "author": {"login": "app/dependabot", "is_bot": True}},
|
||||
{"number": 67, "author": {"login": "prakashmagat50-byte", "is_bot": False}},
|
||||
{"number": 70, "author": {"login": "closedwithoutmerge", "is_bot": False}},
|
||||
]
|
||||
ISSUES = [
|
||||
{"number": 87, "author": {"login": "paperweightorder", "is_bot": False}},
|
||||
{"number": 85, "author": {"login": "72374", "is_bot": False}},
|
||||
{"number": 83, "author": {"login": "72374", "is_bot": False}},
|
||||
{"number": 32, "author": {"login": "Bappo0", "is_bot": False}},
|
||||
{"number": 31, "author": {"login": "ghost", "is_bot": False}},
|
||||
{"number": 30, "author": {"login": "habib256", "is_bot": False}},
|
||||
{"number": 29, "author": {"login": "Abdess", "is_bot": False}},
|
||||
]
|
||||
ISSUE_COMMENTS = "Abdess\nhelper\n72374\ngithub-actions[bot]\nAlpha\n"
|
||||
REVIEW_COMMENTS = "reviewer\nhabib256\n"
|
||||
|
||||
def fake(self, argv):
|
||||
self.calls.append(argv)
|
||||
if argv[:2] == ["git", "log"]:
|
||||
return "\n".join(self.TAGS) + "\n"
|
||||
if argv[:2] == ["git", "show"]:
|
||||
return json.dumps({"tag": self.TAGS[argv[2].split(":")[0]]})
|
||||
if argv[:2] == ["gh", "api"]:
|
||||
path = argv[3]
|
||||
return {"repos/Abdess/retrobios/commits": self.COMMIT_AUTHORS,
|
||||
"repos/Abdess/retrobios/issues/comments": self.ISSUE_COMMENTS,
|
||||
"repos/Abdess/retrobios/pulls/comments": self.REVIEW_COMMENTS}[path]
|
||||
if argv[:3] == ["gh", "pr", "list"]:
|
||||
return json.dumps(self.PULLS)
|
||||
if argv[:3] == ["gh", "issue", "list"]:
|
||||
return json.dumps(self.ISSUES)
|
||||
raise AssertionError(argv)
|
||||
|
||||
def setUp(self):
|
||||
self.calls = []
|
||||
|
||||
def test_the_base_is_the_previous_release_record(self):
|
||||
import release_notes
|
||||
|
||||
self.assertEqual(release_notes.previous_record_commit("v2026.11.10", self.fake), "c1")
|
||||
|
||||
def test_everyone_since_the_start_is_thanked_once(self):
|
||||
import release_notes
|
||||
|
||||
lines = release_notes.gather_thanks(self.fake)
|
||||
self.assertEqual(lines, [
|
||||
"- **Code and data**: @closedwithoutmerge, @dajiaohuang, @habib256 and @zed.",
|
||||
"- **Reports**: @72374 and @paperweightorder.",
|
||||
"- **Help in issues**: @Alpha, @helper and @reviewer.",
|
||||
])
|
||||
text = "\n".join(lines)
|
||||
for left_out in ("Abdess", "bot", "dependabot", "ghost", "Bappo0", "prakashmagat50"):
|
||||
self.assertNotIn(left_out, text)
|
||||
# Every state: a pull request closed without merge still counts.
|
||||
pulls = next(argv for argv in self.calls if argv[:3] == ["gh", "pr", "list"])
|
||||
self.assertEqual(pulls[pulls.index("--state") + 1], "all")
|
||||
issues = next(argv for argv in self.calls if argv[:3] == ["gh", "issue", "list"])
|
||||
self.assertEqual(issues[issues.index("--state") + 1], "all")
|
||||
|
||||
def test_the_notes_end_with_thanks_then_the_changelog(self):
|
||||
import release_notes
|
||||
|
||||
closing = release_notes.closing_lines(
|
||||
["- **Code and data**: @habib256."],
|
||||
release_notes.changelog_url("55eb95344" + "0" * 31, "v2026.11.10"))
|
||||
text = release_notes.render(TheReleaseNotesNameTheSetupsWithoutAZip.RECORD, PLATFORMS,
|
||||
"### What changed\n\n- x\n", closing)
|
||||
self.assertLess(text.index("### What changed"), text.index("### Thanks"))
|
||||
self.assertIn("### Thanks\n\n<details>\n"
|
||||
"<summary>Everyone who helped since the start</summary>\n\n"
|
||||
"- **Code and data**: @habib256.\n\n</details>\n\n**Full changelog**",
|
||||
text)
|
||||
self.assertEqual(release_notes.refused_words(text), [])
|
||||
self.assertTrue(text.rstrip().endswith(
|
||||
"**Full changelog**: https://github.com/Abdess/retrobios/compare/"
|
||||
"55eb95344...v2026.11.10"))
|
||||
|
||||
def test_a_checked_list_replaces_the_one_gh_gives(self):
|
||||
import release_notes
|
||||
|
||||
with tempfile.TemporaryDirectory(dir=REPO_ROOT / "tmp") as tmp:
|
||||
tmp = Path(tmp)
|
||||
(tmp / "whats-new.md").write_text("### What changed\n\n- x\n", encoding="utf-8")
|
||||
(tmp / "thanks.md").write_text("- **Code and data**: @habib256.\n",
|
||||
encoding="utf-8")
|
||||
(tmp / "release.json").write_text(
|
||||
json.dumps(TheReleaseNotesNameTheSetupsWithoutAZip.RECORD), encoding="utf-8")
|
||||
argv = ["release_notes.py", "--record", str(tmp / "release.json"),
|
||||
"--whats-new", str(tmp / "whats-new.md"), "--thanks", str(tmp / "thanks.md"),
|
||||
"--platforms-dir", PLATFORMS, "--output", str(tmp / "notes.md")]
|
||||
with mock.patch.object(sys, "argv", argv), \
|
||||
mock.patch.object(release_notes, "_run", self.fake), \
|
||||
mock.patch.object(release_notes, "gather_thanks",
|
||||
side_effect=AssertionError("gh read")), \
|
||||
contextlib.redirect_stdout(io.StringIO()):
|
||||
self.assertEqual(release_notes.main(), 0)
|
||||
text = (tmp / "notes.md").read_text(encoding="utf-8")
|
||||
self.assertIn("- **Code and data**: @habib256.\n", text)
|
||||
self.assertIn("/compare/c4...v2026.10.24", text)
|
||||
|
||||
|
||||
class EveryPlatformHasAPermanentPage(unittest.TestCase):
|
||||
|
||||
Reference in new issue
Block a user