From 81e46382545f7b9a39e417c54b4be471463d0b43 Mon Sep 17 00:00:00 2001 From: AlxcBTW <187763517+AlxcBTW@users.noreply.github.com> Date: Mon, 12 Oct 2026 18:23:52 +0200 Subject: [PATCH] docs: add a performance report issue form and ask for summary lines .github/ISSUE_TEMPLATE/performance.yml asks for the title and scene, what is slow or what changed, the summary lines and traces of APS5_TRACE_FRAMES captures, the trace digest and optionally the worker's collapsed stacks, and states the capture protocol: warm caches, the same scene and settings, no other profiling switch, the same machine and session. The pull request template and CONTRIBUTING ask a pull request that claims a change in speed for the summary lines of main and of the change, captured the same way. Co-Authored-By: Claude Opus 5.5 --- .github/ISSUE_TEMPLATE/performance.yml | 65 ++++++++++++++++++++++++++ .github/pull_request_template.md | 2 +- CONTRIBUTING.md | 1 + 3 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 .github/ISSUE_TEMPLATE/performance.yml diff --git a/.github/ISSUE_TEMPLATE/performance.yml b/.github/ISSUE_TEMPLATE/performance.yml new file mode 100644 index 000000000..417fc4be2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/performance.yml @@ -0,0 +1,65 @@ +name: Performance report +description: A slow scene or a change in speed, measured with a performance trace so that reports can be compared. +title: "perf: " +body: + - type: markdown + attributes: + value: | + Capture the scene with `APS5_TRACE_FRAMES=:` (presents; `APS5_TRACE_SECONDS=:` also works), as described under [Performance trace](https://github.com/boykopovar/AnyPS5/blob/main/docs/dev/BUILD.md#performance-trace). It writes `aps5-trace--.json.gz` and appends one line to `aps5-summary.jsonl`. + + - Run the scene once and restart the title, so the shader and pipeline caches are warm. + - Use the same scene, window, resolution and settings for every capture you compare. + - Set no other `APS5_TRACE_*` or `APS5_PROFILE_*` switch and do not redirect the log; they cost time. + - Capture the base and the change on the same machine in the same session. + + A trace holds timings, scope and thread names and counts, no game data. The summary line names the GPU, driver and OS. + - type: input + id: scene + attributes: + label: Title and scene + description: Title ID and what the window covers (menu, level, position, cutscene). + placeholder: PPSA01325, main menu after the intro + validations: + required: true + - type: textarea + id: observed + attributes: + label: What is slow or what changed + description: What you see (frame time, stutter, a phase that grew) and, for a comparison, the two commits. + validations: + required: true + - type: textarea + id: summary + attributes: + label: Summary lines + description: The line of aps5-summary.jsonl for each capture. It holds the commit, the APS5_* switches, GPU, driver, OS, resolution and frame times. + render: json + validations: + required: true + - type: textarea + id: trace + attributes: + label: Traces + description: Attach each aps5-trace--.json.gz (drag it into this field). They open in ui.perfetto.dev. + validations: + required: true + - type: textarea + id: digest + attributes: + label: Digest + description: The output of `python3 tools/trace_digest.py ` (with `--stacks .collapsed.txt` if you sampled the worker). + - type: textarea + id: stacks + attributes: + label: Worker stacks + description: Optional. The collapsed-stack file of APS5_SAMPLE_WORKER (.collapsed.txt), attached. It opens in speedscope.app. + - type: checkboxes + id: protocol + attributes: + label: Capture + options: + - label: The caches were warm (the scene ran once and the title was restarted) + required: true + - label: No other APS5_TRACE_* or APS5_PROFILE_* switch was set and the log was not redirected + required: true + - label: Captures compared here come from the same machine, scene and settings diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 94ee308e6..d281079fb 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,7 +1,7 @@ ### What ### Tested - + ### Checklist diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 85fc90d0e..bbaa0faec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,6 +58,7 @@ The [pull request template](.github/pull_request_template.md) is the checklist f - Fixes a title needs go to `main` as pull requests. A Game bring-up discussion lists the open pull requests and local changes the title still needs; update the list when one is merged, closed or replaced. - The PR overlap comment lists open pull requests that change the same lines or exports; agree with their authors which one goes first and declare it with `Depends on`. - Run the tests before opening the pull request and describe what was tested (OS, title or homebrew). +- A pull request that claims a change in speed shows the summary lines of `main` and of the change, from the same machine and scene, and attaches the traces, captured as the [Performance report](.github/ISSUE_TEMPLATE/performance.yml) issue form describes. A slow scene is reported with the same form. - Investigation notes, reports, screenshots and logs go in the pull request, not in the repository. Images for documentation go in the [gist](https://gist.github.com/boykopovar/0e53f2e1426f29ecd41e3b51540b8a90) comments. - Say whether the change was written with AI assistance. The author of the pull request is responsible for every line of it.