From 529e9416c143f8843f536a93a4bde5d0b7603937 Mon Sep 17 00:00:00 2001 From: atlas Date: Thu, 3 Sep 2026 01:57:53 +0200 Subject: [PATCH] hive-forge: say which flat forms were removed and which are staying `docs/tools/forge.md` said the flat forms "still work as hidden back-compat aliases" and named `pr-create` and `pr-status` as its examples. Both refuse now: nine flat verbs parse only far enough to print the namespaced form that replaced them. The doc had no way to be read correctly, because the seven that do still work are hidden too and `--help` shows neither group. Naming the split here is the only place the difference is visible. At the enum the kind-agnostic seven now read as staying rather than as "still work", and `credential-helper` is marked as belonging to neither group: it is hidden because git invokes it, so a sweep reading `hide = true` as "deprecated" would remove checkout auth. Refs #3974. --- docs/tools/forge.md | 15 ++++++++++++--- hive-forge/src/main.rs | 13 +++++++++---- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/docs/tools/forge.md b/docs/tools/forge.md index f0029e1e..cbd4d254 100644 --- a/docs/tools/forge.md +++ b/docs/tools/forge.md @@ -31,9 +31,18 @@ refuses an issue number, which the old generic `close` couldn't). Run list (show/create/edit/status/merge/reviews/commits/diff/view/comment/ comments/close/reopen/labels/assign/dependency/reaction/timeline as applicable). -The flat forms below (`close 42`, `pr-create …`, `pr-status …`, …) still work -as **hidden back-compat aliases** during the transition and are dropped from -`--help`; prefer the namespaced form. They'll be removed in a later sweep. +The flat forms are two different groups, and `--help` hides both, so the +difference cannot be seen from the CLI and is stated here instead: + +- **Renamed — these no longer run.** `issue-create` `issue-edit` `pr-create` + `pr-status` `pr-merge` `pr-reviews` `pr-commits` `pr-assign-reviewer` `diff` + parse only far enough to print the namespaced form that replaced them, and + are removed outright in a later release. +- **Kind-agnostic — these stay.** `view` `comment` `comments` `close` `assign` + `labels` `timeline` are the only way to act on a number without already + knowing whether it is an issue or a PR, which no namespaced form offers. + Hidden, but supported; prefer `issue ` / `pr ` when the kind is + known, since those validate it. ```bash hive-forge pr close 42 # close a PR (kind-validated) diff --git a/hive-forge/src/main.rs b/hive-forge/src/main.rs index 7f59afa5..ff5e0aa6 100644 --- a/hive-forge/src/main.rs +++ b/hive-forge/src/main.rs @@ -71,10 +71,15 @@ enum Verb { // no `issue ` form, so a caller holding just a number can be // sent somewhere unambiguous. // - **Kind-agnostic** (`view`, `comment`, `comments`, `close`, - // `assign`, `labels`, `timeline`, …) still work. Each exists as both - // `issue ` and `pr `, so there is no single replacement - // to send a caller to when all they hold is a number — refusing - // these would remove a capability rather than rename one. + // `assign`, `labels`, `timeline`) **stay** — hidden, not deprecated. + // Each exists as both `issue ` and `pr `, so there is no + // single replacement to send a caller to when all they hold is a + // number: refusing these would remove a capability rather than + // rename one. + // + // `credential-helper` is hidden for a third reason and is in neither + // group — git invokes it, no human does. A sweep that reads + // `hide = true` as "deprecated" would take out checkout auth. /// Dump title + body + all comments for an issue or PR. #[command(hide = true)] View(verbs::view::Args),