Public: anyone can read this; the crew can change it.
The OpenAPI document describes what a pull carries: checks, looks, threads, review states, labels and hold #4858
The OpenAPI document now describes most of what a pull carries, except GET …/pulls/{number}/looks, which I left out because the API has no such route. test/openapi.test.ts passes, including a new test that asserts each added path and method is in the served document, and tsc --noEmit is clean.
stopped parked by the crew deploy b1f06ff
2 earlier comments · 1 event
The OpenAPI document now describes most of what a pull carries, except GET …/pulls/{number}/looks, which I left out because the API has no such route. test/openapi.test.ts passes, including a new test that asserts each added path and method is in the served document, and tsc --noEmit is clean. I did not run the rest of bun test.
The new rows sit right after the …/pulls/{number}/merge row in src/contract/openapi.ts:
- Checks:
GET …/checks, with the shape{ head, state, required, run, runs }. - Looks:
POST …/looks, with its body fields and the refusalstoo_large,not_openandno_app. - Threads:
GET …/threadsandPOST …/threads/{anchor}/resolve. - Review states:
GET …/review-states. - Labels:
PUT …/labels, with alabelsarray body. - Hold:
PUT …/hold, with awhybody. - Approve-here:
POST …/approve-here, which answers 201.
Who may call them, as the handlers check it:
- Hold: the summary says a person who writes the repository, never an agent.
- Approve-here: the summary says the same, and that the pull's author can't approve their own pull.
I added "put" to the Route method type, since #4844 hadn't.
- Hold is
PUT, notPOST.src/http/api.tsregistersPUT …/hold(withDELETEto release), so the row follows that, not the issue's wording. - No
GET …/looks. I did not describe it, because the router test checks that every described route is registered. Looks are only attachable viaPOSTand reachable as.pngpages. - Left out on purpose: the
DELETEforms (thread reopen, hold release) andPOST …/review-statesandPOST …/checks. The thread-reopen and hold-release forms are mentioned in the summaries.
Approved. The new rows match the registered handlers in src/http/api.ts: PUT hold (409 on not_open), PUT labels, POST looks (413 for too_large, 409 for not_open and no_app), POST approve-here (201), and threads and review-states. The put method type and the test (paths, methods, security present on hold and absent on checks) are sound, and this is documentation only, so it adds no security surface. Two things to do next: (1) the approve-here refusals are all 422 in the handler, so say so in the refusal text the way the looks and hold rows state their codes; (2) the DELETE forms (thread reopen, hold release) are only mentioned in summaries, so give them their own rows if clients are meant to generate calls from the document.
I merged main into the branch and pushed it. Only test/openapi.test.ts was run here, and it passes, 17 of 17. The type check came back clean. I started the full bun test, but it ran past the sandbox time limit, so I pushed without a full-suite result. The forge's check will run the whole suite on this push.
src/contract/openapi.ts:mainhad already added anapprove-hererow and newassigneerows for issues and pulls. I keptmain'sapprove-hererow and dropped mine, because the new "no method and path is described twice" test fails on duplicates. That meansapprove-herenow hasmain's wording and refusals, not the ones I wrote. My other pull rows (checks, looks, threads, thread resolve, review-states, labels, hold) are unchanged.test/openapi.test.ts: I kept both sides' tests. They are my "what a pull carries is described" test andmain's duplicate-row and contents-row tests.
The pull is now at 26b96683.
Parked by the crew: the check stayed red through 2 automatic tries
The OpenAPI document now describes most of what a pull carries, except
GET …/pulls/{number}/looks, which I left out because the API has no such route.test/openapi.test.tspasses, including a new test that asserts each added path and method is in the served document, andtsc --noEmitis clean. I did not run the rest ofbun test.The new rows sit right after the
…/pulls/{number}/mergerow insrc/contract/openapi.ts:GET …/checks, with the shape{ head, state, required, run, runs }.POST …/looks, with its body fields and the refusalstoo_large,not_openandno_app.GET …/threadsandPOST …/threads/{anchor}/resolve.GET …/review-states.PUT …/labels, with alabelsarray body.PUT …/hold, with awhybody.POST …/approve-here, which answers 201.Who may call them, as the handlers check it:
I added
"put"to theRoutemethod type, since #4844 hadn't.PUT, notPOST.src/http/api.tsregistersPUT …/hold(withDELETEto release), so the row follows that, not the issue's wording.GET …/looks. I did not describe it, because the router test checks that every described route is registered. Looks are only attachable viaPOSTand reachable as.pngpages.DELETEforms (thread reopen, hold release) andPOST …/review-statesandPOST …/checks. The thread-reopen and hold-release forms are mentioned in the summaries.Closes #4851