From 410f9db6a2ca1b75f7d0131b14ddd01e3712a608 Mon Sep 17 00:00:00 2001 From: Mistium <92952823+Mistium@users.noreply.github.com> Date: Sat, 21 Nov 2026 01:18:44 +0000 Subject: [PATCH 1/4] Document commit summaries --- docs/backend/storage.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 8abba4fe..7522791b 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -21,6 +21,7 @@ The read-only commit endpoints inspect the stored `.mwp` on the server. Clients - `state`: what running the project changes rather than edits. That is variable and list values, sprite position, size, direction, layer and visibility, stage settings, the current costume, monitors and where scripts sit on the canvas. Reordering scripts or moving them on the canvas, a newer Fractch spelling of the same block (also inside `${...}` in template strings), a value hidden under a reporter, and rotation centres that differ by less than 0.005 are not reported as edits. Other files are listed in `files` like the plain endpoint with inline text. `totals` counts everything, and `totals.stateOnly` is true when saved state is all that changed. A sprite with a region file over 1 MiB, or whose region files together pass what is left of the 8 MiB response budget, is listed with `tooLarge: true` and no breakdown. Renaming a sprite renames its folder, so it shows as one target removed and another added. `GET /v1/projects/:id/pulls/:index/diff?view=changes` returns the same shape for a pull request in `inspection`. +- `GET /v1/projects/:id/commit-summaries?shas=,` returns a short summary for each listed commit, for commit lists. It takes up to 50 SHAs that the project records and skips any others. Each entry in `summaries` (keyed by SHA) has `totals` (the same counts as the changes view), `sprites` (the names of up to five sprites with script, item or asset changes), `spriteCount`, `legacy`, and `initial` (true for a commit with no parent). Summaries are computed when first asked for and cached like the changes view. - `GET /v1/projects/:id/commits/:sha/tree` returns `commit` and a flat `files` array. Each file has `path`, `oid`, `mode`, `size`, and `binary`. - `GET /v1/projects/:id/commits/:sha/file?path=` returns one file record and `content`, encoded as base64 by JSON. - `GET /v1/projects/:id/commits/:sha/co-authors` returns the Rotur users credited on that commit. The older `/collaborators` path remains an alias. From d29d71cb98dd2eba6399bf1a77f1fca6fec3b3ca Mon Sep 17 00:00:00 2001 From: Mistium <92952823+Mistium@users.noreply.github.com> Date: Sat, 21 Nov 2026 01:36:58 +0000 Subject: [PATCH 2/4] Document authored file counts and the summary cache --- docs/backend/storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 7522791b..26b2b6c3 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -21,7 +21,7 @@ The read-only commit endpoints inspect the stored `.mwp` on the server. Clients - `state`: what running the project changes rather than edits. That is variable and list values, sprite position, size, direction, layer and visibility, stage settings, the current costume, monitors and where scripts sit on the canvas. Reordering scripts or moving them on the canvas, a newer Fractch spelling of the same block (also inside `${...}` in template strings), a value hidden under a reporter, and rotation centres that differ by less than 0.005 are not reported as edits. Other files are listed in `files` like the plain endpoint with inline text. `totals` counts everything, and `totals.stateOnly` is true when saved state is all that changed. A sprite with a region file over 1 MiB, or whose region files together pass what is left of the 8 MiB response budget, is listed with `tooLarge: true` and no breakdown. Renaming a sprite renames its folder, so it shows as one target removed and another added. `GET /v1/projects/:id/pulls/:index/diff?view=changes` returns the same shape for a pull request in `inspection`. -- `GET /v1/projects/:id/commit-summaries?shas=,` returns a short summary for each listed commit, for commit lists. It takes up to 50 SHAs that the project records and skips any others. Each entry in `summaries` (keyed by SHA) has `totals` (the same counts as the changes view), `sprites` (the names of up to five sprites with script, item or asset changes), `spriteCount`, `legacy`, and `initial` (true for a commit with no parent). Summaries are computed when first asked for and cached like the changes view. +- `GET /v1/projects/:id/commit-summaries?shas=,` returns a short summary for each listed commit, for commit lists. It takes up to 50 SHAs that the project records and skips any others. Each entry in `summaries` (keyed by SHA) has `totals` (the same counts as the changes view), `sprites` (the names of up to five sprites with script, item or asset changes), `spriteCount`, `authoredFiles` (changed files that are not sprite code, assets or `fractch.json`), `tooLarge` (true when a sprite was too large to compare), `legacy`, and `initial` (true for a commit with no parent). A commit's summary never changes, so each one is computed the first time it is asked for and kept in one cache file per project under `git-summaries/` in the temp directory. Saving the project does not clear that file. - `GET /v1/projects/:id/commits/:sha/tree` returns `commit` and a flat `files` array. Each file has `path`, `oid`, `mode`, `size`, and `binary`. - `GET /v1/projects/:id/commits/:sha/file?path=` returns one file record and `content`, encoded as base64 by JSON. - `GET /v1/projects/:id/commits/:sha/co-authors` returns the Rotur users credited on that commit. The older `/collaborators` path remains an alias. From 4517f07da16310b1f41be75e66b1ba00b3d2f6a7 Mon Sep 17 00:00:00 2001 From: Mistium <92952823+Mistium@users.noreply.github.com> Date: Sat, 21 Nov 2026 01:48:36 +0000 Subject: [PATCH 3/4] Correct the commit summaries reference --- docs/backend/storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 26b2b6c3..7dd78857 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -21,7 +21,7 @@ The read-only commit endpoints inspect the stored `.mwp` on the server. Clients - `state`: what running the project changes rather than edits. That is variable and list values, sprite position, size, direction, layer and visibility, stage settings, the current costume, monitors and where scripts sit on the canvas. Reordering scripts or moving them on the canvas, a newer Fractch spelling of the same block (also inside `${...}` in template strings), a value hidden under a reporter, and rotation centres that differ by less than 0.005 are not reported as edits. Other files are listed in `files` like the plain endpoint with inline text. `totals` counts everything, and `totals.stateOnly` is true when saved state is all that changed. A sprite with a region file over 1 MiB, or whose region files together pass what is left of the 8 MiB response budget, is listed with `tooLarge: true` and no breakdown. Renaming a sprite renames its folder, so it shows as one target removed and another added. `GET /v1/projects/:id/pulls/:index/diff?view=changes` returns the same shape for a pull request in `inspection`. -- `GET /v1/projects/:id/commit-summaries?shas=,` returns a short summary for each listed commit, for commit lists. It takes up to 50 SHAs that the project records and skips any others. Each entry in `summaries` (keyed by SHA) has `totals` (the same counts as the changes view), `sprites` (the names of up to five sprites with script, item or asset changes), `spriteCount`, `authoredFiles` (changed files that are not sprite code, assets or `fractch.json`), `tooLarge` (true when a sprite was too large to compare), `legacy`, and `initial` (true for a commit with no parent). A commit's summary never changes, so each one is computed the first time it is asked for and kept in one cache file per project under `git-summaries/` in the temp directory. Saving the project does not clear that file. +- `GET /v1/projects/:id/commit-summaries?shas=,` returns a short summary for each listed commit, for commit lists. It uses the same access rule as `/commits/:sha/changes`, without the pull request exception. It takes up to 50 lowercase hex SHAs and ignores any that are malformed, repeated, or not recorded by the project. Commits that cannot be summarised (for example when the parent commit is missing) are left out of `summaries`. Each entry in `summaries` (keyed by SHA) has `totals` (the same counts as the changes view, comparing a merge commit with its first parent), `sprites` (the names of up to five sprite folders with script, item or asset changes; saved state alone does not name a sprite, and `fonts/` or root `assets/` files are counted in `totals` but name no sprite), `spriteCount`, `authoredFiles` (changed files that are not sprite code, assets or `fractch.json`), `tooLarge` (true when a sprite was too large to compare), `legacy`, and `initial` (true for a commit with no parent). Summaries are computed the first time they are asked for and kept in one cache file per project under `git-summaries/` in the temp directory, so saving the project does not recompute them. Failures are cached for an hour. The file holds up to 2,000 entries and starts again from the current request when it would grow past that. The cache name carries its own version, which changes whenever the summary format does. - `GET /v1/projects/:id/commits/:sha/tree` returns `commit` and a flat `files` array. Each file has `path`, `oid`, `mode`, `size`, and `binary`. - `GET /v1/projects/:id/commits/:sha/file?path=` returns one file record and `content`, encoded as base64 by JSON. - `GET /v1/projects/:id/commits/:sha/co-authors` returns the Rotur users credited on that commit. The older `/collaborators` path remains an alias. From d56b91eb8a11c92b22cecd3afc19a4a74f7a39d1 Mon Sep 17 00:00:00 2001 From: Mistium <92952823+Mistium@users.noreply.github.com> Date: Sat, 21 Nov 2026 01:51:32 +0000 Subject: [PATCH 4/4] Note the summary retry window and empty histories --- docs/backend/storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/backend/storage.md b/docs/backend/storage.md index 7dd78857..f2de77a0 100644 --- a/docs/backend/storage.md +++ b/docs/backend/storage.md @@ -21,7 +21,7 @@ The read-only commit endpoints inspect the stored `.mwp` on the server. Clients - `state`: what running the project changes rather than edits. That is variable and list values, sprite position, size, direction, layer and visibility, stage settings, the current costume, monitors and where scripts sit on the canvas. Reordering scripts or moving them on the canvas, a newer Fractch spelling of the same block (also inside `${...}` in template strings), a value hidden under a reporter, and rotation centres that differ by less than 0.005 are not reported as edits. Other files are listed in `files` like the plain endpoint with inline text. `totals` counts everything, and `totals.stateOnly` is true when saved state is all that changed. A sprite with a region file over 1 MiB, or whose region files together pass what is left of the 8 MiB response budget, is listed with `tooLarge: true` and no breakdown. Renaming a sprite renames its folder, so it shows as one target removed and another added. `GET /v1/projects/:id/pulls/:index/diff?view=changes` returns the same shape for a pull request in `inspection`. -- `GET /v1/projects/:id/commit-summaries?shas=,` returns a short summary for each listed commit, for commit lists. It uses the same access rule as `/commits/:sha/changes`, without the pull request exception. It takes up to 50 lowercase hex SHAs and ignores any that are malformed, repeated, or not recorded by the project. Commits that cannot be summarised (for example when the parent commit is missing) are left out of `summaries`. Each entry in `summaries` (keyed by SHA) has `totals` (the same counts as the changes view, comparing a merge commit with its first parent), `sprites` (the names of up to five sprite folders with script, item or asset changes; saved state alone does not name a sprite, and `fonts/` or root `assets/` files are counted in `totals` but name no sprite), `spriteCount`, `authoredFiles` (changed files that are not sprite code, assets or `fractch.json`), `tooLarge` (true when a sprite was too large to compare), `legacy`, and `initial` (true for a commit with no parent). Summaries are computed the first time they are asked for and kept in one cache file per project under `git-summaries/` in the temp directory, so saving the project does not recompute them. Failures are cached for an hour. The file holds up to 2,000 entries and starts again from the current request when it would grow past that. The cache name carries its own version, which changes whenever the summary format does. +- `GET /v1/projects/:id/commit-summaries?shas=,` returns a short summary for each listed commit, for commit lists. It uses the same access rule as `/commits/:sha/changes`, without the pull request exception. It takes up to 50 lowercase hex SHAs and ignores any that are malformed, repeated, or not recorded by the project. Commits that cannot be summarised (for example when the parent commit is missing) are left out of `summaries`. Each entry in `summaries` (keyed by SHA) has `totals` (the same counts as the changes view, comparing a merge commit with its first parent), `sprites` (the names of up to five sprite folders with script, item or asset changes; saved state alone does not name a sprite, and `fonts/` or root `assets/` files are counted in `totals` but name no sprite), `spriteCount`, `authoredFiles` (changed files that are not sprite code, assets or `fractch.json`), `tooLarge` (true when a sprite was too large to compare), `legacy`, and `initial` (true for a commit with no parent). Summaries are computed the first time they are asked for and kept in one cache file per project under `git-summaries/` in the temp directory, so saving the project does not recompute them. A project with no recorded branch heads returns an empty `summaries` object. Failures are cached for ten minutes. The file holds up to 2,000 entries and starts again from the current request when new entries would push it past that. The cache name carries its own version, which changes whenever the summary format does. - `GET /v1/projects/:id/commits/:sha/tree` returns `commit` and a flat `files` array. Each file has `path`, `oid`, `mode`, `size`, and `binary`. - `GET /v1/projects/:id/commits/:sha/file?path=` returns one file record and `content`, encoded as base64 by JSON. - `GET /v1/projects/:id/commits/:sha/co-authors` returns the Rotur users credited on that commit. The older `/collaborators` path remains an alias.