docs(forge): every pull request description starts with a plain TL;DR and a Breakdown; the check suggests them where they are missing #1470
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1470
Loading…
Reference in a new issue
No description provided.
Delete branch "mooki/Longshot:docs/pr-template-tldr"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Type: docs · Risk: low · Tested on: Linux (Arch), no GPU: it changes no game file · Needs: the forge's new pull request page, after merge
TL;DR
A pull request's description is long, and someone who is not reading the code has to dig through it to learn what a change is for. The template now opens with a TL;DR, a few plain sentences, and a Breakdown, short bullets, and the description check asks for them to be filled in when they are there. When they are missing it only suggests them, so the open pull requests keep passing: read over all of them, the new check adds no error. The check's new tests failed before the change and pass after it, and the whole suite gives main's result.
Breakdown
forge.pyneeds no change.Why
A description opens, after the status line, with Why, and under it come the reproduction steps, the measurements, the testing and the checklist. A reader who only wants to know what a pull request does, who it helps and whether it was checked has to read it all and sum it up in their head. I want every pull request to start with a human-readable TL;DR and a breakdown, and the template to carry them; #1462's description shows the form.
This builds on #1454 (merged today), which made "ready for review" one list and put a complete description in it (CONTRIBUTING.md, "Ready for review: out of WIP", item 5): this adds the part of that description a reader reaches first. I searched the tracker for "TL;DR", "TLDR", "pull request template", "PR description" and "breakdown": no issue asks for it, so there is nothing to link; the pull requests that touch the same files are under Overlaps.
What changed
The template gets a TL;DR and a Breakdown right after the status line, and the description check reads them. Kept, they must be filled in; left out, they only draw a warning, so no open pull request starts to fail for lacking them.
.forgejo/pull_request_template.mdhas## TL;DR(two to four plain sentences, at most 120 words: what was wrong or missing, what this changes, the headline result and how it was checked) and## Breakdown(seven bullets: who it helps, what was wrong, what changes, what does not change, how it was checked, what is still open, the risk), each with an HTML comment that explains it and a short example, in the template's existing style. Why's comment no longer says "first".scripts/check_pr_description.pyhasSUMMARY,TLDR_WORDS = 120,summary()(finds the section by its heading without case or punctuation, soTLDRcounts),tldr_problems()andbreakdown_problems();review()runs them after the status line's checks and before Why. Placeholders are the template's own<...>stand-ins, found the way every other section's are. A missing section adds one warning to the returned warnings; the returned(problems, warnings)shape,problems(),TEMPLATE,keep_applicable()andwithout_reproduce()(what Tooling'sforge.pycalls) are as they were.status()is untouched, so a TL;DR above the status line is "no status line".docs/workflow.mdanddocs/agent-pull-requests.mdonly link the template and CONTRIBUTING.md (they list no sections), so they are unchanged.tests/test_check_pr_description.pyhas a newSummaryclass (10 tests) and updated samples;tests/pr_description/good.md, the sample of a good description, has both sections. The "older description" sample is good.md less the two sections, taken in the test, so it follows the template when that changes.Unchanged: every other section's rules, the checklist, the WIP notice, the workflow (
.forgejo/workflows/pr-description.ymlruns main's copy of the script on every pull request, so once this merges the new rules apply to every open description at its next edit).Measurements
Verdict: the new tests fail on main's check and template (15 of 51) and pass here (51 of 51); the whole suite is main's (674 passed, 38 failed, 17 skipped, the same 38 failing names); read over all 334 open descriptions the new check adds no error and drops none, and its warnings reach every description that has neither section; its time over all those descriptions is the same within the spread.
Hardware: Linux (Arch), kernel 7.2.15, i9-13900K (32 threads), 93 GB; no GPU, no game
Scene: none: a Python check on text; the open pull requests' real descriptions read from the forge
Method:
tests/test_check_pr_description.pyat the tests-only commit and at the head;tests/run_all.py --jobs 6 --stricton this head and on main; a scan script runs main's check with main's template and this branch's check with its template over every open description (the call--prmakes, without the diff, which the new rules do not read); the check's cost is five interleaved timed passes of each check over those descriptionsHow to reproduce:
python -I -B tests/test_check_pr_description.py;python -I -B tests/run_all.py --jobs 6 --strict(RX_CPMset to the dependency cache that holds the Vulkan and SPIR-V headers);python -I scan_open_prs.py --old <main checkout> --new <this checkout>257c54911a51766cb9cf3590fa9): 36 of 51 pass, 15 fail (9 failures, 6 errors)Flags and settings
None.
How it was tested
Everything here was run by an AI agent (Claude Sonnet 5.5) working for me; the commands are given so anyone can rerun them. No game was run: nothing here is read by the game (
.forgejo/, a script underscripts/, tests, a doc).1. What was looked for
.forgejo/workflows/pr-description.ymlruns main'sscripts/check_pr_description.py --pr Non every pull request event, with main's template, so after a merge the new rules apply to every open description at its next edit.forge.py(Tooling) loads the same file and callsreview,problems,keep_applicableandwithout_reproduceand readsTEMPLATE: all four and the(problems, warnings)shape are unchanged. A rule that errors on a missing section would turn every open description red, so a missing section is a warning.GET /api/v1/repos/MagicBeanDev/Longshot/pulls?state=open&limit=50&page=Nuntil an empty page), gave 337 open pull requests at the first read, 338 at the second, 335 at the next two and 334 at the last, at 21:02 UTC (they merge and close while this is written). At the first read one description had aTL;DRorBreakdownheading (#1462); by the last, three (#1462, #68, #1466), as TL;DRs began to be added to open pull requests today. The earlier reads (the last at 20:41 UTC) found #1466 at 191 words and #68 at 155: the only two errors the new rules added. Both were then cut to 115 words, and the read at 21:02 UTC adds none.2. Game-free checks (anyone can rerun them)
python -I -B), git 2.56.0, clang++ 23.1.3 and g++ 16.2.1 (the suite's compiled tests). Base: main257c54911(forge main, still current when fetched at 20:54 UTC on 17 November, after #1454); heada51766cb9, two commits:cf3590fa9(the tests alone) anda51766cb9(the template, the check, CONTRIBUTING.md). 17 November 2026, 19:40 to 21:05 UTC. Main moved three times while this was written (#718; #1459 with two others; none touches a file of the check, the template, CONTRIBUTING.md or the pull request tests): the two commits were rebased each time,git range-diffshows both unchanged, and the tests, the suite and the scan were rerun on the final base; the cost passes below were timed on the head before the last rebase (the same patch). The machine runs other builds and checks at the same time: the 1-minute load average was 11 to 23 when read during the runs (the 15-minute one up to 37); nothing here is a timing claim except the one table row that says so.git worktreeof each commit, never from the working tree being edited.cf3590fa9holds only the tests andgood.md.python -I -B tests/test_check_pr_description.pyin a clean checkout of it (main's check and template):Ran 51 tests ... FAILED (failures=9, errors=6). The 15 are: the sample and template tests that need a TL;DR section to exist (test_the_fix_sample_passes,test_a_docs_change_with_one_line_passes,test_contributings_example_passes,test_the_bare_template_fails_on_every_section,test_the_sections_follow_the_order,test_without_reproduce) and the newSummarytests (placeholders, length, bullets, empty bullets, the heading's spelling, warnings and the command's output, the template's order). Three of them error on a name that does not exist yet (check.SUMMARY,check.TLDR_WORDS), one onKeyError: 'Breakdown'and two on the template having no TL;DR section for the sample helpers to fill; nine fail on behaviour (a missing section gives no warning, an empty TL;DR is accepted, the template's sections are not in the new order). The tenthSummarytest,test_the_status_line_still_comes_first, passes on main on purpose: the status line rule is not changed. At the head:Ran 51 tests ... OK. Main's own copy of the file (41 tests) passes on main.scripts/check_pr_description.py, each followed by the same test file through the gate; each must fail: the limit raised to 121 (test_the_tldr_is_short,test_the_template_has_them_right_after_the_status_line); a missing section made an error (test_left_out_is_a_warning_never_an_error,test_the_command_passes_and_says_so); the placeholder check skipped for the two sections (three tests); the empty-bullet check off (test_a_bullet_is_not_left_empty); the no-bullets check off (test_the_breakdown_has_bullets); the heading read exactly, soTLDRis missed (test_the_heading_may_be_spelled_tldr). All six exit 1 on an assertion, none on a syntax error.python -I -B tests/run_all.py --jobs 6 --strictthrough the gate, withRX_CPMset to the dependency cache (a first run without it failed 94 tests on both trees:--strictfails a test whose Vulkan or SPIR-V headers it cannot find; with it, the 38 below), on this head and then on main257c54911, one after the other: 674 passed / 38 failed / 17 skipped (712 checks) on both, and the same 38 names.test_crash_record.pytimed out on a 10 s wait for a killed child in the first full run of the head, twice over the work (once on the previous base, once on this one), under heavy load (the 15-minute load average was 30 to 33); alone it passes on the head and on main each time it was tried, and the next full run of the head has it passing. The 38 are main's own on this machine, none in or near the description check (tests/test_check_pr_description.pypasses on both): test_bug_report_defaults.py, test_cpu_report.py, test_crt_options.py, test_damage_debug_menu.py, test_display_startup_failure.py, test_dlss_feature_size.py, test_failed_compile_keeps_objects.py, test_framegen_preset.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_hud_layout_row.py, test_import_reach.py, test_invalidate_vcore.py, test_linux_preflight.py, test_linux_pressure.py, test_linux_update.py, test_log_open_failure.py, test_mirror_budget.py, test_missing_nup.py, test_mods_size_table.py, test_nonuniform_image_arrays.py, test_parallel_init_order.py, test_pending_guest_import.py, test_pipeline_play_cache.py, test_present_thread.py, test_profiling_mode.py, test_readback_timeout_source.py, test_replay_write_order.py, test_rumble_menu.py, test_run_all_changed.py, test_slow_frames.py, test_staging_burst.py, test_target_image_pool.py, test_upscaler_round_trip.py, test_upscaler_rows.py, test_vcore_escape.py, test_vk_occlusion_queries.py, test_walk_key.py.scan_open_prs.py(attached to the first comment asscan_open_prs.py.txt, about 80 lines, standard library only, public reads only) loads two copies of the check (each with its template) from two checkouts, reads every open description with the forge's public API and runsreview(body, merge_base=..., title=...)of each on it: the call--prmakes, without the diff, which the new rules do not read. It prints how many fail with each, every error the new check adds or drops, and how many descriptions get each new warning (its output is the block above). The three descriptions that have the sections (#1462, #1466, #68) were also run through the new check one by one at 21:03 UTC: their TL;DRs are 93, 115 and 115 words and the TL;DR and Breakdown raise nothing; the one error #1462 and #68 still have is an unticked box of #1454's Everyone list, which main's check reports the same way.pulls/N/files(334 of 335 at that read:pulls/768/filesanswerednull, an incomplete answer, so its head was merged on its own), thengit merge-tree --write-tree --name-only <base> <head>of each head that changes one of this branch's files, against main and against this branch.3. In the game
Not run: no file the game runs changed, and
pr createasks for a game run only forgpu/,host/,nx2/,assets/andthird_party/.4. What was not tested
See "Not tested" under Testing.
Testing
Tested: on this PC (Linux, no GPU), the check and its 51 tests at the tests-only commit (15 fail on main's check and template) and at the head (all pass); six deliberate breakages of the new rules, each caught; the whole suite on the head and on main (the same 674 passed, 38 failed, 17 skipped, the same names); the new check against all 334 open descriptions (no error added; 331 of 334 get the two suggestions) and against the live descriptions of #1462, #1466 and #68, the three that have the sections (their TL;DRs of 93, 115 and 115 words raise nothing); a trial merge of this branch with each open pull request that changes the same files (no conflict added; with #1454, which merged first, the 51 tests passed on the merge of this branch with its head before the rebase).
Not tested: how the forge's new pull request page shows the template (the headings, the stand-ins, the comments hidden): the page cannot be opened for a branch that is not on main yet;
forge.py pr createagainst the new template (it opens a pull request: not run; its calls into the check were read, and their shapes did not change); the workflow itself on the forge (it runs main's copy, so it runs on the first pull request event after the merge); Windows (the check is plain Python text rules: not run); afeatorperfdescription made from the new template (the tests use a fix, a perf and a docs sample).Must be tested:
Risks
What could break: a description that keeps a TL;DR over 120 words, a Breakdown without bullets or with an empty bullet, or a placeholder in either, is refused when it is marked ready, and the workflow flags it on its next edit. No open description is in that case now: two were when the check first read them (#1466's TL;DR was 191 words and #68's 155, both added today) and both were cut to 115 words; a looser limit is one constant,
TLDR_WORDS. A## TL;DRor## Breakdownheading used for something else is read as these; none of the 337 descriptions read at the first look had one. Cost: the check reads two short sections more: 0.28 to 0.29 s against 0.27 to 0.29 s over 335 descriptions (about 0.8 ms each), on a loaded PC, so no measurable difference.Turning it off: revert the commit, or delete the two sections from a description (it then only warns).
Compatibility: nothing changes for a player; a contributor who starts a pull request from the new template sees two more sections to fill in, and a description from the old template passes with two warnings.
Overlaps
Read from
pulls/N/filesof the open pull requests and trial merges (git merge-tree --write-tree) of each head against main and against this branch, conflict hunks read where there were any (done on maindcb7b47c2; the commits added to main since touch none of this branch's files). #1454, which changed the same template, check, tests, good.md and CONTRIBUTING.md, merged while this was written: this branch was rebased onto it (the range-diff of the two commits shows only changed context lines) and the tests and the suite were rerun on the result. Fourteen open pull requests change CONTRIBUTING.md and nothing else of this branch's files (#29, #56, #67, #68, #144, #204, #235, #236, #284, #405, #685, #860, #893, #1145): eight merge cleanly with main and with this branch; six conflict with main already (#29 in CONTRIBUTING.md and tests/run_all.py, #204, #236, #284, #405, #685 in other files) and this branch adds no conflict to any of them. #768's file list was not readable (null); its head merges cleanly with both.Checklist
Everyone
type(scope): description) of the status line's type.can't be run by hand is in Testing's Not testable by hand, with why.
in Risks.
main.python -I -B tests/run_all.pypasses (any failure that also fails onmainis named): 38 tests fail on both main and this PR, the same names, none in the description check: test_bug_report_defaults.py, test_cpu_report.py, test_crt_options.py, test_damage_debug_menu.py, test_display_startup_failure.py, test_dlss_feature_size.py, test_failed_compile_keeps_objects.py, test_framegen_preset.py, test_fsr_uniform_ownership.py, test_guest_imported.py, test_hud_layout_row.py, test_import_reach.py, test_invalidate_vcore.py, test_linux_preflight.py, test_linux_pressure.py, test_linux_update.py, test_log_open_failure.py, test_mirror_budget.py, test_missing_nup.py, test_mods_size_table.py, test_nonuniform_image_arrays.py, test_parallel_init_order.py, test_pending_guest_import.py, test_pipeline_play_cache.py, test_present_thread.py, test_profiling_mode.py, test_readback_timeout_source.py, test_replay_write_order.py, test_rumble_menu.py, test_run_all_changed.py, test_slow_frames.py, test_staging_burst.py, test_target_image_pool.py, test_upscaler_round_trip.py, test_upscaler_rows.py, test_vcore_escape.py, test_vk_occlusion_queries.py, test_walk_key.py.third_party/untouched (a new folder with aPROVENANCE.mdinstead).When it applies
Assisted-by:/Co-Authored-By:trailers.tests/that reads changed source updated in this PR, not weakened (tests/test_check_pr_description.pyreads the template, the check and CONTRIBUTING.md; its samples andtest_the_sections_follow_the_order,test_without_reproduceandtest_refusalsfollow the new sections, and nothing was removed).New on this forge; not opened on GitHub.
WIP: docs(forge): every pull request description starts with a plain TL;DR and a Breakdown; the check suggests them where they are missingto docs(forge): every pull request description starts with a plain TL;DR and a Breakdown; the check suggests them where they are missingThe script behind the description's scan of the open pull requests is attached:
scan_open_prs.py(attached asscan_open_prs.py.txt; the forge does not take.pyfiles). It reads every open pull request's description through the forge's public API, page by page until an empty page, and runs main's description check and this branch's on each one, with the pull request's own diff and title; it prints the errors each check adds or drops and the warnings. It only reads: it posts nothing and changes nothing. To run it, put it in a checkout of this branch with main'sscripts/check_pr_description.pysaved beside it as the old check, and run it with Python 3.12 or newer.