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.

CI under 10 min for branches; release notes from note fragments

islandmedfc4739bf1391
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index ddd904f5..08693fbc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -4,7 +4,14 @@ on:
push:
branches: [main]
pull_request:
+ types: [opened, synchronize, reopened, labeled]
+ merge_group: # the merge queue (docs/merge-queue.md): every PR is tested on top of main before it lands
workflow_dispatch:
+ inputs:
+ full:
+ description: Also the VFX Reference Platform and Blender add-on jobs (main always runs them)
+ type: boolean
+ default: false
permissions:
contents: read
@@ -16,7 +23,7 @@ concurrency:
# Compiler cache (ccache). Every job compiles through ccache and starts from the newest cache of the same job; ccache
# hashes the compiler and the preprocessed source with every flag, so a hit is the object file that compiler would
# produce, and anything changed compiles fresh. Caches are saved only by push and workflow_dispatch runs (main, or a
-# maintainer's own branch): pull_request runs, forks included, only restore them (actions/cache/restore), so nothing a
+# maintainer's own branch): pull_request and merge_group runs, forks included, only restore them (actions/cache/restore), so nothing a
# pull request builds can end up in another run. GitHub scopes caches by branch as well: a branch reads its own and
# main's, never another branch's. Release packages (packages.yml) restore main's caches and never save from a tag.
# Keys are ccache-ci-<job>.<commit>: the dot keeps one job's prefix from matching another's (one key may start with another's).
@@ -31,12 +38,16 @@ concurrency:
jobs:
# Pushes and pull requests that change only the website (not its phone page, website/link, which is built into the
- # app) or release paperwork skip the build and test jobs; their required checks then pass as skipped.
+ # app), docs no build or test reads (docs/guide and docs/supporters.txt are built in), note fragments or release
+ # paperwork skip the build and test jobs; their required checks then pass as skipped.
+ # `full`: the slow platform checks (VFX Reference Platform containers, Blender add-on in Blender) run on main, in the
+ # merge queue, on a dispatch with full=true and on a pull request labelled full-ci; other branch runs skip them.
changes:
name: Changes
runs-on: ubuntu-24.04
outputs:
code: ${{ steps.diff.outputs.code }}
+ full: ${{ steps.diff.outputs.full }}
steps:
- id: diff
env:
@@ -44,9 +55,11 @@ jobs:
REPO: ${{ github.repository }}
EVENT: ${{ github.event_name }}
BEFORE: ${{ github.event.before }}
- BASE: ${{ github.event.pull_request.base.sha }}
- HEAD: ${{ github.event.pull_request.head.sha || github.sha }}
+ BASE: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha }}
+ HEAD: ${{ github.event.pull_request.head.sha || github.event.merge_group.head_sha || github.sha }}
+ FULL: ${{ github.ref == 'refs/heads/main' || github.event_name == 'merge_group' || inputs.full == true || contains(github.event.pull_request.labels.*.name, 'full-ci') }}
run: |
+ echo "full=$FULL" | tee -a "$GITHUB_OUTPUT"
base=$BASE
[ "$EVENT" = push ] && base=$BEFORE
code=true
@@ -57,7 +70,10 @@ jobs:
while IFS= read -r f; do
case "$f" in
website/link/*) code=true ;;
- website/*|.github/workflows/pages.yml|.github/workflows/download-stats.yml|packaging/arch/*|tools/publish/*|scripts/release.sh|docs/releasing.md) ;;
+ website/*|.github/workflows/pages.yml|.github/workflows/download-stats.yml|packaging/arch/*|tools/publish/*|scripts/release.sh|scripts/merge-queue.sh) ;;
+ docs/guide/*|docs/supporters.txt) code=true ;;
+ docs/*.md|docs/design/*|changes/*|.github/ISSUE_TEMPLATE/*|.github/PULL_REQUEST_TEMPLATE.md) ;;
+ CHANGELOG.md|README.md|ROADMAP.md|CONTRIBUTING.md|CODE_OF_CONDUCT.md|SECURITY.md|TESTERS.md|REPORT.md|BRIEF.md) ;;
'') ;;
*) code=true ;;
esac
@@ -81,9 +97,10 @@ jobs:
- { name: Linux ARM64, key: linux-arm64, shard: 1, shards: 2, os: "${{ vars.SF_RUNNER_LINUX_ARM || 'ubuntu-24.04-arm' }}" }
- { name: Linux ARM64, key: linux-arm64, shard: 2, shards: 2, os: "${{ vars.SF_RUNNER_LINUX_ARM || 'ubuntu-24.04-arm' }}" }
- { name: macOS, key: macos, shard: 1, shards: 1, os: "${{ vars.SF_RUNNER_MAC || 'macos-15' }}" }
- - { name: Windows, key: windows, shard: 1, shards: 3, os: "${{ vars.SF_RUNNER_WIN || 'windows-2022' }}" }
- - { name: Windows, key: windows, shard: 2, shards: 3, os: "${{ vars.SF_RUNNER_WIN || 'windows-2022' }}" }
- - { name: Windows, key: windows, shard: 3, shards: 3, os: "${{ vars.SF_RUNNER_WIN || 'windows-2022' }}" }
+ - { name: Windows, key: windows, shard: 1, shards: 4, os: "${{ vars.SF_RUNNER_WIN || 'windows-2022' }}" }
+ - { name: Windows, key: windows, shard: 2, shards: 4, os: "${{ vars.SF_RUNNER_WIN || 'windows-2022' }}" }
+ - { name: Windows, key: windows, shard: 3, shards: 4, os: "${{ vars.SF_RUNNER_WIN || 'windows-2022' }}" }
+ - { name: Windows, key: windows, shard: 4, shards: 4, os: "${{ vars.SF_RUNNER_WIN || 'windows-2022' }}" }
env:
CCACHE_DIR: ${{ github.workspace }}/.ccache
CCACHE_BASEDIR: ${{ github.workspace }}
@@ -92,6 +109,7 @@ jobs:
steps:
- uses: actions/checkout@v7
- uses: actions/setup-python@v7
+ id: py
with:
python-version: '3.13'
- name: Install Linux dependencies
@@ -132,6 +150,16 @@ jobs:
restore-keys: ccache-ci-${{ matrix.key }}.
- name: NumPy for the Python API test
run: python -m pip install numpy
+ # The configured build folder (CMake's cache with every compiler and library check, the fetched dependency
+ # sources, the generated project), right after configure and before any compiling: a hit skips the minute or
+ # more of checks (93 s on Windows). Exact key only: the runner image (compiler), Python and every CMake file, so
+ # a changed CMakeLists.txt or option configures from scratch, as a fresh checkout would.
+ - name: Configure cache (restore)
+ id: cmake-cache
+ uses: actions/cache/restore@v5
+ with:
+ path: build
+ key: cmake-ci-${{ matrix.key }}~${{ env.ImageOS }}-${{ env.ImageVersion }}-py${{ steps.py.outputs.python-version }}-${{ hashFiles('CMakeLists.txt', 'cmake/**', 'packaging/linux/install-build-deps.sh') }}
- name: Configure
if: runner.os != 'Windows'
run: >
@@ -144,13 +172,19 @@ jobs:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DSCULPTFORGE_USE_SYSTEM_SDL=OFF
-DCMAKE_VS_GLOBALS="CLToolExe=cl.exe;CLToolPath=${{ env.SF_CCACHE_CL }};TrackFileAccess=false;UseMultiToolTask=true;EnforceProcessCountAcrossBuilds=true"
-DSCULPTFORGE_BUILD_PYTHON=ON -DPython_EXECUTABLE="${{ env.pythonLocation }}/python.exe"
+ - name: Configure cache (save; a miss, not from pull requests; one shard saves)
+ if: steps.cmake-cache.outputs.cache-hit != 'true' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && matrix.shard == 1
+ uses: actions/cache/save@v5
+ with:
+ path: build
+ key: ${{ steps.cmake-cache.outputs.cache-primary-key }}
- name: Build
run: |
ccache -z
cmake --build build --config Release --parallel 4
ccache -s -v
- name: Compiler cache (save; not from pull requests; one shard saves)
- if: github.event_name != 'pull_request' && matrix.shard == 1
+ if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && matrix.shard == 1
uses: actions/cache/save@v5
with:
path: .ccache
@@ -161,10 +195,10 @@ jobs:
if: runner.os == 'Linux'
run: |
xvfb-run -a -s "-screen 0 1920x1080x24" env LIBGL_ALWAYS_SOFTWARE=1 \
- ctest --test-dir build -C Release --output-on-failure -j 4 -I '${{ matrix.shard }},,${{ matrix.shards }}'
+ ctest --test-dir build -C Release --output-on-failure --output-junit ctest.xml -j 4 -I '${{ matrix.shard }},,${{ matrix.shards }}'
- name: Test (C++ and Python API; UI tests need a display)
if: runner.os == 'macOS'
- run: ctest --test-dir build -C Release --output-on-failure -LE ui -j 4 -I '${{ matrix.shard }},,${{ matrix.shards }}'
+ run: ctest --test-dir build -C Release --output-on-failure --output-junit ctest.xml -LE ui -j 4 -I '${{ matrix.shard }},,${{ matrix.shards }}'
- name: Test (C++, Python API, UI tests with Mesa llvmpipe)
if: runner.os == 'Windows'
shell: pwsh
@@ -177,8 +211,12 @@ jobs:
}
7z e mesa.7z x64/opengl32.dll x64/libgallium_wgl.dll -obuild/Release -y | Out-Null
$env:GALLIUM_DRIVER = 'llvmpipe'
- ctest --test-dir build -C Release --output-on-failure -j 4 -I '${{ matrix.shard }},,${{ matrix.shards }}'
+ ctest --test-dir build -C Release --output-on-failure --output-junit ctest.xml -j 4 -I '${{ matrix.shard }},,${{ matrix.shards }}'
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+ - name: Slowest tests (job summary; tells which test to split when a shard is the long pole)
+ if: always()
+ run: python tools/ci/slowest_tests.py build/ctest.xml >> "$GITHUB_STEP_SUMMARY"
+ shell: bash
- name: UI test screenshots
if: always() && runner.os != 'macOS'
uses: actions/upload-artifact@v7
@@ -192,7 +230,7 @@ jobs:
blender-addon:
name: Blender add-on (bpy ${{ matrix.bpy }})
needs: changes
- if: needs.changes.outputs.code == 'true'
+ if: needs.changes.outputs.code == 'true' && needs.changes.outputs.full == 'true'
runs-on: ${{ vars.SF_RUNNER_LINUX || 'ubuntu-24.04' }}
strategy:
fail-fast: false
@@ -228,7 +266,7 @@ jobs:
cmake --build build --target sculptforge-cli --parallel 4
ccache -s -v
- name: Compiler cache (save; not from pull requests)
- if: github.event_name != 'pull_request'
+ if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
uses: actions/cache/save@v5
with:
path: .ccache
@@ -245,7 +283,7 @@ jobs:
vfx-platform:
name: VFX Reference Platform ${{ matrix.cy }} build (${{ matrix.image }})
needs: changes
- if: needs.changes.outputs.code == 'true'
+ if: needs.changes.outputs.code == 'true' && needs.changes.outputs.full == 'true'
runs-on: ${{ vars.SF_RUNNER_LINUX || 'ubuntu-24.04' }}
container: ${{ matrix.image }}
strategy:
@@ -292,7 +330,7 @@ jobs:
cmake --build build --parallel 4
ccache -s -v
- name: Compiler cache (save; not from pull requests)
- if: github.event_name != 'pull_request'
+ if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
uses: actions/cache/save@v5
with:
path: .ccache
diff --git a/.github/workflows/prune-caches.yml b/.github/workflows/prune-caches.yml
new file mode 100644
index 00000000..ed4217c6
--- /dev/null
+++ b/.github/workflows/prune-caches.yml
@@ -0,0 +1,32 @@
+name: Prune caches
+
+# Keeps only the newest Actions cache of each kind per branch (tools/ci/prune_caches.py) after CI or Packages saved
+# new ones: the repository's 10 GB cache budget otherwise evicts main's compiler caches within two pushes, and branch
+# builds then start cold (8-13 min instead of about 1). Its own workflow because deleting caches needs actions: write,
+# which Packages cannot ask for when release.yml calls it.
+
+on:
+ workflow_run:
+ workflows: [CI, Packages]
+ types: [completed]
+ workflow_dispatch:
+
+permissions:
+ actions: write
+ contents: read
+
+concurrency:
+ group: prune-caches
+ cancel-in-progress: false
+
+jobs:
+ prune:
+ name: Prune caches
+ runs-on: ubuntu-24.04
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ sparse-checkout: tools/ci
+ - env:
+ GH_TOKEN: ${{ github.token }}
+ run: python3 tools/ci/prune_caches.py ccache-ci- cmake-ci- ccache-pkg-
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 5805b256..066f3207 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -660,6 +660,13 @@ if(SCULPTFORGE_BUILD_TESTS)
add_test(NAME insider_drops COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/drops/drops.py selftest
--cli ${SCULPTFORGE_CLI_RUNNER})
set_tests_properties(insider_drops PROPERTIES TIMEOUT 300)
+ # Release notes from note fragments (tools/release/assemble_notes.py, changes/README.md): the assembler, and
+ # every fragment on this branch parses.
+ add_test(NAME release_notes COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/assemble_notes.py --self-test)
+ add_test(NAME release_notes_fragments COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/release/assemble_notes.py --check)
+ # The Actions cache pruner keeps the newest cache of each kind (tools/ci/prune_caches.py).
+ add_test(NAME ci_prune_caches COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/ci/prune_caches.py --self-test)
+ add_test(NAME ci_slowest_tests COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tools/ci/slowest_tests.py --self-test)
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)
diff --git a/changes/README.md b/changes/README.md
new file mode 100644
index 00000000..e111efcb
--- /dev/null
+++ b/changes/README.md
@@ -0,0 +1,31 @@
+# Note fragments
+
+Every branch that changes something users notice adds **one file here**, `changes/<branch>.md` (e.g.
+`changes/fix-wacom-hotplug.md`), instead of editing `CHANGELOG.md` and `docs/guide/whats-new.md`. Two branches
+never touch the same file, so release notes never conflict. `scripts/release.sh X.Y.Z` (step bump) runs
+`tools/release/assemble_notes.py X.Y.Z --apply`: the entries go into CHANGELOG `[Unreleased]` and What's New
+`Version X.Y.Z`, and the fragments are deleted in the release commit.
+
+```markdown
+---
+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 at 150% scaling: Draw > Camera > Gizmo size > Large; click each axis end, the view snaps to that side.
+ - Any OS: restart; the size is kept.
+---
+Anything after the front matter is for reviewers and is not copied anywhere.
+```
+
+| key | goes to | |
+|---|---|---|
+| `whats_new` | a bullet in the guide's What's New (the app shows it) | what users get, plain words, menu paths in bold |
+| `highlight` | the version's feature block and the update feed | optional; 3-5 per release in all, one short line |
+| `added` `changed` `fixed` `removed` `security` (`deprecated`) | `CHANGELOG.md` `[Unreleased]`, that section | the full entry, issue numbers and credits |
+| `testers` | the #testers checklist (`assemble_notes.py X.Y.Z --testers`) | what to try, where, what "good" looks like |
+
+Every key may repeat. A value continues on the next lines indented by two spaces; each `testers` item starts with
+` - `. Feature cards (title, line, image, Try it) stay hand-written in `docs/guide/whats-new.md`.
+`ctest -R release_notes` checks that every fragment parses.
diff --git a/changes/feat-release-train.md b/changes/feat-release-train.md
new file mode 100644
index 00000000..c0eec1ba
--- /dev/null
+++ b/changes/feat-release-train.md
@@ -0,0 +1,9 @@
+---
+changed: Faster CI for branches and pull requests: the VFX Reference Platform and Blender add-on checks run on main,
+ in the merge queue and on request (label `full-ci`, or a dispatch with full=true); Windows tests run on 4 runners;
+ CMake's configure checks are cached; old compiler caches are pruned so main's stay warm (prune-caches.yml); docs-only
+ changes skip the build; every test job lists its slowest tests in the job summary.
+changed: Release notes come from one note fragment per branch, `changes/<branch>.md` (changes/README.md);
+ `scripts/release.sh` step bump assembles them into CHANGELOG.md and What's New, and the update feed's highlights
+ default to the version's highlight lines.
+---
diff --git a/scripts/release.sh b/scripts/release.sh
index 89471c0b..57e6674e 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -152,7 +152,8 @@ highlights_ok() {
highlights_fix="write 3-5 one-line highlights (what users get) to a file and run again with HIGHLIGHTS=that-file"
# The words people write for What's New: the guide section and the UI test that expects it.
words_ok() {
- grep -q "^## Version ${V//./\\.}\$" docs/guide/whats-new.md ||
+ python3 tools/release/assemble_notes.py --check >/dev/null || die "a note fragment in changes/ doesn't parse: $(python3 tools/release/assemble_notes.py --check 2>&1)" "fix it (changes/README.md has the format), commit, push main"
+ grep -q "^## Version ${V//./\\.}\$" docs/guide/whats-new.md || grep -qs '^whats_new:' changes/*.md ||
die "docs/guide/whats-new.md has no '## Version $V'" "write that section at the top (Help > What's New shows it), commit, push main"
grep -qF "expect_text \"Version $V\"" tests/ui/whats_new.sfui ||
die "tests/ui/whats_new.sfui doesn't check Version $V" "update its first expect_text lines to the new section (the version and one line from it), commit, push main"
@@ -184,6 +185,11 @@ preflight() {
# site (bump writes the home page's card from the features block)
card_ok || features_ok || die "docs/guide/whats-new.md: Version $V has no \`\`\`features block with a tagline" "$card_fix"
if ! feed_done; then
+ if [ -z "${HIGHLIGHTS:-}" ]; then # the version's highlight lines (What's New features block + note fragments)
+ HIGHLIGHTS=$(mktemp)
+ python3 tools/release/assemble_notes.py "$V" --highlights >"$HIGHLIGHTS"
+ highlights_ok || HIGHLIGHTS=
+ fi
highlights_ok || die "HIGHLIGHTS must name a file with 3-5 highlight lines for the update feed (now: '${HIGHLIGHTS:-unset}')" "$highlights_fix"
fi
python3 -c 'import json, sys; json.load(open(sys.argv[1]))' website/latest.json 2>/dev/null || die "website/latest.json is not valid JSON" "fix it, commit"
@@ -214,6 +220,9 @@ step_bump() {
on_main
preflight bump
local out
+ # Note fragments (changes/<branch>.md) into CHANGELOG [Unreleased] and What's New X.Y.Z; the fragments go.
+ out=$(python3 tools/release/assemble_notes.py "$V" --apply 2>&1) || die "$out" "fix that fragment in changes/, commit, push main"
+ grep -q 'written' <<<"$out" && echo "$out" | sed 's/^/ notes: /'
out=$(python3 - "$V" "$TODAY" <<'PY'
import re, sys
v, today = sys.argv[1:]
@@ -281,7 +290,8 @@ PY
[ -n "$out" ] && echo "$out" | sed 's/^/ set: /'
python3 tools/guide/build_site.py >/dev/null # the guide, and the home page's What's New area for $V
card_ok || die "website/index.html has no 'new in $V' card after build_site.py" "$card_fix"
- git add CMakeLists.txt CITATION.cff packaging/rez/package.py packaging/linux/org.sculptforge.SculptForge.metainfo.xml CHANGELOG.md website/index.html
+ git add CMakeLists.txt CITATION.cff packaging/rez/package.py packaging/linux/org.sculptforge.SculptForge.metainfo.xml CHANGELOG.md website/index.html docs/guide/whats-new.md
+ git add -A changes
git add -A website/guide
if git diff --cached --quiet; then
ok "every version file already says $V and the guide is built"
diff --git a/tools/ci/prune_caches.py b/tools/ci/prune_caches.py
new file mode 100755
index 00000000..87aee363
--- /dev/null
+++ b/tools/ci/prune_caches.py
@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+# SculptForge - open source digital sculpting
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Keeps the newest GitHub Actions cache of each kind per branch and deletes the older ones.
+
+The repository gets 10 GB of cache. Every push to main saves a compiler cache per job (ccache-ci-<job>.<commit>,
+ccache-pkg-<job>.<commit>) and a configure cache per job (cmake-ci-<job>~<image, Python, CMake files>), about 5 GB in
+all, so without pruning each push evicts the previous one's and branch runs start cold (8-13 min builds instead of
+about 1). Only the newest entry of a kind can be restored by a later run anyway (restore-keys pick the newest).
+
+ tools/ci/prune_caches.py [--dry-run] PREFIX... e.g. ccache-ci- cmake-ci-
+
+Needs GH_TOKEN with actions: write and GITHUB_REPOSITORY (both set in a workflow job).
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+
+
+def kind(key):
+ """ccache-ci-blender-4.2.0.<40 hex> -> ccache-ci-blender-4.2.0; cmake-ci-windows~win22-... -> cmake-ci-windows."""
+ return re.sub(r"(\.[0-9a-f]{40}|~.*)$", "", key)
+
+
+def stale(caches, prefixes):
+ """The caches to delete: all but the newest of each (branch, kind) whose key starts with one of the prefixes."""
+ newest = {}
+ for c in caches:
+ if not c["key"].startswith(tuple(prefixes)):
+ continue
+ group = (c["ref"], kind(c["key"]))
+ if group not in newest or c["created_at"] > newest[group]["created_at"]:
+ newest[group] = c
+ keep = {c["id"] for c in newest.values()}
+ return [c for c in caches if c["key"].startswith(tuple(prefixes)) and c["id"] not in keep]
+
+
+def main(argv):
+ dry = "--dry-run" in argv
+ prefixes = [a for a in argv if a != "--dry-run"]
+ if not prefixes:
+ print(__doc__)
+ return 2
+ if prefixes == ["--self-test"]:
+ return self_test()
+ repo = os.environ["GITHUB_REPOSITORY"]
+ out = subprocess.run(["gh", "api", "--paginate", f"repos/{repo}/actions/caches?per_page=100",
+ "--jq", ".actions_caches[]"], check=True, capture_output=True, text=True).stdout
+ caches = [json.loads(line) for line in out.splitlines() if line.strip()]
+ for c in stale(caches, prefixes):
+ print(f"delete {c['key']} ({c['ref']}, {c['size_in_bytes'] >> 20} MB, {c['created_at']})")
+ if not dry:
+ subprocess.run(["gh", "api", "-X", "DELETE", f"repos/{repo}/actions/caches/{c['id']}"], check=False)
+ return 0
+
+
+def self_test():
+ sha1, sha2 = "a" * 40, "b" * 40
+ caches = [
+ {"id": 1, "key": f"ccache-ci-windows.{sha1}", "ref": "refs/heads/main", "created_at": "2026-11-02T15:00:00Z"},
+ {"id": 2, "key": f"ccache-ci-windows.{sha2}", "ref": "refs/heads/main", "created_at": "2026-11-02T16:00:00Z"},
+ {"id": 3, "key": f"ccache-ci-blender-4.2.0.{sha1}", "ref": "refs/heads/main", "created_at": "2026-11-02T15:00:00Z"},
+ {"id": 4, "key": f"ccache-ci-windows.{sha1}", "ref": "refs/heads/feat/x", "created_at": "2026-11-02T15:30:00Z"},
+ {"id": 5, "key": "cmake-ci-windows~win22-20261026.1-py3.13.17-abc", "ref": "refs/heads/main", "created_at": "2026-11-01T10:00:00Z"},
+ {"id": 6, "key": "cmake-ci-windows~win22-20261026.1-py3.13.17-def", "ref": "refs/heads/main", "created_at": "2026-11-02T10:00:00Z"},
+ {"id": 7, "key": f"ccache-pkg-windows.{sha1}", "ref": "refs/heads/main", "created_at": "2026-11-01T10:00:00Z"},
+ ]
+ got = sorted(c["id"] for c in stale(caches, ["ccache-ci-", "cmake-ci-"]))
+ assert got == [1, 5], got # newest per (branch, kind) kept; other prefixes untouched
+ assert kind(f"ccache-ci-blender-4.2.0.{sha1}") == "ccache-ci-blender-4.2.0"
+ print("prune_caches self-test ok")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/tools/ci/slowest_tests.py b/tools/ci/slowest_tests.py
new file mode 100755
index 00000000..eae961ea
--- /dev/null
+++ b/tools/ci/slowest_tests.py
@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+# SculptForge - open source digital sculpting
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The slowest tests of a ctest run, for the CI job summary: whole ctest entries, and the single tests inside the
+sculptforge_tests shards (their "[ OK ] name (N ms)" lines). Tells which test to split or move when a CI shard
+becomes the long pole.
+
+ tools/ci/slowest_tests.py build/ctest.xml [N] (ctest --output-junit ctest.xml writes it)
+"""
+import re
+import sys
+import xml.etree.ElementTree as ET
+
+
+def main(argv):
+ if not argv or argv[0] == "--self-test":
+ return self_test()
+ try:
+ root = ET.parse(argv[0]).getroot()
+ except (OSError, ET.ParseError) as e:
+ print(f"no ctest results: {e}")
+ return 0
+ n = int(argv[1]) if len(argv) > 1 else 12
+ entries, inner = report(root)
+ print(f"| slowest ctest entries | s |\n|---|---|")
+ for t, name in entries[:n]:
+ print(f"| {name} | {t:.1f} |")
+ print(f"\n| slowest tests inside sculptforge_tests | s |\n|---|---|")
+ for t, name in inner[:n]:
+ print(f"| {name} | {t:.1f} |")
+ return 0
+
+
+def report(root):
+ entries, inner = [], []
+ for case in root.iter("testcase"):
+ entries.append((float(case.get("time") or 0), case.get("name")))
+ out = "".join(e.text or "" for e in case.iter("system-out"))
+ for name, ms in re.findall(r"^\[ OK \] (\S+) \((\d+) ms\)", out, re.M):
+ inner.append((int(ms) / 1000, name))
+ return sorted(entries, reverse=True), sorted(inner, reverse=True)
+
+
+def self_test():
+ xml = ('<testsuite><testcase name="sculptforge_tests_3of8" time="282.1"><system-out>[ RUN] a\n[ OK ] a (120500 ms)\n'
+ '[ OK ] b (12 ms)\n</system-out></testcase><testcase name="ui_bake" time="51"/></testsuite>')
+ entries, inner = report(ET.fromstring(xml))
+ assert entries == [(282.1, "sculptforge_tests_3of8"), (51.0, "ui_bake")], entries
+ assert inner == [(120.5, "a"), (0.012, "b")], inner
+ print("slowest_tests self-test ok")
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main(sys.argv[1:]))
diff --git a/tools/release/assemble_notes.py b/tools/release/assemble_notes.py
new file mode 100755
index 00000000..0c0d7e79
--- /dev/null
+++ b/tools/release/assemble_notes.py
@@ -0,0 +1,277 @@
+#!/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)
+ lines[last + 1:last + 1] = [f"highlight: {h}" for h in highlights]
+ 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":
+ print(f"{len(frags)} note fragment(s) parse")
+ return 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", [])]
+ 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
+ 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:]))