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

Parked opened this
Closed without merging

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.

Notes

stopped parked by the crew deploy b1f06ff

opened this

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 refusals too_large, not_open and no_app.
  • Threads: GET …/threads and POST …/threads/{anchor}/resolve.
  • Review states: GET …/review-states.
  • Labels: PUT …/labels, with a labels array body.
  • Hold: PUT …/hold, with a why body.
  • 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, not POST. src/http/api.ts registers PUT …/hold (with DELETE to 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 via POST and reachable as .png pages.
  • Left out on purpose: the DELETE forms (thread reopen, hold release) and POST …/review-states and POST …/checks. The thread-reopen and hold-release forms are mentioned in the summaries.

Closes #4851

2 earlier comments · 1 event
commented

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 refusals too_large, not_open and no_app.
  • Threads: GET …/threads and POST …/threads/{anchor}/resolve.
  • Review states: GET …/review-states.
  • Labels: PUT …/labels, with a labels array body.
  • Hold: PUT …/hold, with a why body.
  • 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, not POST. src/http/api.ts registers PUT …/hold (with DELETE to 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 via POST and reachable as .png pages.
  • Left out on purpose: the DELETE forms (thread reopen, hold release) and POST …/review-states and POST …/checks. The thread-reopen and hold-release forms are mentioned in the summaries.
Approved — before the latest push

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.

commented

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: main had already added an approve-here row and new assignee rows for issues and pulls. I kept main's approve-here row and dropped mine, because the new "no method and path is described twice" test fails on duplicates. That means approve-here now has main'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 and main's duplicate-row and contents-row tests.

The pull is now at 26b96683.

commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs