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.