### Problem to solve Pending review comments (draft notes) are currently exposed as a `--draft` flag on the existing `glab mr note` verbs, plus a separate `publish` verb: | Action | Today | Status | | --- | --- | --- | | Create | `glab mr note create --draft` | Merged in !3885, released in v1.119.0 | | Publish | `glab mr note publish` | Merged in !3909, released in v1.120.0 | | List | `glab mr note list --draft` | Proposed in !3963 (#8563) | | Discard | `glab mr note delete --draft <id>` | Proposed in !3963 (#8563) | | Edit | `glab mr note update --draft <id>` | Proposed in #8569 | Draft notes are a different GitLab resource with a different API (`/merge_requests/:iid/draft_notes`, `DraftNotesService` in client-go) than published notes and discussions. Overloading every `mr note` verb with `--draft` has these costs: - Every verb branches on `--draft` into a separate code path, with its own client calls, output format, and error messages. `create` already has to dispatch `--draft` before `--reply`, and `list`/`delete`/`update` would each need a parallel implementation (!3963 adds `runDraft`, `completeDraft`, and a separate printer). - Flag matrices grow. `--draft` must be rejected with `--unique`, `--resolvable=false`, and `--internal` on `create`, and with `--type` and `--state` on `list`. Each rule needs validation code, help text, and tests. - The ID namespace changes under the same command: `glab mr note delete 123 456` deletes note 456, while `glab mr note delete --draft 123 456` deletes draft note 456. - `--draft` already means "draft merge request" on `glab mr create`, `glab mr update`, and `glab mr list`. `glab mr list --draft` and `glab mr note list --draft` would filter completely different things. - The publish step lives at `glab mr note publish`, detached from the commands that manage what it publishes. Discussed in !3885 (https://gitlab.com/gitlab-org/cli/-/merge_requests/3885#note_3928426677) and agreed by @viktomas, @phikai, and @andrei.zubov. This is the shape used by the original POC (!2932) and by https://gitlab.com/viktomas/note. ### Proposal Add a `draft` noun under `glab mr note` that owns the full pending review lifecycle, and remove the flag-based commands: ```shell glab mr note draft create [<id> | <branch>] [-m <body>] [--file <path> [--line N[:M] | --old-line N]] [--reply <discussion-id>] [--attach <file>] glab mr note draft list [<id> | <branch>] [--file <path>] [-F json] glab mr note draft update [<id> | <branch>] <draft-note-id> [-m <body>] [--attach <file>] glab mr note draft delete [<id> | <branch>] <draft-note-id> [--yes] glab mr note draft publish [<id> | <branch>] [-m <summary>] [--internal] [--reviewer-state requested_changes|reviewed] [--yes] ``` Mapping from the current and proposed commands: | Before | After | | --- | --- | | `glab mr note create --draft` | `glab mr note draft create` | | `glab mr note publish` | `glab mr note draft publish` | | `glab mr note list --draft` (!3963) | `glab mr note draft list` | | `glab mr note delete --draft` (!3963) | `glab mr note draft delete` | | `glab mr note update --draft` (#8569) | `glab mr note draft update` | Behavior carried over unchanged: - `draft create`: same diff targeting (`--file`, `--line`, `--old-line`), same `--reply` prefix resolution, same `--attach` behavior, and the success output stays the bare draft note ID so it can be piped into `draft update` and `draft delete`. Flags that never applied to drafts (`--unique`, `--resolvable`, `--internal`) do not exist on the new command, so their conflict rules and tests go away. - `draft publish`: same flags, confirmation prompt, `--yes` requirement when non-interactive, and the "no pending review comments" error from `glab mr note publish`. - `draft list` and `draft delete`: the output and prompt behavior designed in !3963. - `draft update`: the position-preserving update described in #8569 (re-send the existing `position`, because the API clears it otherwise: https://gitlab.com/gitlab-org/gitlab/-/work_items/631434). Removal of the old surface: - Remove `--draft` from `glab mr note create` and remove `glab mr note publish`, with no deprecation period. Both are marked `(EXPERIMENTAL)`, and the help text states that experimental features "might be unstable or removed at any time." Call out the removal in the MR and release notes. - Do not add `--draft` to `mr note list`, `mr note delete`, or `mr note update`. ### Further details Implementation notes: - Put the commands in their own package (for example `internal/commands/mr/note/draft/`), registered from `NewCmdNote` in `internal/commands/mr/note/mr_note.go` in place of `NewCmdPublish`. - Move the `--file`/`--line`/`--old-line` → `gitlab.PositionOptions` resolution currently inline in `mr_note_create.go` `complete` into a helper shared by `mr note create` and `mr note draft create`. `mrutils.BuildDiffPosition` and `mrutils.ResolveDiscussionID` are already shared. - Move `mr_note_publish.go`, its unit tests, and `Test_MrNotePublish_Integration` to the new package. The integration test currently creates its fixture with `NewCmdCreate` and `--draft`, so switch it to `draft create`. - Run `make gen-docs`. It generates `docs/source/mr/note/draft/*.md`, prunes `docs/source/mr/note/publish.md`, updates `docs/navigation-glab.yaml`, and removes the `--draft` section from `docs/source/mr/note/create.md`. - Keep `text.ExperimentalString` on every new command. Effect on in-flight work: - !3963 (@adityaswarupparida): retarget from `list --draft` / `delete --draft` to `draft list` / `draft delete`. The printing and prompt logic carries over. Only the command wiring and flag-conflict code changes. - #8569: retarget to `draft update`. Out of scope: - Publishing a single draft note (`PUT /draft_notes/:id/publish`). `draft publish` keeps the bulk "submit review" semantics. - Exposing the draft-notes `resolve_discussion` field ("resolve this thread when the review publishes"). Open question: should the noun be `draft`, matching the API and the original proposal, or `review`, matching the UI's "Start a review" and "Submit review"? This issue proposes `draft`. ### Links / references - Design discussion: https://gitlab.com/gitlab-org/cli/-/merge_requests/3885#note_3928426677 - `create --draft`: !3885 - `publish`: !3909 - Pending review workflow tracking: #8560 - List and discard: #8563, !3963 - Edit: #8569 - Original POC: !2932, epic https://gitlab.com/groups/gitlab-org/-/work_items/21295 - Prior art: https://gitlab.com/viktomas/note - Draft notes API: https://docs.gitlab.com/api/draft_notes/