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"]