A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
# /// script
# requires-python = ">=3.13,<3.14"
# dependencies = [
# "msgspec",
# ]
#
# [tool.uv]
# exclude-newer = "2025-06-27T12:38:25.742953-04:00"
# ///
"""Generate release notes from commits on main branch."""
from __future__ import annotations
import re
import subprocess
import sys
import msgspec
class Author(msgspec.Struct):
"""GitHub author/user information."""
login: str
class Label(msgspec.Struct):
"""GitHub label information."""
name: str
color: str | None = None
description: str | None = None
class PullRequest(msgspec.Struct):
"""GitHub Pull Request information."""
number: int
title: str
author: Author
labels: list[Label]
body: str | None
mergedAt: str | None = None
class Commit(msgspec.Struct):
"""Git commit information."""
sha: str
message: str
pr_number: int | None = None
class CategorizedEntry(msgspec.Struct):
"""A release note entry with its PR information."""
commit: Commit
pr: PullRequest | None = None
def get_commits_since_tag(since_tag: str) -> list[Commit]:
"""Get commits on main since a specific tag."""
result = subprocess.run(
[
"git",
"log",
f"{since_tag}..HEAD",
"--format=%H %s",
"--first-parent", # Only follow the first parent (main branch)
"main",
],
capture_output=True,
text=True,
check=True,
)
commits = []
for line in result.stdout.strip().split("\n"):
if not line:
continue
parts = line.split(" ", 1)
if len(parts) != 2:
continue
sha, message = parts
# Extract PR number from squash merge commit message
# Looking for patterns like (#1234) or #1234
pr_match = re.search(r"#(\d+)", message)
pr_number = int(pr_match.group(1)) if pr_match else None
commits.append(Commit(sha=sha, message=message, pr_number=pr_number))
return commits
def get_merged_prs(limit: int = 100) -> dict[int, PullRequest]:
"""Get recently merged PRs and return as a dict keyed by PR number."""
result = subprocess.run(
[
"gh",
"pr",
"list",
"--base",
"main",
"--state",
"merged",
"--limit",
str(limit),
"--json",
"number,title,author,labels,body,mergedAt",
],
check=True,
capture_output=True,
text=True,
)
return {
pr.number: pr
for pr in msgspec.json.decode(result.stdout, type=list[PullRequest])
}
def extract_media_from_body(body: str | None) -> list[str]:
"""Extract media (images/links) from PR body."""
if not body:
return []
media = []
# Find markdown images: 
img_pattern = r"!\[.*?\]\((.*?)\)"
for match in re.finditer(img_pattern, body):
media.append(f'<img src="{match.group(1)}" alt="PR media">')
# Find HTML img tags
html_img_pattern = r'<img[^>]+src=["\']([^"\']+)["\'][^>]*>'
for match in re.finditer(html_img_pattern, body):
media.append(match.group(0))
# Find video links (common patterns)
video_patterns = [
r"https?://[^\s]+\.(?:mp4|webm|mov|gif)",
r"https?://(?:www\.)?(?:youtube\.com/watch\?v=|youtu\.be/)[^\s]+",
r"https?://(?:www\.)?vimeo\.com/[^\s]+",
]
for pattern in video_patterns:
for match in re.finditer(pattern, body):
media.append(f'<a href="{match.group(0)}">{match.group(0)}</a>')
return media
def categorize_entries(
entries: list[CategorizedEntry],
) -> dict[str, list[CategorizedEntry]]:
"""Categorize entries based on PR labels."""
# TODO: Could add more or be more granular
categories = {
"breaking": [],
"bug": [],
"enhancement": [],
"documentation": [],
"preview": [],
"other": [],
"highlights": [],
}
for entry in entries:
if entry.pr is None:
categories["other"].append(entry)
continue
label_names = {label.name for label in entry.pr.labels}
# Skip entries labeled as "internal"
if "internal" in label_names:
continue
if "release-highlight" in label_names:
categories["highlights"].append(entry)
if "breaking" in label_names:
categories["breaking"].append(entry)
elif "preview" in label_names:
categories["preview"].append(entry)
elif "bug" in label_names:
categories["bug"].append(entry)
elif "enhancement" in label_names:
categories["enhancement"].append(entry)
elif "documentation" in label_names:
categories["documentation"].append(entry)
else:
categories["other"].append(entry)
return categories
def strip_conventional_prefix(title: str) -> str:
"""Strip conventional commit prefixes and capitalize first letter."""
# Match patterns like "word:" or "word(scope):" at the beginning
match = re.match(r"^(\w+)(?:\([^)]+\))?:\s*(.+)", title)
if match:
# Get the part after the prefix and capitalize first letter
stripped = match.group(2)
return stripped[0].upper() + stripped[1:] if stripped else stripped
return title
def format_entry(entry: CategorizedEntry) -> str:
if entry.pr:
title = strip_conventional_prefix(entry.pr.title)
return f"* {title} ([#{entry.pr.number}](https://github.com/marimo-team/marimo/pull/{entry.pr.number}))"
title = entry.commit.message
title = strip_conventional_prefix(entry.commit.message)
return f"* {title} ({entry.commit.sha[:7]})"
def get_contributors(entries: list[CategorizedEntry]) -> list[str]:
"""Extract unique contributors from all entries."""
contributors = set()
for entry in entries:
if entry.pr and entry.pr.author:
contributors.add(entry.pr.author.login)
return sorted(contributors, key=str.lower)
def generate_release_notes(since_tag: str) -> str:
"""Generate release notes since a specific tag."""
commits = get_commits_since_tag(since_tag)
pr_map = get_merged_prs(limit=100)
# Match commits with PRs
entries = []
for commit in commits:
pr = pr_map.get(commit.pr_number) if commit.pr_number else None
entries.append(CategorizedEntry(commit=commit, pr=pr))
categories = categorize_entries(entries)
notes = ["## What's Changed\n"]
if categories["highlights"]:
for i, entry in enumerate(categories["highlights"]):
if i > 0:
notes.append("")
if entry.pr:
notes.append(f"**TODO: {entry.pr.title} #{entry.pr.number}**")
notes.append("")
notes.append("TODO: Description of the feature")
# Check for media
label_names = {label.name for label in entry.pr.labels}
if "includes-media" in label_names:
media = extract_media_from_body(entry.pr.body)
if media:
notes.append("")
for item in media:
notes.append(item)
notes.append("")
if categories["breaking"]:
notes.append("## 🚨 Breaking changes")
for entry in categories["breaking"]:
notes.append(format_entry(entry))
notes.append("")
if categories["enhancement"]:
notes.append("## ✨ Enhancements")
for entry in categories["enhancement"]:
notes.append(format_entry(entry))
notes.append("")
if categories["bug"]:
notes.append("## 🐛 Bug fixes")
for entry in categories["bug"]:
notes.append(format_entry(entry))
notes.append("")
if categories["documentation"]:
notes.append("## 📚 Documentation")
for entry in categories["documentation"]:
notes.append(format_entry(entry))
notes.append("")
if categories["preview"]:
notes.append("## 🔬 Preview features")
for entry in categories["preview"]:
notes.append(format_entry(entry))
notes.append("")
if categories["other"]:
notes.append("## 📝 Other changes")
for entry in categories["other"]:
notes.append(format_entry(entry))
notes.append("")
contributors = get_contributors(entries)
notes.append("## Contributors")
notes.append(
f"Thanks to all our community and contributors who made this release possible: @{', @'.join(contributors)}"
)
notes.append("")
notes.append("And especially to our new contributors:")
notes.append("* TODO: Check for new contributors")
notes.append("")
current_tag = "TODO_CURRENT_VERSION"
notes.append(
f"\n**Full Changelog**: https://github.com/marimo-team/marimo/compare/{since_tag}...{current_tag}"
)
return "\n".join(notes)
def main() -> None:
if len(sys.argv) < 2:
print("Usage: generate_release_notes.py <since-tag>")
print("Example: generate_release_notes.py 0.14.7")
sys.exit(1)
print(generate_release_notes(sys.argv[1]))
if __name__ == "__main__":
main()