[Schema Inaccuracy] pull-request-review.state and two siblings should be enum, not string

Aperta Adatta ai principianti
#6,345 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
70/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Tranquilla
Stack tecnologico
openapi
Ambito
api

Direzione di ricerca

Inizia individuando gli schemi dei componenti pull-request-review.state, timeline-reviewed-event.state e webhooks_review.state, quindi confrontali con i valori documentati dell’API e con il precedente inline webhook-pull-request-review-dismissed.review.state. Il lavoro è completato quando lo schema REST elenca i cinque valori in maiuscolo, mentre gli schemi timeline e webhook condiviso elencano i quattro valori submitted-review in minuscolo.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation

Schema Inaccuracy

Three schemas type their review state property as a plain string rather than an enum, even though the value is constrained to a documented set.

REST (uppercase values):

  1. components/schemas/pull-request-review.state{ "type": "string", "example": "CHANGES_REQUESTED" }. Used by GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews and every other endpoint returning a review.

Event records (lowercase values):

  1. components/schemas/timeline-reviewed-event.state{ "type": "string", "example": "CHANGES_REQUESTED" }. Returned by GET /repos/{owner}/{repo}/issues/{issue_number}/timeline. The example value here is uppercase, but the live API returns lowercase for this surface (see Reproduction below).
  2. components/schemas/webhooks_review.state{ "type": "string" }, $ref'd from webhook-pull-request-review-submitted.review and -edited.review. Webhook payloads deliver lowercase.

The canonical value list is GitHub's own GraphQL PullRequestReviewState enum: APPROVED, CHANGES_REQUESTED, COMMENTED, DISMISSED, PENDING. Prior precedent for citing the GraphQL enum as the source of truth: #74 (author_association), which was resolved by introducing a shared author-association component schema with the enum drawn from the GraphQL CommentAuthorAssociation enum.

Expected

pull-request-review.state (REST) should enumerate the uppercase values the API returns:

"state": {
  "type": "string",
  "enum": ["APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED", "PENDING"],
  "example": "CHANGES_REQUESTED"
}

timeline-reviewed-event.state and webhooks_review.state should enumerate the lowercase values these surfaces actually deliver (pending is omitted because reviews don't reach event records or webhook payloads until submitted):

"state": {
  "type": "string",
  "enum": ["approved", "changes_requested", "commented", "dismissed"]
}

The inline webhook-pull-request-review-dismissed.review.state already declares the enum ["dismissed", "approved", "changes_requested"] directly — precedent for the same fix on webhooks_review.state.

Reproduction Steps

REST pull-request-review.state returns uppercase:

$ curl -s -H "Accept: application/vnd.github+json" \
    -H "X-GitHub-Api-Version: 2022-11-28" \
    https://api.github.com/repos/kubernetes/kubernetes/pulls/90000/reviews \
    | jq '[.[].state] | unique'
[
  "APPROVED",
  "CHANGES_REQUESTED",
  "COMMENTED"
]

timeline-reviewed-event.state returns lowercase from the same PR (despite the spec's uppercase example: "CHANGES_REQUESTED"):

$ curl -s -H "Accept: application/vnd.github+json" \
    -H "X-GitHub-Api-Version: 2022-11-28" \
    https://api.github.com/repos/kubernetes/kubernetes/issues/90000/timeline \
    | jq -r '[.[] | select(.event == "reviewed") | .state] | unique'
[
  "approved",
  "changes_requested",
  "commented"
]
Lingua principale
Nessun dato sulla lingua
Stelle
1.6k
Fork
342
Merge medio
3h 33m
PR unite (30g)
51

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di github/rest-api-description

Tutte le issue di github/rest-api-description

Issue simili

Altre issue su Backend & API Design

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.