diff --git a/README.md b/README.md
index 98fe52d..000d159 100644
--- a/README.md
+++ b/README.md
@@ -88,6 +88,43 @@ A message of your own:
color: "3066993"
```
+## Release notes
+
+[release-notes/release_notes.py](release-notes/release_notes.py) writes a release page's notes from your project's TOML config and the files you're publishing. It needs Python 3.11 or later.
+
+The notes go in this order:
+
+1. A headline. It's the first line of your what's-new file, or the config's `description`.
+2. The downloads, as direct links. Each group links the first of its files the release has.
+3. What's new: the rest of your what's-new file.
+4. Your extra sections. Folded ones go in a collapsed block.
+5. The commit and the checksum file.
+
+Start from [release-notes/example.toml](release-notes/example.toml):
+
+```toml
+name = "Example"
+repository = "OWNER/example"
+description = "A one-line description."
+
+[[downloads]]
+label = "Windows"
+files = ["example-windows-x64.zip"]
+
+[[downloads]]
+label = "Linux"
+files = ["example-linux-x64.AppImage", "example-linux-x64.zip"]
+```
+
+Then run it on the folder of files:
+
+```sh
+python3 release_notes.py --config .github/release-notes.toml --version 1.2.0 \
+ --commit "$GITHUB_SHA" --dir dist --whats-new docs/release-notes/1.2.0.md > notes.md
+```
+
+For a test build, add `--testing --tag v1.2.0-testing`. The notes then start with the config's `[testing]` text, or a default one.
+
## Credits
Parts of the toolkit are adapted from ChupathingyCE's release and housekeeping tools.
diff --git a/release-notes/example.toml b/release-notes/example.toml
new file mode 100644
index 0000000..e5ebd63
--- /dev/null
+++ b/release-notes/example.toml
@@ -0,0 +1,46 @@
+# An example release-notes config. Copy it into your repository and change
+# the names. Every download group links the first of its files that the
+# release has; groups with none are left out.
+
+name = "Example"
+repository = "OWNER/example"
+description = "A one-line description, shown when the what's-new file has no headline."
+# The checksum file's name (default: SHA256SUMS)
+checksums = "SHA256SUMS"
+
+[[downloads]]
+label = "Windows"
+files = ["example-windows-x64.zip"]
+
+[[downloads]]
+label = "Mac"
+files = ["example-macos.zip"]
+
+[[downloads]]
+label = "Linux"
+files = ["example-linux-x64.AppImage", "example-linux-x64.zip"]
+
+# Extra sections, after what's new. folded = true (the default) puts a section
+# in a collapsed block. A section with items shows only when one is present.
+# An item with requires shows only when that file is present too.
+[[sections]]
+title = "Older systems"
+folded = false
+
+[[sections.items]]
+label = "Windows 32-bit"
+file = "example-windows-x86.zip"
+requires = "example-windows-x64.zip"
+
+[[sections]]
+title = "Running a server"
+text = "See the server guide in the repository."
+
+[[sections.items]]
+label = "Linux x64 server"
+file = "example-server-linux-x64.zip"
+note = "most VPSes"
+
+# The top of a test build's notes. {name} and {version} are filled in.
+[testing]
+text = "**Test build.** {name} {version}, for testers. It might break. For everyday use, get the latest release."
diff --git a/release-notes/release_notes.py b/release-notes/release_notes.py
new file mode 100755
index 0000000..a0fb42e
--- /dev/null
+++ b/release-notes/release_notes.py
@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""A release page's notes, from a project's TOML config and the files being
+published: a headline, the downloads as direct links, what's new, then
+extra sections and the checksums.
+
+ release_notes.py --config release-notes.toml --version V --commit SHA --dir DIR
+ [--tag TAG] [--whats-new FILE] [--testing] [--notes TEXT] [--output FILE]
+
+DIR holds the release's files (or empty files with their names, for a
+preview). The notes go to standard output, or to --output.
+
+A what's-new file may start with a one-line headline: a first paragraph that
+isn't a list, heading, quote, table or HTML. It goes above the downloads, in
+place of the config's description.
+
+--testing makes a test build's notes: the config's testing text on top
+(or a default one), then --notes, then the downloads.
+
+Needs Python 3.11 or later (tomllib).
+"""
+
+import argparse
+import sys
+import tomllib
+from pathlib import Path
+
+DEFAULT_TESTING = ("**Test build.** {name} {version}, for testers. It might break, and the next test build "
+ "replaces it. For everyday use, get the latest release.")
+
+
+class ConfigError(Exception):
+ pass
+
+
+def load_config(path: Path) -> dict:
+ try:
+ config = tomllib.loads(path.read_text())
+ except tomllib.TOMLDecodeError as error:
+ raise ConfigError(f"{path}: {error}") from error
+ for key in ("name", "repository"):
+ if not isinstance(config.get(key), str) or not config[key]:
+ raise ConfigError(f"{path}: '{key}' is required")
+ if config["repository"].count("/") != 1:
+ raise ConfigError(f"{path}: 'repository' is OWNER/NAME")
+ for entry in config.setdefault("downloads", []):
+ if "label" not in entry or "files" not in entry:
+ raise ConfigError(f"{path}: every [[downloads]] needs a label and files")
+ if isinstance(entry["files"], str):
+ entry["files"] = [entry["files"]]
+ for section in config.setdefault("sections", []):
+ if "title" not in section:
+ raise ConfigError(f"{path}: every [[sections]] needs a title")
+ for item in section.setdefault("items", []):
+ if "label" not in item or "file" not in item:
+ raise ConfigError(f"{path}: every item in '{section['title']}' needs a label and a file")
+ config.setdefault("description", "")
+ config.setdefault("checksums", "SHA256SUMS")
+ return config
+
+
+def site(config: dict) -> str:
+ return f"https://github.com/{config['repository']}"
+
+
+def link(config: dict, tag: str, name: str) -> str:
+ return f"{site(config)}/releases/download/{tag}/{name}"
+
+
+def details(summary: str, body: list) -> str:
+ return "\n".join([f"{summary}
", "", *body, "", " "])
+
+
+def headline(whats_new: str):
+ """(the what's-new file's one-line headline, if it starts with one; the rest)"""
+ first, _, rest = whats_new.partition("\n\n")
+ if first and "\n" not in first.strip() and not first.lstrip().startswith(("-", "*", "#", "<", "|", ">", "!")):
+ return first.strip(), rest.strip()
+ return "", whats_new
+
+
+def downloads(config: dict, tag: str, names) -> str:
+ links = []
+ for entry in config["downloads"]:
+ name = next((name for name in entry["files"] if name in names), None)
+ if name:
+ links.append(f"[{entry['label']}]({link(config, tag, name)})")
+ if not links:
+ return ""
+ return "\n".join(["## Download", "", " ยท ".join(links)])
+
+
+def section(config: dict, tag: str, names, spec: dict) -> str:
+ items = [item for item in spec["items"]
+ if item["file"] in names and (not item.get("requires") or item["requires"] in names)]
+ if spec["items"] and not items:
+ return ""
+ body = [f"- [{item['label']}]({link(config, tag, item['file'])})" + (f": {item['note']}" if item.get("note") else "")
+ for item in items]
+ if spec.get("text"):
+ body += (["", spec["text"]] if body else [spec["text"]])
+ if not body:
+ return ""
+ if spec.get("folded", True):
+ return details(spec["title"], body)
+ return "\n".join([f"## {spec['title']}", "", *body])
+
+
+def checks(config: dict, tag: str, commit: str, names) -> str:
+ body = [f"- Commit: [{commit[:12]}]({site(config)}/commit/{commit})"]
+ sums = config["checksums"]
+ if sums in names:
+ body.append(f"- [{sums}]({link(config, tag, sums)}) lists every download's SHA-256.")
+ if f"{sums}.sig" in names:
+ body.append(f"- [{sums}.sig]({link(config, tag, sums + '.sig')}) signs it.")
+ return details("Checksums", body)
+
+
+def notes(config: dict, version: str, tag: str, commit: str, names, whats_new: str = "",
+ testing: bool = False, extra: str = "") -> str:
+ if testing:
+ top = (config.get("testing", {}).get("text") or DEFAULT_TESTING).format(name=config["name"], version=version)
+ sections = [top, extra, downloads(config, tag, names), whats_new]
+ else:
+ line, whats_new = headline(whats_new.strip())
+ sections = [line or config["description"], downloads(config, tag, names), whats_new]
+ sections += [section(config, tag, names, spec) for spec in config["sections"]]
+ sections.append(checks(config, tag, commit, names))
+ return "\n\n".join(part.strip() for part in sections if part and part.strip()) + "\n"
+
+
+def main(argv=None) -> int:
+ parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ parser.add_argument("--config", type=Path, required=True, help="the project's release-notes TOML")
+ parser.add_argument("--version", required=True)
+ parser.add_argument("--tag", help="default: v")
+ parser.add_argument("--commit", required=True)
+ parser.add_argument("--dir", type=Path, required=True, help="the files being published")
+ parser.add_argument("--whats-new", type=Path, help="Markdown; a missing file is skipped")
+ parser.add_argument("--testing", action="store_true", help="a test build's notes")
+ parser.add_argument("--notes", default="", help="extra text for a test build")
+ parser.add_argument("--output", type=Path)
+ options = parser.parse_args(argv)
+ try:
+ config = load_config(options.config)
+ except (ConfigError, OSError) as error:
+ print(f"error: {error}", file=sys.stderr)
+ return 2
+ names = {path.name for path in options.dir.iterdir() if path.is_file()}
+ whats_new = options.whats_new.read_text() if options.whats_new and options.whats_new.is_file() else ""
+ text = notes(config, options.version, options.tag or f"v{options.version}", options.commit, names,
+ whats_new, options.testing, options.notes)
+ if options.output:
+ options.output.write_text(text)
+ else:
+ sys.stdout.write(text)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tests/test_release_notes.py b/tests/test_release_notes.py
new file mode 100644
index 0000000..5dd31c4
--- /dev/null
+++ b/tests/test_release_notes.py
@@ -0,0 +1,87 @@
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "release-notes"))
+import release_notes # noqa: E402
+
+EXAMPLE = ROOT / "release-notes" / "example.toml"
+COMMIT = "0123456789abcdef0123456789abcdef01234567"
+SITE = "https://github.com/OWNER/example"
+
+
+def folder(tmp_path, names):
+ tmp_path.mkdir(parents=True, exist_ok=True)
+ for name in names:
+ (tmp_path / name).write_text("")
+ return tmp_path
+
+
+def render(tmp_path, names, whats_new="", **options):
+ directory = folder(tmp_path / "files", names)
+ arguments = ["--config", str(EXAMPLE), "--version", "1.2.0", "--commit", COMMIT, "--dir", str(directory),
+ "--output", str(tmp_path / "notes.md")]
+ if whats_new:
+ (tmp_path / "new.md").write_text(whats_new)
+ arguments += ["--whats-new", str(tmp_path / "new.md")]
+ for key, value in options.items():
+ arguments += [f"--{key}"] + ([] if value is True else [value])
+ assert release_notes.main(arguments) == 0
+ return (tmp_path / "notes.md").read_text()
+
+
+def test_downloads_link_the_first_present_file(tmp_path):
+ text = render(tmp_path, ["example-windows-x64.zip", "example-linux-x64.zip", "SHA256SUMS"])
+ assert f"[Windows]({SITE}/releases/download/v1.2.0/example-windows-x64.zip)" in text
+ assert f"[Linux]({SITE}/releases/download/v1.2.0/example-linux-x64.zip)" in text
+ assert "[Mac]" not in text
+ assert text.startswith("A one-line description")
+ assert f"[SHA256SUMS]({SITE}/releases/download/v1.2.0/SHA256SUMS)" in text
+ assert f"[{COMMIT[:12]}]({SITE}/commit/{COMMIT})" in text
+
+
+def test_headline_replaces_the_description(tmp_path):
+ text = render(tmp_path, ["example-macos.zip"], "Faster menus and a new server browser.\n\n- Fixed a crash\n")
+ assert text.startswith("Faster menus and a new server browser.\n\n## Download")
+ assert "A one-line description" not in text
+ assert text.index("## Download") < text.index("- Fixed a crash")
+
+
+def test_a_list_is_not_a_headline():
+ assert release_notes.headline("- one\n- two") == ("", "- one\n- two")
+ assert release_notes.headline("## Heading\n\ntext") == ("", "## Heading\n\ntext")
+
+
+def test_sections_show_only_with_their_files(tmp_path):
+ text = render(tmp_path, ["example-windows-x86.zip"])
+ assert "Older systems" not in text
+ text = render(tmp_path / "b", ["example-windows-x86.zip", "example-windows-x64.zip",
+ "example-server-linux-x64.zip"])
+ assert "## Older systems" in text
+ assert "Running a server
" in text
+ assert "server-linux-x64.zip): most VPSes" in text
+
+
+def test_testing_notes(tmp_path):
+ text = render(tmp_path, ["example-macos.zip"], tag="v1.2.0-testing", testing=True, notes="Try the new menus.")
+ assert text.startswith("**Test build.** Example 1.2.0, for testers.")
+ assert "Try the new menus." in text
+ assert "/download/v1.2.0-testing/example-macos.zip" in text
+
+
+def test_missing_required_keys(tmp_path):
+ path = tmp_path / "bad.toml"
+ path.write_text('name = "x"\n')
+ with pytest.raises(release_notes.ConfigError):
+ release_notes.load_config(path)
+ path.write_text('name = "x"\nrepository = "o/r"\n[[downloads]]\nlabel = "Windows"\n')
+ with pytest.raises(release_notes.ConfigError):
+ release_notes.load_config(path)
+
+
+def test_a_single_file_string_is_allowed(tmp_path):
+ path = tmp_path / "one.toml"
+ path.write_text('name = "x"\nrepository = "o/r"\n[[downloads]]\nlabel = "Linux"\nfiles = "x.zip"\n')
+ assert release_notes.load_config(path)["downloads"][0]["files"] == ["x.zip"]