File size: 10,011 Bytes
aacc0cb 5ecb1dc aacc0cb 69c00d1 aacc0cb 69c00d1 aacc0cb 69c00d1 aacc0cb 69c00d1 aacc0cb | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 | """Build release notes from kscrape's curated changelog."""
from __future__ import annotations
import argparse
import re
from collections.abc import Sequence
from pathlib import Path
ROOT = Path(__file__).resolve().parents[3]
VERSION_RE = re.compile(r"^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$")
RELEASE_HEADING_RE = re.compile(
r"^# \[(?P<version>\d+\.\d+\.\d+)\] - "
r"(?P<date>\d{4}-\d{2}-\d{2})$",
re.MULTILINE,
)
UNRELEASED_HEADING = "# [Unreleased]"
UNRELEASED_SECTIONS = (
"### 💥 Breaking Change Summary",
"### ➕ Added",
"### 💔 Changed",
"### ⚠️ Deprecated",
"### 🗑️ Removed",
"### 🔨 Fixed",
)
def build_release_notes(markdown: str, version: str) -> str:
"""Extract one released changelog section for an annotated tag.
:param markdown: Complete changelog text.
:param version: Release version without a leading ``v``.
:return: Markdown body for the release tag.
"""
validate_version(version)
validate_unreleased_section(markdown)
match = _release_heading(markdown, version)
_validate_toc_entry(markdown, match)
next_heading = re.search(r"^# \[", markdown[match.end() :], re.MULTILINE)
section_end = (
match.end() + next_heading.start()
if next_heading is not None
else len(markdown)
)
notes = _clean_release_markdown(markdown[match.end() : section_end])
if not any(line.lstrip().startswith("- ") for line in notes.splitlines()):
raise ValueError(f"Release {version} has no changelog entries.")
return f"{notes}\n"
def validate_version(version: str) -> None:
"""Reject versions that do not use three non-zero-padded components.
:param version: Candidate release version without a leading ``v``.
:return: None.
"""
if VERSION_RE.fullmatch(version) is None:
raise ValueError(
f"Invalid release version {version!r}; expected MAJOR.MINOR.PATCH."
)
def validate_tag_version(tag: str, project_version: str) -> None:
"""Require an annotated tag to name the package version exactly.
:param tag: Git tag expected to use the ``vMAJOR.MINOR.PATCH`` form.
:param project_version: Version declared in package metadata.
:return: None.
"""
validate_version(project_version)
expected_tag = f"v{project_version}"
if tag != expected_tag:
raise ValueError(
f"Release tag {tag!r} does not match project version "
f"{project_version!r}; expected {expected_tag!r}."
)
def validate_next_version(current_version: str, next_version: str) -> None:
"""Require a prepared changelog release to advance package metadata.
:param current_version: Version currently declared in package metadata.
:param next_version: Version prepared in the changelog.
:return: None.
"""
validate_version(current_version)
validate_version(next_version)
current_key = tuple(int(part) for part in current_version.split("."))
next_key = tuple(int(part) for part in next_version.split("."))
if next_key <= current_key:
raise ValueError(
f"Prepared release {next_version!r} must be newer than "
f"the current project version {current_version!r}."
)
def latest_release_version(markdown: str) -> str:
"""Return the highest version declared in the changelog.
:param markdown: Complete changelog text.
:return: Highest released semantic version.
"""
matches = list(RELEASE_HEADING_RE.finditer(markdown))
if not matches:
raise ValueError("Changelog has no versioned release heading.")
return max(
(match.group("version") for match in matches),
key=lambda value: tuple(int(part) for part in value.split(".")),
)
def validate_unreleased_section(markdown: str) -> None:
"""Require a complete and empty ``[Unreleased]`` release template.
:param markdown: Complete changelog text.
:return: None.
"""
if markdown.count(UNRELEASED_HEADING) != 1:
raise ValueError(
"Changelog must contain exactly one [Unreleased] heading."
)
start = markdown.index(UNRELEASED_HEADING) + len(UNRELEASED_HEADING)
next_release = RELEASE_HEADING_RE.search(markdown, start)
if next_release is None:
raise ValueError(
"Changelog has no released section after [Unreleased]."
)
section = markdown[start : next_release.start()]
for heading in UNRELEASED_SECTIONS:
if section.count(heading) != 1:
raise ValueError(
"The [Unreleased] section must contain each release category "
f"exactly once; invalid heading: {heading!r}."
)
content_lines = [
line for line in _content_lines(section) if not line.startswith("### ")
]
if content_lines:
raise ValueError(
"The [Unreleased] section still contains release entries. Move "
"them into the prepared version before tagging."
)
def write_release_notes(markdown: str, version: str, output: Path) -> None:
"""Write a released changelog section to a Markdown file.
:param markdown: Complete changelog text.
:param version: Release version without a leading ``v``.
:param output: Destination Markdown path.
:return: None.
"""
output.parent.mkdir(parents=True, exist_ok=True)
output.write_text(build_release_notes(markdown, version), encoding="utf-8")
def _release_heading(markdown: str, version: str) -> re.Match[str]:
"""Find the unique heading for one version.
:param markdown: Complete changelog text.
:param version: Release version without a leading ``v``.
:return: Matched version heading.
"""
matches = [
match
for match in RELEASE_HEADING_RE.finditer(markdown)
if match.group("version") == version
]
if len(matches) != 1:
raise ValueError(
f"Changelog must contain exactly one release heading for {version}; "
f"found {len(matches)}."
)
return matches[0]
def _validate_toc_entry(markdown: str, match: re.Match[str]) -> None:
"""Require a release heading to appear once in the changelog table of contents.
:param markdown: Complete changelog text.
:param match: Release heading whose table-of-contents entry is required.
:return: None.
"""
version = match.group("version")
date = match.group("date")
entry = f"[\\[{version}\\] - {date}](#{version.replace('.', '')}---{date})"
if markdown.count(entry) != 1:
raise ValueError(
f"Changelog table of contents must contain exactly one {entry!r} entry."
)
def _clean_release_markdown(section: str) -> str:
"""Remove layout markers while retaining headings and release entries.
:param section: Changelog text after a version heading.
:return: Compact release-note Markdown.
"""
cleaned: list[str] = []
previous_blank = True
for line in section.splitlines():
stripped = line.strip()
if _is_layout_line(stripped):
continue
if line.startswith("### "):
line = line[1:]
if not stripped:
if not previous_blank:
cleaned.append("")
previous_blank = True
continue
cleaned.append(line)
previous_blank = False
while cleaned and not cleaned[-1]:
cleaned.pop()
return "\n".join(cleaned)
def _content_lines(section: str) -> list[str]:
"""Return non-empty changelog lines that are not layout markers.
:param section: One changelog section.
:return: Content lines stripped of surrounding whitespace.
"""
return [
line.strip()
for line in section.splitlines()
if line.strip() and not _is_layout_line(line.strip())
]
def _is_layout_line(line: str) -> bool:
"""Identify a Markdown line used only for changelog spacing.
:param line: Stripped Markdown line.
:return: Whether the line contains no release content.
"""
return (
line == "<br>"
or line == "---"
or (line.startswith("<!--") and line.endswith("-->"))
)
def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
"""Parse release-note extraction arguments.
:param argv: Optional argument vector used by tests.
:return: Parsed command arguments.
"""
parser = argparse.ArgumentParser(
description="Extract one release body from CHANGELOG.md."
)
parser.add_argument("version", help="Release version without a leading v.")
parser.add_argument(
"--changelog",
type=Path,
default=ROOT / "CHANGELOG.md",
help="Changelog source path.",
)
parser.add_argument(
"--output", type=Path, required=True, help="Destination path."
)
parser.add_argument("--tag", help="Optional tag to validate.")
parser.add_argument(
"--project-version", help="Optional package version to validate."
)
return parser.parse_args(argv)
def main(argv: Sequence[str] | None = None) -> int:
"""Validate release state and write a release-note file.
:param argv: Optional argument vector used by tests.
:return: Process exit code.
"""
args = parse_args(argv)
if (args.tag is None) != (args.project_version is None):
raise ValueError(
"--tag and --project-version must be provided together."
)
if args.tag is not None:
validate_tag_version(args.tag, args.project_version)
if args.version != args.project_version:
raise ValueError(
f"Requested release version {args.version!r} does not match "
f"project version {args.project_version!r}."
)
write_release_notes(
args.changelog.read_text(encoding="utf-8"), args.version, args.output
)
return 0
if __name__ == "__main__":
raise SystemExit(main())
|