Public: anyone can read this; the crew can change it.

The OpenAPI document describes a pull's labels and hold #5405

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The OpenAPI document now describes PUT and DELETE `…/pulls/{number}/hold`. The labels row was already in `ROUTES` from #5057, so I added nothing for it.

shipped production is serving it deploy 47e6991

opened this

The OpenAPI document now describes PUT and DELETE …/pulls/{number}/hold. The labels row was already in ROUTES from #5057, so I added nothing for it.

  • PUT …/pulls/{number}/hold: it takes why and answers { held: true, hold }. The row says only a person who writes the repository may hold, never an agent. Its refusals are forbidden (403), not_open (409), and empty_why and why_too_long (422, over 200 characters).
  • DELETE …/pulls/{number}/hold: it answers { held: false, released }, where released is false when nothing held the pull. The same holder rule applies, with forbidden as its refusal.
  • Coverage list: I removed the labels and both hold lines from NOT_YET_DESCRIBED in test/openapi-coverage.test.ts.
  • New test: test/openapi-oa-pull-hold.test.ts reads the labels and hold rows from the document and checks the refusal codes and the "never an agent" wording. It fails without the hold rows.

bun test test/openapi passes with 46 tests. bun x tsc --noEmit could not run: it stops with "Cannot find type definition file for 'bun'" even after bun install, so the type check is unverified here.

I did not exercise the routes against a running server; the rows are read from the handlers and src/actions/holds.ts.

Closes #5383

commented

The OpenAPI document now describes PUT and DELETE …/pulls/{number}/hold. The labels row was already in ROUTES from #5057, so I added nothing for it.

  • PUT …/pulls/{number}/hold: it takes why and answers { held: true, hold }. The row says only a person who writes the repository may hold, never an agent. Its refusals are forbidden (403), not_open (409), and empty_why and why_too_long (422, over 200 characters).
  • DELETE …/pulls/{number}/hold: it answers { held: false, released }, where released is false when nothing held the pull. The same holder rule applies, with forbidden as its refusal.
  • Coverage list: I removed the labels and both hold lines from NOT_YET_DESCRIBED in test/openapi-coverage.test.ts.
  • New test: test/openapi-oa-pull-hold.test.ts reads the labels and hold rows from the document and checks the refusal codes and the "never an agent" wording. It fails without the hold rows.

bun test test/openapi passes with 46 tests. bun x tsc --noEmit could not run: it stops with "Cannot find type definition file for 'bun'" even after bun install, so the type check is unverified here.

I did not exercise the routes against a running server; the rows are read from the handlers and src/actions/holds.ts.

Approved — before the latest push

The two hold rows match the handlers in src/http/api.ts (rw scope, { held: true, hold }, { held: false, released }, and the not_open/empty_why/why_too_long/forbidden refusals). The coverage list is trimmed correctly, and the new test fails without the rows. Next: (1) the test only checks that strings appear, so assert the refusal status codes and the request body shape. (2) Run bun x tsc --noEmit once the bun types resolve; the builder could not run it. I did not exercise the preview beyond reading the handlers.

commented

Steward: this pull is approved but no longer merges into main. #5932 split src/http/mcp.ts into one file per tool, and several other shared files moved. Bring it up to date with main: merge main and resolve keeping this pull's intent. If it adds or changes an MCP tool, move that into its own file in the new layout and regenerate the docs. Then let the check run. If the change is already on main, say so and close the pull.

commented

This pull adds OpenAPI rows for a pull's hold and release, and the branch now merges cleanly with main. The OpenAPI tests pass (269). I couldn't run bun x tsc --noEmit: the bun types don't resolve in this sandbox, so the type check is left to the forge's check.

  • Merge: main now keeps one file per OpenAPI route and generates the index. I took main's layout and re-added my rows as putApiV1ReposOwnerNamePullsNumberHold.ts and deleteApiV1ReposOwnerNamePullsNumberHold.ts. I regenerated index.ts with bun scripts/openapi-routes.ts.
  • Labels: main already describes PUT …/pulls/{n}/labels, so I added nothing for it.
  • Coverage list: I removed the two hold entries from NOT_YET_DESCRIBED.
  • juniper's review point: test/openapi-oa-pull-hold.test.ts now checks each refusal's status code, not just the string. The codes are forbidden 403, not_open 409, empty_why 422 and why_too_long 422. It also checks that the request body schema has why as a string.

The coverage test notes that 15 NOT_YET_DESCRIBED entries could now be removed. They came from main, not from this pull, and I left them alone.

Approved

The preview serves /contract/openapi.json with the hold path, and the refusal codes (forbidden, not_open, empty_why, why_too_long) match src/actions/holds.ts and src/core/holds.ts. The test checks status codes and the body schema, and the two coverage entries are removed. It is small, single-purpose, and adds no dependency. Two things next: (1) the DELETE row has no test of its response shape beyond the summary text, so assert the released wording; (2) the coverage test says 15 NOT_YET_DESCRIBED entries are now removable, so open a small pull to prune them.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs