Free, open-source 3D sculpting for Linux, macOS and Windows: dense meshes, remeshing, painting, built-in AI (image/text to 3D), Send to Unreal, game-ready LODs, Gaussian splats and OpenUSD.
C++ 3d3d-sculptingcppdear-imguidigital-sculptingfbxgame-developmentgaussian-splattinggltfimage-to-3dmcpopenglopenusdsculptingtext-to-3dunreal-engine
#!/usr/bin/env python3
# SculptForge - open source digital sculpting
# SPDX-License-Identifier: GPL-3.0-or-later
"""Release notes from note fragments: one changes/<branch>.md per branch instead of every branch editing CHANGELOG.md
and the guide's What's New (the merge conflicts of every release).
A fragment is front matter only (changes/README.md has the format):
---
whats_new: **Gizmo size**: **Draw > Camera > Gizmo size** sets Small, Medium or Large.
highlight: Corner axes in three sizes
added: **Gizmo size** (Draw > Camera): the corner axes come in Small, Medium (as before, the default) and Large,
on top of the UI scale. Saved in the preferences.
testers:
- Windows, 150% scaling: Draw > Camera > Gizmo size Large; click each axis end, the view snaps to that side.
---
Keys: whats_new (a bullet for docs/guide/whats-new.md, which the app shows), highlight (a line for the version's
feature block and the update feed), added / changed / fixed / removed / security (a CHANGELOG.md entry in that
section), testers (bullets for the #testers checklist). Every key may repeat; a value continues on lines indented
by two spaces.
tools/release/assemble_notes.py X.Y.Z what would change (nothing written)
tools/release/assemble_notes.py X.Y.Z --apply write CHANGELOG.md [Unreleased] and What's New X.Y.Z, delete the
fragments (scripts/release.sh step bump runs this)
tools/release/assemble_notes.py X.Y.Z --testers print the #testers checklist (post it with the preview build)
tools/release/assemble_notes.py X.Y.Z --highlights the version's highlight lines, What's New's and the fragments'
(release.sh uses them when HIGHLIGHTS is not set)
tools/release/assemble_notes.py --check every fragment parses (ctest release_notes runs --self-test)
"""
import re
import sys
import tempfile
from pathlib import Path
ROOT = Path(__file__).resolve().parents[2]
SECTIONS = ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"] # Keep a Changelog's order
KEYS = {"whats_new", "highlight", "testers"} | {s.lower() for s in SECTIONS}
class NoteError(Exception):
pass
def parse(path):
"""A fragment's front matter as {key: [values]}."""
text = Path(path).read_text(encoding="utf-8")
m = re.match(r"---\n(.*?)\n---[ \t]*(\n|$)", text, re.S)
if not m:
raise NoteError(f"{path}: no front matter (a '---' line, key: value lines, a '---' line)")
out, key, item = {}, None, None
for n, line in enumerate(m.group(1).split("\n"), start=2):
if not line.strip() or line.lstrip().startswith("#"):
continue
km = re.match(r"([a-z_]+):[ \t]*(.*)$", line)
if km and not line[0].isspace():
key = km.group(1)
if key not in KEYS:
raise NoteError(f"{path}:{n}: unknown key '{key}' (known: {', '.join(sorted(KEYS))})")
out.setdefault(key, [])
item = None
if km.group(2).strip():
out[key].append(km.group(2).strip())
item = len(out[key]) - 1
continue
if key is None or not line.startswith(" "):
raise NoteError(f"{path}:{n}: expected 'key: value' or a line indented by two spaces")
body = line.strip()
if key == "testers" and body.startswith("- "):
out[key].append(body[2:].strip())
item = len(out[key]) - 1
elif item is not None:
out[key][item] += " " + body
else:
out[key].append(body)
item = len(out[key]) - 1
if not any(out.get(k) for k in KEYS):
raise NoteError(f"{path}: empty (give at least a whats_new or a CHANGELOG line)")
return out
def fragments(root):
d = Path(root) / "changes"
files = sorted(p for p in d.glob("*.md") if p.name.lower() != "readme.md") if d.is_dir() else []
return [(p, parse(p)) for p in files]
def wrap(text, first, rest, width=118):
"""Markdown bullet text wrapped as the hand-written CHANGELOG and guide are (118 columns, 2-space hang)."""
lines, cur = [], ""
for w in text.split():
prefix = rest if lines else first
if cur and len(prefix) + len(cur) + 1 + len(w) > width:
lines.append(prefix + cur)
cur = w
else:
cur = f"{cur} {w}" if cur else w
lines.append((rest if lines else first) + cur)
return "\n".join(lines) + "\n"
def changelog(text, frags):
"""CHANGELOG.md with every fragment's entries added to [Unreleased], in their sections."""
m = re.search(r"^## \[Unreleased\][^\n]*\n", text, re.M)
if not m:
raise NoteError("CHANGELOG.md has no '## [Unreleased]' section")
nxt = re.search(r"^## \[", text[m.end():], re.M)
end = m.end() + nxt.start() if nxt else len(text)
body = text[m.end():end]
for section in SECTIONS:
entries = [e for _, f in frags for e in f.get(section.lower(), [])]
if not entries:
continue
add = "".join(wrap(e, "- ", " ") for e in entries)
sm = re.search(rf"^### {section}[ \t]*\n", body, re.M)
if sm:
snext = re.search(r"^##", body[sm.end():], re.M)
at = sm.end() + (snext.start() if snext else len(body) - sm.end())
before = body[:at].rstrip("\n") + "\n"
body = before + add + "\n" + body[at:].lstrip("\n")
else:
body = body.rstrip("\n") + f"\n\n### {section}\n" + add + "\n"
body = "\n" + body.lstrip("\n")
if not body.endswith("\n\n") and nxt:
body = body.rstrip("\n") + "\n\n"
return text[:m.end()] + body + text[end:]
def whats_new(text, version, frags):
"""docs/guide/whats-new.md with the fragments' bullets (and highlights) in the version's section, made if new."""
bullets = [b for _, f in frags for b in f.get("whats_new", [])]
highlights = [h for _, f in frags for h in f.get("highlight", [])]
if not bullets and not highlights:
return text
ev = re.escape(version)
m = re.search(rf"^## Version {ev}[ \t]*\n", text, re.M)
if not m:
first = re.search(r"^## Version ", text, re.M)
at = first.start() if first else len(text)
block = f"## Version {version}\n\n```features\ndate: unreleased\n```\n\n"
text = text[:at] + block + text[at:]
m = re.search(rf"^## Version {ev}[ \t]*\n", text, re.M)
nxt = re.search(r"^## ", text[m.end():], re.M)
end = m.end() + nxt.start() if nxt else len(text)
section = text[m.end():end]
if highlights:
fm = re.search(r"^```features\n(.*?)^```", section, re.M | re.S)
if not fm:
raise NoteError(f"whats-new.md: Version {version} has no ```features block for the highlights")
lines = fm.group(1).split("\n")
last = max([i for i, l in enumerate(lines) if l.startswith(("date:", "tagline:", "highlight:"))], default=-1)
have = {l[len("highlight:"):].strip() for l in lines if l.startswith("highlight:")}
lines[last + 1:last + 1] = [f"highlight: {h}" for h in dict.fromkeys(highlights) if h not in have]
section = section[:fm.start(1)] + "\n".join(lines) + section[fm.end(1):]
if bullets:
# Straight after the list if the section has one, else after a blank line.
list_end = re.search(r"^- ", section, re.M) and section.rstrip("\n").split("\n")[-1].startswith(("- ", " "))
section = section.rstrip("\n") + ("\n" if list_end else "\n\n")
section += "".join(wrap(b, "- ", " ") for b in bullets) + "\n"
return text[:m.end()] + section + text[end:]
def testers(version, frags):
out = [f"**SculptForge {version} preview: please try** (reply with OS, tablet and what you saw)", ""]
for path, f in frags:
for t in f.get("testers", []):
out.append(f"- [ ] {t} ({path.stem})")
return "\n".join(out) + "\n"
def run(root, version, mode):
root = Path(root)
frags = fragments(root)
if mode == "--check":
# whats_new and highlight text goes into the in-app What's New, drawn with the app's Latin UI font: the same
# rule as the guide (tools/guide/build_site.py, ctest guide_site), here and not only after the bump assembles
# the notes (0.11.10: "繁體中文 and 简体中文" in a whats_new line stopped the stage).
bad = []
for path, f in frags:
for key in ("whats_new", "highlight"):
for text in f.get(key, []) if isinstance(f.get(key), list) else [f.get(key) or ""]:
chars = sorted({ch for ch in text if ord(ch) > 0xFF or (ord(ch) < 0x20 and ch not in "\t\n")})
if chars:
bad.append(f"{path.name}: {key}: characters the app's font can't show: "
+ " ".join(f"U+{ord(ch):04X}" for ch in chars))
for b in bad:
print(b)
print(f"{len(frags)} note fragment(s) parse")
return 1 if bad else 0
if mode == "--testers":
sys.stdout.write(testers(version, frags))
return 0
if mode == "--highlights": # the version's feature block's highlights, then the fragments'
wn = (root / "docs" / "guide" / "whats-new.md").read_text(encoding="utf-8")
m = re.search(rf"^## Version {re.escape(version)}[ \t]*\n+```features\n(.*?)^```", wn, re.M | re.S)
lines = re.findall(r"^highlight:[ \t]*(.+)$", m.group(1), re.M) if m else []
lines += [h for _, f in frags for h in f.get("highlight", [])]
lines = list(dict.fromkeys(lines)) # a fragment's highlight already in the block counts once
sys.stdout.write("".join(h + "\n" for h in lines))
return 0
if not frags:
print("no note fragments in changes/")
return 0
cl, wn = root / "CHANGELOG.md", root / "docs" / "guide" / "whats-new.md"
new = {cl: changelog(cl.read_text(encoding="utf-8"), frags),
wn: whats_new(wn.read_text(encoding="utf-8"), version, frags)}
for p, t in new.items():
if mode == "--apply":
p.write_text(t, encoding="utf-8")
print(f"{p.relative_to(root)}: {'written' if mode == '--apply' else 'would change'}")
for path, _ in frags:
if mode == "--apply":
path.unlink()
print(f"{path.relative_to(root)}: {'deleted' if mode == '--apply' else 'would be deleted'}")
return 0
def self_test():
with tempfile.TemporaryDirectory() as tmp:
t = Path(tmp)
(t / "changes").mkdir()
(t / "docs" / "guide").mkdir(parents=True)
(t / "CHANGELOG.md").write_text(
"# Changelog\n\n## [Unreleased]\n\n### Fixed\n- Old fix.\n\n## [0.1.0] - 2026-01-01\n\n### Added\n- A.\n")
(t / "docs/guide/whats-new.md").write_text(
"# What's new\n\nIntro.\n\n## Version 0.1.0\n\n```features\ndate: 2026-01-01\n```\n\n- Old.\n")
(t / "changes/README.md").write_text("not a fragment\n")
(t / "changes/feat-gizmo.md").write_text(
"---\nwhats_new: **Gizmo size**: Small, Medium or Large.\nhighlight: Corner axes in three sizes\n"
"added: **Gizmo size** (Draw > Camera): Small,\n Medium and Large.\n"
"fixed: Axes no longer clip.\ntesters:\n - Click each axis end;\n the view snaps.\n - Try Large.\n---\n"
"Free notes for reviewers.\n")
(t / "changes/fix-pen.md").write_text("---\nfixed: Pen pressure on Windows Ink (#72).\n---\n")
assert run(t, "0.2.0", "--check") == 0
cjk = t / "changes/fix-lang.md" # (a language named in its own script: the app's font can't draw it)
cjk.write_text("---\nwhats_new: **Español, 繁體中文** labels.\n---\n", encoding="utf-8")
assert run(t, "0.2.0", "--check") == 1
cjk.unlink()
hl = Path(tmp) / "hl.txt"
with open(hl, "w") as out:
saved, sys.stdout = sys.stdout, out
try:
run(t, "0.1.0", "--highlights")
finally:
sys.stdout = saved
assert hl.read_text() == "Corner axes in three sizes\n", hl.read_text()
assert run(t, "0.2.0", "--apply") == 0
cl = (t / "CHANGELOG.md").read_text()
# Entries join their section; a section [Unreleased] lacks is added at its end.
assert "### Fixed\n- Old fix.\n- Axes no longer clip.\n- Pen pressure on Windows Ink (#72).\n\n### Added\n" in cl, cl
assert "### Added\n- **Gizmo size** (Draw > Camera): Small, Medium and Large.\n\n## [0.1.0]" in cl, cl
wn = (t / "docs/guide/whats-new.md").read_text()
assert wn.index("## Version 0.2.0") < wn.index("## Version 0.1.0"), wn
assert "```features\ndate: unreleased\nhighlight: Corner axes in three sizes\n```" in wn, wn
assert "- **Gizmo size**: Small, Medium or Large.\n\n## Version 0.1.0" in wn, wn
assert not (t / "changes/feat-gizmo.md").exists() and (t / "changes/README.md").exists()
# A second run with no fragments changes nothing.
assert run(t, "0.2.0", "--apply") == 0 and (t / "CHANGELOG.md").read_text() == cl
# #testers checklist
(t / "changes/a.md").write_text("---\ntesters:\n - Click each axis end;\n the view snaps.\n---\n")
assert testers("0.2.0", fragments(t)).endswith("- [ ] Click each axis end; the view snaps. (a)\n")
# Errors name the file and line.
(t / "changes/bad.md").write_text("---\nwhatsnew: typo\n---\n")
try:
fragments(t)
raise AssertionError("unknown key accepted")
except NoteError as e:
assert "bad.md:2: unknown key 'whatsnew'" in str(e), e
# Long entries wrap at 118 columns with a two-space hang.
w = wrap("word " * 40, "- ", " ")
assert all(len(l) <= 118 for l in w.splitlines()) and w.splitlines()[1].startswith(" word"), w
print("assemble_notes self-test ok")
return 0
def main(argv):
if argv == ["--self-test"]:
return self_test()
if argv == ["--check"]:
argv = ["0", "--check"]
if not argv or not re.fullmatch(r"\d+(\.\d+)*", argv[0]) or len(argv) > 2:
print(__doc__)
return 2
mode = argv[1] if len(argv) == 2 else "--dry-run"
if mode not in ("--dry-run", "--apply", "--testers", "--highlights", "--check"):
print(__doc__)
return 2
try:
return run(ROOT, argv[0], mode)
except NoteError as e:
print(f"error: {e}", file=sys.stderr)
return 1
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))