Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 37 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
46 changes: 46 additions & 0 deletions release-notes/example.toml
Original file line number Diff line number Diff line change
@@ -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."
160 changes: 160 additions & 0 deletions release-notes/release_notes.py
Original file line number Diff line number Diff line change
@@ -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"<details><summary>{summary}</summary>", "", *body, "", "</details>"])


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<version>")
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())
87 changes: 87 additions & 0 deletions tests/test_release_notes.py
Original file line number Diff line number Diff line change
@@ -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 "<details><summary>Running a server</summary>" 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"]
Loading