Skip to content

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.

Upstream watch: weekly issues for new OpenUSD/ASWF/DCC/library releases, monthly digest

islandmed99ec6e60cccf
diff --git a/.github/workflows/upstream-watch.yml b/.github/workflows/upstream-watch.yml
new file mode 100644
index 00000000..042bdbb9
--- /dev/null
+++ b/.github/workflows/upstream-watch.yml
@@ -0,0 +1,36 @@
+# Weekly (Mondays 14:23 UTC) and on demand: compares packaging/upstream.json with the latest upstream releases
+# (tools/upstream-watch, public JSON APIs only) and opens one "upstream" issue per newer item, plus the
+# "Upstream digest YYYY-MM" issue that collects the month. Deduplicated by title, so reruns open nothing new.
+name: Upstream watch
+
+on:
+ schedule:
+ - cron: "23 14 * * 1"
+ workflow_dispatch:
+
+permissions:
+ issues: write
+ contents: read
+
+concurrency:
+ group: upstream-watch
+
+jobs:
+ watch:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ sparse-checkout: |
+ tools/upstream-watch
+ packaging/upstream.json
+ tests/upstream
+ tests/data/upstream
+ sparse-checkout-cone-mode: false
+ - name: Unit tests (recorded responses)
+ run: python3 -I tests/upstream/test_upstream_watch.py
+ - name: Check upstream and file issues
+ env:
+ GITHUB_TOKEN: ${{ github.token }}
+ run: python3 -I tools/upstream-watch/upstream_watch.py run --repo "${{ github.repository }}"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f29c9447..d50ccc5c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,11 @@ All notable changes to SculptForge are listed here. The format follows
## [Unreleased]
+### Added
+- Upstream watch for studios: a weekly check of OpenUSD, MaterialX, OpenColorIO, OpenEXR, OpenVDB, OpenSubdiv,
+ OpenTimelineIO, OpenAssetIO, the VFX Reference Platform, Blender, Unreal Engine, Godot, SDL3, Dear ImGui and Python
+ opens a tracking issue for each new release, plus a monthly "Upstream digest" (targets in `packaging/upstream.json`).
+
## [0.10.7] - 2026-11-01
### Changed
diff --git a/CMakeLists.txt b/CMakeLists.txt
index a54b9989..dd32676c 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -602,6 +602,8 @@ if(SCULPTFORGE_BUILD_TESTS)
--cli ${SCULPTFORGE_CLI_RUNNER} --out ${CMAKE_CURRENT_BINARY_DIR}/release-smoke)
# Proof mode results: the validator and website list tool (tools/benchmark/submit.py, docs/benchmark.md).
add_test(NAME benchmark_submit COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/benchmark/submit.py selftest)
+ # The upstream watch (tools/upstream-watch, .github/workflows/upstream-watch.yml) against recorded API responses.
+ add_test(NAME upstream_watch COMMAND ${Python3_EXECUTABLE} -I ${CMAKE_CURRENT_SOURCE_DIR}/tests/upstream/test_upstream_watch.py)
add_test(NAME guide_site COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/guide/build_site.py --check
--out ${CMAKE_CURRENT_BINARY_DIR}/guide-site)
endif()
diff --git a/packaging/upstream.json b/packaging/upstream.json
new file mode 100644
index 00000000..a1fddcc7
--- /dev/null
+++ b/packaging/upstream.json
@@ -0,0 +1,37 @@
+{
+ "_comment": "Versions SculptForge targets, checked weekly by .github/workflows/upstream-watch.yml (tools/upstream-watch). Bump an item when its upstream issue is done. track: minor/major compares only those parts (patch releases don't open issues).",
+ "items": [
+ {"name": "OpenUSD", "version": "26.11", "track": "minor", "source": {"kind": "github", "repo": "PixarAnimationStudios/OpenUSD"},
+ "why": "USD export/import and the studio pipeline (docs/studios.md)."},
+ {"name": "MaterialX", "version": "1.39.5", "source": {"kind": "github", "repo": "AcademySoftwareFoundation/MaterialX"}},
+ {"name": "OpenColorIO", "version": "2.6.0", "source": {"kind": "github", "repo": "AcademySoftwareFoundation/OpenColorIO"}},
+ {"name": "OpenEXR", "version": "3.5", "track": "minor", "source": {"kind": "github", "repo": "AcademySoftwareFoundation/openexr"},
+ "why": "We read and write EXR through tinyexr; check the new version's files still load."},
+ {"name": "OpenVDB", "version": "14.0.0", "source": {"kind": "github", "repo": "AcademySoftwareFoundation/openvdb"}},
+ {"name": "OpenSubdiv", "version": "3.8.0", "source": {"kind": "github", "repo": "PixarAnimationStudios/OpenSubdiv"}},
+ {"name": "OpenTimelineIO", "version": "0.18.1", "source": {"kind": "github", "repo": "AcademySoftwareFoundation/OpenTimelineIO", "prerelease": true}},
+ {"name": "OpenAssetIO", "version": "1.0.2", "source": {"kind": "github", "repo": "OpenAssetIO/OpenAssetIO"}},
+ {"name": "VFX Reference Platform", "version": "CY2027",
+ "source": {"kind": "github_dir", "repo": "ves-tech/vfxplatform", "path": "_data/platforms", "name": "^CY(\\d{4})\\.yml$"},
+ "notes": "https://vfxplatform.com/", "why": "Update the table in docs/studios.md, the rez package and the CI VFX builds."},
+ {"name": "Blender", "version": "5.2", "track": "minor", "source": {"kind": "endoflife", "product": "blender"},
+ "notes": "https://www.blender.org/download/releases/{major}-{minor}/", "why": "Add it to the bpy matrix in ci.yml and test the Blender bridge."},
+ {"name": "Unreal Engine", "version": "5.8", "track": "minor",
+ "source": {"kind": "page_title", "url": "https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-5-8-release-notes",
+ "title": "Unreal Engine (\\d+\\.\\d+) Release Notes"},
+ "notes": "https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-{major}-{minor}-release-notes"},
+ {"name": "Godot", "version": "4.7", "track": "minor", "source": {"kind": "github", "repo": "godotengine/godot", "tag": "^(\\d+(?:\\.\\d+)*)-stable$"},
+ "notes": "https://godotengine.org/releases/{major}.{minor}/"},
+ {"name": "SDL3", "version": "3.2", "track": "minor", "source": {"kind": "github", "repo": "libsdl-org/SDL", "tag": "^release-(3\\.\\d+\\.\\d+)$"},
+ "why": "Pinned in cmake/Dependencies.cmake (3.2.30)."},
+ {"name": "Dear ImGui", "version": "1.91.9", "source": {"kind": "github", "repo": "ocornut/imgui"},
+ "why": "Pinned in cmake/Dependencies.cmake."},
+ {"name": "Python", "version": "3.13", "track": "minor", "source": {"kind": "endoflife", "product": "python"},
+ "notes": "https://docs.python.org/{major}.{minor}/whatsnew/{major}.{minor}.html",
+ "why": "The module follows the VFX Reference Platform's Python; test it on the new version, switch when the platform does."}
+ ],
+ "skipped": {
+ "Houdini": "SideFX publishes no public release-notes RSS or JSON",
+ "Maya": "Autodesk publishes no public release-notes RSS or JSON"
+ }
+}
diff --git a/tests/data/upstream/opensubdiv_releases.json b/tests/data/upstream/opensubdiv_releases.json
new file mode 100644
index 00000000..fc072241
--- /dev/null
+++ b/tests/data/upstream/opensubdiv_releases.json
@@ -0,0 +1,26 @@
+[
+ {
+ "tag_name": "v3_8_0",
+ "html_url": "https://github.com/PixarAnimationStudios/OpenSubdiv/releases/tag/v3_8_0",
+ "draft": false,
+ "prerelease": false
+ },
+ {
+ "tag_name": "v3_7_0",
+ "html_url": "https://github.com/PixarAnimationStudios/OpenSubdiv/releases/tag/v3_7_0",
+ "draft": false,
+ "prerelease": false
+ },
+ {
+ "tag_name": "v3_6_1",
+ "html_url": "https://github.com/PixarAnimationStudios/OpenSubdiv/releases/tag/v3_6_1",
+ "draft": false,
+ "prerelease": false
+ },
+ {
+ "tag_name": "v3_6_0",
+ "html_url": "https://github.com/PixarAnimationStudios/OpenSubdiv/releases/tag/v3_6_0",
+ "draft": false,
+ "prerelease": false
+ }
+]
diff --git a/tests/data/upstream/otio_releases.json b/tests/data/upstream/otio_releases.json
new file mode 100644
index 00000000..f6acb229
--- /dev/null
+++ b/tests/data/upstream/otio_releases.json
@@ -0,0 +1,32 @@
+[
+ {
+ "tag_name": "v0.18.1",
+ "html_url": "https://github.com/AcademySoftwareFoundation/OpenTimelineIO/releases/tag/v0.18.1",
+ "draft": false,
+ "prerelease": true
+ },
+ {
+ "tag_name": "v0.18.0",
+ "html_url": "https://github.com/AcademySoftwareFoundation/OpenTimelineIO/releases/tag/v0.18.0",
+ "draft": false,
+ "prerelease": true
+ },
+ {
+ "tag_name": "v0.17.0",
+ "html_url": "https://github.com/AcademySoftwareFoundation/OpenTimelineIO/releases/tag/v0.17.0",
+ "draft": false,
+ "prerelease": true
+ },
+ {
+ "tag_name": "v0.16.0",
+ "html_url": "https://github.com/AcademySoftwareFoundation/OpenTimelineIO/releases/tag/v0.16.0",
+ "draft": false,
+ "prerelease": true
+ },
+ {
+ "tag_name": "v0.17.0.dev1",
+ "html_url": "https://github.com/AcademySoftwareFoundation/OpenTimelineIO/releases/tag/v0.17.0.dev1",
+ "draft": false,
+ "prerelease": true
+ }
+]
diff --git a/tests/data/upstream/python_eol.json b/tests/data/upstream/python_eol.json
new file mode 100644
index 00000000..1354cceb
--- /dev/null
+++ b/tests/data/upstream/python_eol.json
@@ -0,0 +1,18 @@
+[
+ {
+ "cycle": "3.15",
+ "latest": "3.15.2"
+ },
+ {
+ "cycle": "3.14",
+ "latest": "3.14.10"
+ },
+ {
+ "cycle": "3.13",
+ "latest": "3.13.18"
+ },
+ {
+ "cycle": "3.12",
+ "latest": "3.12.16"
+ }
+]
diff --git a/tests/data/upstream/sdl_releases.json b/tests/data/upstream/sdl_releases.json
new file mode 100644
index 00000000..4b0a6794
--- /dev/null
+++ b/tests/data/upstream/sdl_releases.json
@@ -0,0 +1,50 @@
+[
+ {
+ "tag_name": "release-3.4.18",
+ "html_url": "https://github.com/libsdl-org/SDL/releases/tag/release-3.4.18",
+ "draft": false,
+ "prerelease": false
+ },
+ {
+ "tag_name": "release-3.4.16",
+ "html_url": "https://github.com/libsdl-org/SDL/releases/tag/release-3.4.16",
+ "draft": false,
+ "prerelease": false
+ },
+ {
+ "tag_name": "release-3.4.14",
+ "html_url": "https://github.com/libsdl-org/SDL/releases/tag/release-3.4.14",
+ "draft": false,
+ "prerelease": false
+ },
+ {
+ "tag_name": "release-3.4.12",
+ "html_url": "https://github.com/libsdl-org/SDL/releases/tag/release-3.4.12",
+ "draft": false,
+ "prerelease": false
+ },
+ {
+ "tag_name": "release-3.4.10",
+ "html_url": "https://github.com/libsdl-org/SDL/releases/tag/release-3.4.10",
+ "draft": false,
+ "prerelease": false
+ },
+ {
+ "tag_name": "release-3.4.8",
+ "html_url": "https://github.com/libsdl-org/SDL/releases/tag/release-3.4.8",
+ "draft": false,
+ "prerelease": false
+ },
+ {
+ "tag_name": "release-2.32.10",
+ "html_url": "https://github.com/libsdl-org/SDL/releases/tag/release-2.32.10",
+ "draft": false,
+ "prerelease": false
+ },
+ {
+ "tag_name": "preview-3.5.0",
+ "html_url": "x",
+ "draft": false,
+ "prerelease": true
+ }
+]
diff --git a/tests/data/upstream/unreal_challenge.html b/tests/data/upstream/unreal_challenge.html
new file mode 100644
index 00000000..540b5d77
--- /dev/null
+++ b/tests/data/upstream/unreal_challenge.html
@@ -0,0 +1 @@
+<!doctype html><html><head><title>Just a moment...</title></head><body>challenge</body></html>
diff --git a/tests/data/upstream/unreal_notes.html b/tests/data/upstream/unreal_notes.html
new file mode 100644
index 00000000..585f7b74
--- /dev/null
+++ b/tests/data/upstream/unreal_notes.html
@@ -0,0 +1 @@
+<!doctype html><html><head><meta charset="utf-8"><title>Unreal Engine 5.8 Release Notes | Unreal Engine 5.8 Documentation | Epic Developer Community</title></head><body></body></html>
diff --git a/tests/data/upstream/vfx_platforms.json b/tests/data/upstream/vfx_platforms.json
new file mode 100644
index 00000000..7f100dcf
--- /dev/null
+++ b/tests/data/upstream/vfx_platforms.json
@@ -0,0 +1,18 @@
+[
+ {
+ "name": "CY2024.yml",
+ "type": "file"
+ },
+ {
+ "name": "CY2025.yml",
+ "type": "file"
+ },
+ {
+ "name": "CY2026.yml",
+ "type": "file"
+ },
+ {
+ "name": "CY2027.yml",
+ "type": "file"
+ }
+]
diff --git a/tests/upstream/test_upstream_watch.py b/tests/upstream/test_upstream_watch.py
new file mode 100755
index 00000000..2b7e9658
--- /dev/null
+++ b/tests/upstream/test_upstream_watch.py
@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+# SculptForge - open source digital sculpting
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""tools/upstream-watch against recorded API responses (tests/data/upstream): version comparison, each source,
+issue dedupe by title, superseded issues, the monthly digest, and that packaging/upstream.json is well formed."""
+import datetime
+import json
+import pathlib
+import sys
+import unittest
+import urllib.error
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+DATA = ROOT / "tests" / "data" / "upstream"
+sys.path.insert(0, str(ROOT / "tools" / "upstream-watch"))
+import upstream_watch as uw
+
+TODAY = datetime.date(2026, 11, 2)
+REPO = "example/sculptforge"
+
+
+class Recorded:
+ """Serves recorded responses by URL substring and records every write."""
+
+ def __init__(self, routes, issues=()):
+ self.routes, self.issues, self.writes, self.next = routes, list(issues), [], 100
+
+ def _find(self, url):
+ for key, value in self.routes.items():
+ if key in url:
+ if isinstance(value, Exception):
+ raise value
+ return (DATA / value).read_text() if isinstance(value, str) else value
+ raise urllib.error.URLError(f"no recording for {url}")
+
+ def get(self, url):
+ if "/issues?" in url:
+ return self.issues if "page=1" in url else []
+ return json.loads(self._find(url))
+
+ def get_text(self, url):
+ return self._find(url)
+
+ def post(self, url, body):
+ self.writes.append(("POST", url, body))
+ if url.endswith("/issues"):
+ self.next += 1
+ return {"number": self.next}
+ return {}
+
+ def patch(self, url, body):
+ self.writes.append(("PATCH", url, body))
+ return {}
+
+
+ROUTES = {"libsdl-org/SDL": "sdl_releases.json", "OpenTimelineIO": "otio_releases.json",
+ "OpenSubdiv": "opensubdiv_releases.json", "endoflife.date/api/python": "python_eol.json",
+ "ves-tech/vfxplatform": "vfx_platforms.json", "dev.epicgames.com": "unreal_notes.html"}
+
+ITEMS = [
+ {"name": "SDL3", "version": "3.2", "track": "minor",
+ "source": {"kind": "github", "repo": "libsdl-org/SDL", "tag": r"^release-(3\.\d+\.\d+)$"}},
+ {"name": "OpenTimelineIO", "version": "0.18.1",
+ "source": {"kind": "github", "repo": "AcademySoftwareFoundation/OpenTimelineIO", "prerelease": True}},
+ {"name": "OpenSubdiv", "version": "3.7.0", "source": {"kind": "github", "repo": "PixarAnimationStudios/OpenSubdiv"}},
+ {"name": "Python", "version": "3.13", "track": "minor", "source": {"kind": "endoflife", "product": "python"},
+ "notes": "https://docs.python.org/{major}.{minor}/whatsnew/{major}.{minor}.html"},
+ {"name": "VFX Reference Platform", "version": "CY2026", "notes": "https://vfxplatform.com/",
+ "source": {"kind": "github_dir", "repo": "ves-tech/vfxplatform", "path": "_data/platforms", "name": r"^CY(\d{4})\.yml$"}},
+ {"name": "Unreal Engine", "version": "5.8", "track": "minor",
+ "source": {"kind": "page_title", "url": "https://dev.epicgames.com/x", "title": r"Unreal Engine (\d+\.\d+) Release Notes"}},
+]
+
+
+class Versions(unittest.TestCase):
+ def test_parse(self):
+ self.assertEqual(uw.parse_version("v3_6_1"), (3, 6, 1))
+ self.assertEqual(uw.parse_version("release-3.2.30"), (3, 2, 30))
+ self.assertEqual(uw.parse_version("v25.08"), (25, 8))
+ self.assertEqual(uw.parse_version("CY2027"), (2027,))
+ self.assertIsNone(uw.parse_version("latest"))
+
+ def test_compare(self):
+ self.assertTrue(uw.is_newer((26, 11), (26, 8)))
+ self.assertTrue(uw.is_newer((1, 93, 0), (1, 91, 9)))
+ self.assertFalse(uw.is_newer((25, 5), (25, 5, 0))) # missing parts count as 0
+ self.assertTrue(uw.is_newer((25, 5, 1), (25, 5)))
+ self.assertFalse(uw.is_newer((3, 2, 31), (3, 2), "minor")) # patch releases don't count at minor
+ self.assertTrue(uw.is_newer((3, 4, 0), (3, 2, 30), "minor"))
+ self.assertFalse(uw.is_newer((3, 15, 0), (3, 13), "major"))
+ self.assertFalse(uw.is_newer((1, 0), (1, 0, 2)))
+
+
+class Sources(unittest.TestCase):
+ def setUp(self):
+ self.http = Recorded(ROUTES)
+
+ def test_github_filters_tags_and_prereleases(self):
+ v, link = uw.latest_github(ITEMS[0]["source"], self.http)
+ self.assertEqual(v, (3, 4, 18)) # not SDL 2.x, not the 3.5 preview
+ self.assertTrue(link.endswith("release-3.4.18"))
+
+ def test_github_prerelease_opt_in(self):
+ self.assertEqual(uw.latest_github(ITEMS[1]["source"], self.http)[0], (0, 18, 1))
+ with self.assertRaises(ValueError): # every OTIO release is marked prerelease
+ uw.latest_github({"repo": "AcademySoftwareFoundation/OpenTimelineIO"}, self.http)
+
+ def test_underscore_tags(self):
+ self.assertEqual(uw.latest_github(ITEMS[2]["source"], self.http)[0], (3, 8, 0))
+
+ def test_endoflife(self):
+ self.assertEqual(uw.latest_endoflife(ITEMS[3]["source"], self.http)[0][:2], (3, 15))
+
+ def test_vfx_platform(self):
+ self.assertEqual(uw.latest_github_dir(ITEMS[4]["source"], self.http)[0], (2027,))
+
+ def test_unreal_title_and_bot_check(self):
+ self.assertEqual(uw.latest_page_title(ITEMS[5]["source"], self.http)[0], (5, 8))
+ blocked = Recorded({"dev.epicgames.com": "unreal_challenge.html"})
+ with self.assertRaises(ValueError):
+ uw.latest_page_title(ITEMS[5]["source"], blocked)
+
+ def test_survey_reports_failures_without_stopping(self):
+ http = Recorded({**ROUTES, "OpenSubdiv": urllib.error.URLError("timed out")})
+ behind, failed = uw.survey({"items": ITEMS}, http)
+ self.assertEqual([e["name"] for e in behind], ["SDL3", "Python", "VFX Reference Platform"])
+ self.assertEqual([f["name"] for f in failed], ["OpenSubdiv"])
+ sdl, py, vfx = behind
+ self.assertEqual(sdl["latest"], "3.4")
+ self.assertEqual(py["link"], "https://docs.python.org/3.15/whatsnew/3.15.html")
+ self.assertEqual(vfx["latest"], "2027")
+
+
+class Issues(unittest.TestCase):
+ def behind(self):
+ return uw.survey({"items": ITEMS}, Recorded(ROUTES))[0]
+
+ def test_new_items_open_issues_and_digest(self):
+ http = Recorded(ROUTES)
+ behind = self.behind()
+ actions, numbers = uw.plan(behind, [], [], TODAY)
+ uw.apply(actions, numbers, behind, [], http, REPO, TODAY, out=lambda *_: None)
+ titles = [b["title"] for m, u, b in http.writes if m == "POST"]
+ self.assertEqual(titles, ["Upstream: SDL3 3.4", "Upstream: OpenSubdiv 3.8.0", "Upstream: Python 3.15",
+ "Upstream: VFX Reference Platform 2027", "Upstream digest 2026-11"])
+ for _, _, body in http.writes:
+ self.assertEqual(body["labels"], ["upstream"])
+ first = http.writes[0][2]["body"]
+ for part in ("3.4", "targets 3.2", "release-3.4.18", "- [ ] Bump", "- [ ] Test", "- [ ] Notes"):
+ self.assertIn(part, first)
+ digest = http.writes[-1][2]["body"]
+ self.assertIn("| SDL3 | 3.2 |", digest)
+ self.assertIn("#101", digest) # links the issue opened in the same run
+
+ def test_dedupe_by_title_open_or_closed(self):
+ existing = [{"title": "Upstream: SDL3 3.4", "number": 7, "state": "closed"},
+ {"title": "Upstream: Python 3.15", "number": 8, "state": "open"},
+ {"title": "Upstream: OpenSubdiv 3.8.0", "number": 9, "state": "open"},
+ {"title": "Upstream: VFX Reference Platform 2027", "number": 10, "state": "open"},
+ {"title": "Upstream digest 2026-11", "number": 11, "state": "open"}]
+ actions, numbers = uw.plan(self.behind(), [], existing, TODAY)
+ self.assertEqual(actions, [("update", 11, None)])
+ http = Recorded(ROUTES)
+ uw.apply(actions, numbers, self.behind(), [], http, REPO, TODAY, out=lambda *_: None)
+ self.assertEqual(len(http.writes), 1)
+ self.assertIn("#7", http.writes[0][2]["body"])
+
+ def test_superseded_issue_is_closed(self):
+ existing = [{"title": "Upstream: Python 3.14", "number": 5, "state": "open"},
+ {"title": "Upstream: Python 3.12", "number": 4, "state": "closed"},
+ {"title": "Upstream: Python Tools 1.0", "number": 3, "state": "open"}]
+ py = [e for e in self.behind() if e["name"] == "Python"]
+ actions, _ = uw.plan(py, [], existing, TODAY)
+ self.assertIn(("create", "Upstream: Python 3.15", uw.issue_body(py[0])), actions)
+ self.assertIn(("close", 5, "Superseded by Python 3.15."), actions)
+ self.assertNotIn(4, [a[1] for a in actions if a[0] == "close"])
+ # "Python Tools" starts with "Upstream: Python " too: only a same-name issue is superseded.
+ self.assertNotIn(3, [a[1] for a in actions if a[0] == "close"])
+
+ def test_quiet_month_opens_nothing(self):
+ actions, _ = uw.plan([], [{"name": "Unreal Engine", "error": "bot check"}], [], TODAY)
+ self.assertEqual(actions, [])
+
+ def test_digest_lists_unchecked_sources(self):
+ body = uw.digest_body([], [{"name": "Unreal Engine", "error": "bot check"}], {}, TODAY)
+ self.assertIn("Everything we track is current", body)
+ self.assertIn("Unreal Engine (bot check)", body)
+
+
+class Config(unittest.TestCase):
+ def test_upstream_json(self):
+ config = uw.load_config(uw.DEFAULT_CONFIG)
+ names = [i["name"] for i in config["items"]]
+ self.assertEqual(len(names), len(set(names)))
+ for item in config["items"]:
+ self.assertIn(item["source"]["kind"], uw.SOURCES, item["name"])
+ self.assertIsNotNone(uw.parse_version(item["version"]), item["name"])
+ self.assertIn(item.get("track", "patch"), ("patch", "minor", "major"), item["name"])
+ if "notes" in item:
+ uw.notes_link(item, (1, 2, 3), None)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tools/upstream-watch/upstream_watch.py b/tools/upstream-watch/upstream_watch.py
new file mode 100755
index 00000000..867911a7
--- /dev/null
+++ b/tools/upstream-watch/upstream_watch.py
@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+# SculptForge - open source digital sculpting
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Watches the upstream projects SculptForge targets and opens a GitHub issue when one has a newer release.
+
+ upstream_watch.py check print each item's targeted and latest version (no token needed)
+ upstream_watch.py run --repo OWNER/NAME open one issue per newer item and update the monthly digest
+ [--dry-run] print what it would do instead
+
+The targeted versions live in packaging/upstream.json; bump an item there when the issue's checklist is done.
+Only public JSON APIs are read (GitHub REST, endoflife.date); Unreal Engine has none, so only the <title> of its
+release notes page is read. Issues get the "upstream" label and are deduplicated by title; an older open issue
+for the same item is closed as superseded. "Upstream digest YYYY-MM" collects everything behind that month.
+Stdlib only, so the workflow needs no installs.
+"""
+import argparse
+import datetime
+import json
+import os
+import pathlib
+import re
+import sys
+import urllib.error
+import urllib.request
+
+ROOT = pathlib.Path(__file__).resolve().parents[2]
+DEFAULT_CONFIG = ROOT / "packaging" / "upstream.json"
+LABEL = "upstream"
+API = "https://api.github.com"
+DEFAULT_TAG = r"^v?(\d+(?:[._]\d+)*)[a-z]?$"
+UA = "sculptforge-upstream-watch"
+
+
+def parse_version(text):
+ """'v3_6_1' / 'release-3.2.30' / '25.08' -> (3, 6, 1) etc.; None when there are no digits."""
+ parts = re.findall(r"\d+", text or "")
+ return tuple(int(p) for p in parts) if parts else None
+
+
+def truncate(version, track):
+ """Keeps the components an item is tracked at: 'minor' -> 2, 'major' -> 1, 'patch' (default) -> all."""
+ n = {"major": 1, "minor": 2}.get(track)
+ return version[:n] if n else version
+
+
+def fmt(version):
+ return ".".join(str(p) for p in version)
+
+
+def is_newer(latest, targeted, track=None):
+ """True when latest is past targeted at the item's tracking granularity (missing parts count as 0)."""
+ a, b = truncate(latest, track), truncate(targeted, track)
+ width = max(len(a), len(b))
+ return a + (0,) * (width - len(a)) > b + (0,) * (width - len(b))
+
+
+class Http:
+ """GET/POST/PATCH JSON. Tests replace it with a recorded one."""
+
+ def __init__(self, token=None):
+ self.token = token
+
+ def request(self, method, url, body=None, accept="application/json"):
+ headers = {"User-Agent": UA, "Accept": accept}
+ if self.token and url.startswith(API):
+ headers["Authorization"] = f"Bearer {self.token}"
+ headers["X-GitHub-Api-Version"] = "2022-11-28"
+ data = None
+ if body is not None:
+ data = json.dumps(body).encode()
+ headers["Content-Type"] = "application/json"
+ req = urllib.request.Request(url, data=data, headers=headers, method=method)
+ with urllib.request.urlopen(req, timeout=30) as r:
+ raw = r.read().decode("utf-8", "replace")
+ if "json" in accept:
+ return json.loads(raw) if raw else None
+ return raw
+
+ def get(self, url):
+ return self.request("GET", url)
+
+ def get_text(self, url):
+ return self.request("GET", url, accept="text/html")
+
+ def post(self, url, body):
+ return self.request("POST", url, body)
+
+ def patch(self, url, body):
+ return self.request("PATCH", url, body)
+
+
+# --- latest-version sources: each returns (version tuple, release-notes link) or raises ---
+
+def latest_github(src, http):
+ pat = re.compile(src.get("tag", DEFAULT_TAG))
+ best = None
+ for rel in http.get(f"{API}/repos/{src['repo']}/releases?per_page=30") or []:
+ if rel.get("draft") or (rel.get("prerelease") and not src.get("prerelease")):
+ continue
+ m = pat.match(rel.get("tag_name", ""))
+ v = parse_version(m.group(1)) if m else None
+ if v and (best is None or v > best[0]):
+ best = (v, rel.get("html_url") or f"https://github.com/{src['repo']}/releases")
+ if not best:
+ raise ValueError(f"no release of {src['repo']} matches {pat.pattern}")
+ return best
+
+
+def latest_endoflife(src, http):
+ best = None
+ for cycle in http.get(f"https://endoflife.date/api/{src['product']}.json") or []:
+ v = parse_version(str(cycle.get("latest", "")))
+ if v and (best is None or v > best):
+ best = v
+ if not best:
+ raise ValueError(f"endoflife.date has no releases of {src['product']}")
+ return best, None
+
+
+def latest_github_dir(src, http):
+ """Newest file name in a repo directory, e.g. the VFX Reference Platform's _data/platforms/CY2027.yml."""
+ pat = re.compile(src["name"])
+ best = None
+ for entry in http.get(f"{API}/repos/{src['repo']}/contents/{src['path']}") or []:
+ m = pat.match(entry.get("name", ""))
+ v = parse_version(m.group(1)) if m else None
+ if v and (best is None or v > best):
+ best = v
+ if not best:
+ raise ValueError(f"nothing in {src['repo']}/{src['path']} matches {pat.pattern}")
+ return best, None
+
+
+def latest_page_title(src, http):
+ """Unreal Engine has no public API: its release notes URL opens the newest version, named in the <title>."""
+ html = http.get_text(src["url"])
+ m = re.search(r"<title>[^<]*?" + src["title"], html or "", re.IGNORECASE)
+ if not m:
+ raise ValueError("release notes title not found (the page may be behind a bot check)")
+ return parse_version(m.group(1)), None
+
+
+SOURCES = {"github": latest_github, "endoflife": latest_endoflife, "github_dir": latest_github_dir,
+ "page_title": latest_page_title}
+
+
+def notes_link(item, version, found):
+ tmpl = item.get("notes")
+ if tmpl:
+ return tmpl.format(version=fmt(version), major=version[0], minor=version[1] if len(version) > 1 else 0,
+ nodots="".join(str(p) for p in version))
+ return found or ""
+
+
+def survey(config, http):
+ """Returns (behind, failed): items with a newer release, and items whose source couldn't be read."""
+ behind, failed = [], []
+ for item in config["items"]:
+ src = item["source"]
+ try:
+ latest, found = SOURCES[src["kind"]](src, http)
+ except (urllib.error.URLError, ValueError, KeyError, TypeError, OSError) as e:
+ failed.append({"name": item["name"], "error": str(e)})
+ continue
+ targeted = parse_version(item["version"])
+ if is_newer(latest, targeted, item.get("track")):
+ shown = truncate(latest, item.get("track"))
+ behind.append({"name": item["name"], "targeted": item["version"], "latest": fmt(shown),
+ "link": notes_link(item, shown, found), "why": item.get("why", "")})
+ return behind, failed
+
+
+# --- issues ---
+
+def issue_title(entry):
+ return f"Upstream: {entry['name']} {entry['latest']}"
+
+
+def digest_title(today):
+ return f"Upstream digest {today:%Y-%m}"
+
+
+def issue_body(entry):
+ why = f"\n{entry['why']}\n" if entry["why"] else ""
+ link = entry["link"] or "(see the project's site)"
+ return (f"**{entry['name']} {entry['latest']}** is out; `packaging/upstream.json` targets {entry['targeted']}.\n"
+ f"{why}\nRelease notes: {link}\n\n"
+ f"- [ ] Bump (dependency, CI matrix or docs that name the version; then `packaging/upstream.json`)\n"
+ f"- [ ] Test (full ctest; the integration it affects, if any)\n"
+ f"- [ ] Notes (CHANGELOG / What's New line if users see a difference)\n\n"
+ f"_Opened by .github/workflows/upstream-watch.yml._")
+
+
+def digest_body(behind, failed, numbers, today):
+ lines = [f"What changed upstream as of {today:%Y-%m-%d} (updated by every weekly run this month).", ""]
+ if behind:
+ lines += ["| Project | We target | Latest | Issue |", "|---|---|---|---|"]
+ for e in behind:
+ num = numbers.get(issue_title(e))
+ latest = f"[{e['latest']}]({e['link']})" if e["link"] else e["latest"]
+ lines.append(f"| {e['name']} | {e['targeted']} | {latest} | {f'#{num}' if num else ''} |")
+ else:
+ lines.append("Everything we track is current.")
+ if failed:
+ lines += ["", "Couldn't check: " + "; ".join(f"{f['name']} ({f['error']})" for f in failed)]
+ return "\n".join(lines)
+
+
+def list_issues(http, repo):
+ """Every issue (open and closed, no PRs) with the upstream label."""
+ out, page = [], 1
+ while True:
+ batch = http.get(f"{API}/repos/{repo}/issues?labels={LABEL}&state=all&per_page=100&page={page}") or []
+ out += [i for i in batch if "pull_request" not in i]
+ if len(batch) < 100:
+ return out
+ page += 1
+
+
+def plan(behind, failed, existing, today):
+ """Pure: what to do, given the survey and the existing upstream issues.
+
+ Returns a list of actions: ("create", title, body), ("close", number, comment), ("update", number, body)."""
+ by_title = {i["title"]: i for i in existing}
+ actions, numbers = [], {t: i["number"] for t, i in by_title.items()}
+ for e in behind:
+ title = issue_title(e)
+ if title in by_title:
+ continue
+ actions.append(("create", title, issue_body(e)))
+ prefix = f"Upstream: {e['name']} "
+ for i in existing:
+ rest = i["title"][len(prefix):] if i["title"].startswith(prefix) else ""
+ if i["state"] == "open" and rest and " " not in rest and i["title"] != title:
+ actions.append(("close", i["number"], f"Superseded by {e['name']} {e['latest']}."))
+ dtitle = digest_title(today)
+ if dtitle in by_title:
+ actions.append(("update", by_title[dtitle]["number"], None))
+ elif behind:
+ actions.append(("create", dtitle, None))
+ return actions, numbers
+
+
+def apply(actions, numbers, behind, failed, http, repo, today, out=print):
+ """Runs the planned actions; the digest body is written last so it can link the issues just opened."""
+ base = f"{API}/repos/{repo}"
+ digest = digest_title(today)
+ for kind, key, body in actions:
+ if kind == "create" and key != digest:
+ made = http.post(f"{base}/issues", {"title": key, "body": body, "labels": [LABEL]})
+ numbers[key] = made["number"]
+ out(f"opened #{made['number']} {key}")
+ elif kind == "close":
+ http.post(f"{base}/issues/{key}/comments", {"body": body})
+ http.patch(f"{base}/issues/{key}", {"state": "closed", "state_reason": "not_planned"})
+ out(f"closed #{key} ({body})")
+ for kind, key, _ in actions:
+ if kind == "create" and key == digest:
+ made = http.post(f"{base}/issues", {"title": key, "labels": [LABEL],
+ "body": digest_body(behind, failed, numbers, today)})
+ out(f"opened #{made['number']} {key}")
+ elif kind == "update":
+ http.patch(f"{base}/issues/{key}", {"body": digest_body(behind, failed, numbers, today)})
+ out(f"updated #{key} {digest}")
+
+
+def ensure_label(http, repo):
+ try:
+ http.post(f"{API}/repos/{repo}/labels",
+ {"name": LABEL, "color": "0e8a16", "description": "A newer upstream release to adopt"})
+ except urllib.error.HTTPError as e:
+ if e.code != 422: # 422: it already exists
+ raise
+
+
+def load_config(path):
+ return json.loads(pathlib.Path(path).read_text())
+
+
+def main(argv=None):
+ ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+ ap.add_argument("command", choices=("check", "run"))
+ ap.add_argument("--config", default=DEFAULT_CONFIG)
+ ap.add_argument("--repo", default=os.environ.get("GITHUB_REPOSITORY"))
+ ap.add_argument("--dry-run", action="store_true")
+ args = ap.parse_args(argv)
+ config = load_config(args.config)
+ http = Http(os.environ.get("GITHUB_TOKEN"))
+ today = datetime.date.today()
+ behind, failed = survey(config, http)
+ if args.command == "check":
+ names = {e["name"]: e for e in behind}
+ for item in config["items"]:
+ e = names.get(item["name"])
+ print(f"{item['name']:22} {item['version']:10} {'-> ' + e['latest'] if e else 'current'}")
+ for f in failed:
+ print(f"{f['name']:22} could not check: {f['error']}")
+ for name, why in config.get("skipped", {}).items():
+ print(f"{name:22} skipped: {why}")
+ return 0
+ if not args.repo:
+ ap.error("--repo or GITHUB_REPOSITORY is needed")
+ existing = list_issues(http, args.repo)
+ actions, numbers = plan(behind, failed, existing, today)
+ if args.dry_run:
+ for kind, key, _ in actions:
+ print(f"would {kind} {key}")
+ return 0
+ if actions:
+ ensure_label(http, args.repo)
+ apply(actions, numbers, behind, failed, http, args.repo, today)
+ for f in failed:
+ print(f"::warning::{f['name']}: {f['error']}")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())