Skip to content

Commit 601524f

Browse files
committed
docs(pull-request-workflow): fix the draft-check command
The check offered with the new rule did not run: `gh pr view --json` spells the field `isDraft`, while `draft` belongs to the REST payload and `gh api`. Copying it produced `Unknown JSON field: "draft"`. Corrects the field, names the discrepancy so the next reader does not trip on it in the other direction, and drops a sentence that argued for the practice instead of describing it. Assisted-by: claude-code:claude-opus-5 Agent-Session: https://claude.ai/code/session_014H1xwaAmrQRWUA3vx8bJcD Agent-Host: 0493f0 Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
1 parent 365f68a commit 601524f

1 file changed

Lines changed: 3 additions & 3 deletions

File tree

skills/git-workflow/references/pull-request-workflow.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1125,12 +1125,12 @@ Draft → Ready for Review → Changes Requested → Approved → Merged
11251125
11261126
**Draft is a state the PR returns to, not one it only starts in.** Opening every PR with `--draft` is the well-known half. The half that gets missed: when work resumes on a PR that is already "ready for review" — a rebase, a round of review fixes, another commit of any kind — convert it back *before the first push*, with `gh pr ready --undo <n>` (`glab mr update <iid> --draft`). Mark it ready again as a separate step, once the checks are green and the user has asked for it.
11271127
1128-
The reason is what "ready for review" tells everyone else. It is a standing request for a maintainer's time against a specific head, and mid-work heads do not deserve it: between the first fix commit and the last one, the PR advertises for review a state you already know is incomplete — sometimes one you know is broken, when the work is a response to a reviewer's finding. Reviewers who look during that window spend attention on a diff that is about to change, and a green CI run on an intermediate head reads as an endorsement of work that is not finished. The draft round-trip costs two commands and removes the whole class.
1128+
The reason is what "ready for review" tells everyone else. It is a standing request for a maintainer's time against a specific head, and mid-work heads do not deserve it: between the first fix commit and the last one, the PR advertises for review a state you already know is incomplete — sometimes one you know is broken, when the work is a response to a reviewer's finding. Reviewers who look during that window spend attention on a diff that is about to change, and a green CI run on an intermediate head reads as an endorsement of work that is not finished. The round-trip is two commands.
11291129
1130-
The tell that this was skipped is a PR whose recent commits are labelled as review fixes while `draft: false` held throughout. Check before you start, not after:
1130+
The tell that this was skipped is a PR whose recent commits are labelled as review fixes while it stayed out of draft throughout. Check before you start, not after — note that `gh pr view --json` spells the field `isDraft`, while the REST payload and `gh api` call it `draft`:
11311131
11321132
```bash
1133-
gh pr view "$PR" --json draft,headRefName,state --jq '{draft,headRefName,state}'
1133+
gh pr view "$PR" --json isDraft,headRefName,state --jq '{isDraft,headRefName,state}'
11341134
```
11351135
11361136
**The Draft → Ready edge only exists if the workflow listens for it.** `ready_for_review` is not in the `pull_request` default type set (`opened`, `synchronize`, `reopened`). A workflow declaring a bare `pull_request:` therefore never runs on that transition. Where such a workflow carries the auto-approval — typically a `pr-quality` job gated on `github.event.pull_request.draft == false` — the job skips while the PR is a draft and **nothing re-runs it when the draft is lifted**. The PR then sits at `reviewDecision: REVIEW_REQUIRED` with nothing red and no pending job, which reads as "waiting for a human" and is really "waiting for an event that will never come".

0 commit comments

Comments
 (0)