Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/fixed-tracker-say-it-once.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Activity monitor hovers, the merge-gate chip popover, the β‹― menu hints and the server captions say each thing once in plain words: the 090 "Ready for human merge" popover is now one sentence of state, one primary action ("Merge it") plus "More β‹―", who asked and when, and a collapsed Details holding how to trust the author and the rails; the untrusted-author reason, caption, next-move line and menu consequences lost their config keys, stage numbers and internal nouns and no longer repeat each other ([#15394](https://github.com/hivecommons/hive/issues/15394)).
1 change: 1 addition & 0 deletions src/docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ A terminal agent is a power tool: you hold it, aim it, and it stops when you sto
- [Operator reference](operator-reference.md)
- [GitHub webhooks: cadence, patch and reconcile](webhooks.md) β€” polling fallback, webhook patch and reconcile, and the state-accuracy guarantees.
- [Dashboard sections explained](dashboard-sections.md) β€” what each dashboard section shows and what to do about it.
- [Activity monitor copy inventory](dashboard-copy-inventory.md) β€” every operator-visible string builder in the activity monitor, with before/after word counts and the hover budget.
- [Hive on your iPhone Home Screen](ios-widget.md) β€” a Home Screen widget with issue/PR counts and sparklines (Scriptable, no server change).
- [Dashboard settings explained](settings.md) β€” what each Settings tab controls and where each setting is documented.
- [Maintainer commands](maintainer-commands.md) β€” slash commands for un-parking
Expand Down
82 changes: 82 additions & 0 deletions src/docs/dashboard-copy-inventory.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Activity monitor copy inventory

Every string builder whose output an operator can read on an activity
monitor row, hover, chip popover, β‹― menu, toast or feed line β€” with the
words it produced before and after [#15394](https://github.com/hivecommons/hive/issues/15394)
("this is WAY too much information … use easy to understand language and
much much less text").

Counts are the words the builder can emit for one row (the longest branch
where a builder has several), not the source size. The budget every hover
now meets: **one sentence of state, ≀ 40 visible words, one recommended
action, everything technical behind one collapsed Details, nothing said
twice.** The tests that hold the line are named in the last column.

## The reference case: hive#15315, chip "Ready for human merge Β· untrusted author"

| Surface part | Before (words) | After (words) |
|---|---:|---:|
| Question (`decisionForHumanMerge`) | 72 | 14 |
| Blocker (`decisionDCOBlocker` / hold) | 15 | 0 (folded into Details) |
| Action buttons | 7 buttons Β· 20 | 1 primary + "More β‹―" Β· 4 |
| Bulleted legend (`consequences`) | 120 | 0 (each line is now the β‹― menu item's hint) |
| "Asked by the hive Β· 7 hours ago" | 7 | 7 |
| Stage line echo (`data-ham-tip`: caption + reason + "Next move") | 150 | 0 visible (deduplicated; what is new sits in Details) |
| Details (collapsed) | β€” | 27 |
| **Visible total** | **β‰ˆ 384** | **β‰ˆ 29** |

The new hover, verbatim (title line omitted):

> **Ready to merge. Hive won't merge it alone β€” @odttlnt isn't a trusted author yet.**
> [ Merge it ] [ More β‹― ]
> Asked by the hive Β· 7 hours ago
> Details β–Έ *Hive never merges this on its own; a maintainer merges here or on GitHub. To trust @odttlnt: add them as a merger under βš™ Security β†’ Authorized users. Β· Ready for human merge Β· untrusted author Β· Next move: human β€” a maintainer merges it*

## Server-side builders (Go, `src/pkg/dashboard`)

| Builder | Reaches | Before | After | Held by |
|---|---|---:|---:|---|
| `stageTrackerUntrustedAuthorWhy` (all 10 trust reasons, summed) | question, reason text, delegated outcome | 314 | 68 | `TestStageTrackerHumanMergeSaysItOnce` (no config keys, no jargon) |
| `stageTrackerUntrustedAuthorFix` (new; the how-to-trust line, Details only) | Details | β€” | 81 | same |
| `stageTrackerHumanMergeReasonWords` tips (9 codes, summed) | chip hover, 090 chevron tip | 227 | 101 | `TestStageTrackerHumanMergeReason` |
| `HumanMergeReasonText` composition (090 untrusted author) | chevron tip, row tooltip, feed | 43 + 24 ("Until then a maintainer merges β€” Approve & merge…") | 11 | `TestStageTrackerHumanMergeSaysItOnce` |
| `HumanMergeReasonText` admitted prefix | same | 41 | 9 | `TestStageTrackerDecisionForHumanMerge/admitted…` |
| `stageTrackerCaption` 090 | row caption, feed | 19 | 7 | `TestStageTrackerCaption…` cases in `stage_tracker_test.go` |
| `stageTrackerStageActor` 090 `Why` ("Next move: human β€” …") | chevron tip, row tooltip | 43 (echoed `HumanMergeReasonText`) | 4 | `TestStageTrackerHumanMergeSaysItOnce` (no echo) |
| `decisionForHumanMerge` (question + blocker + 7 consequences) | chip popover, β‹― menu hints | 293 | 169 (of which Details 27, consequences ≀ 12 each) | `TestStageTrackerDecisionForHumanMerge` |
| `decisionMergeNowOption` consequence | popover title, menu hint | 11 | 8 | same |
| `decisionReauthorOption` consequence / disabled reason | menu hint | 31 / 29 | 12 / 14 | `TestStageTrackerDecisionForHumanMerge/unsigned…` |
| `decisionDCOBlocker` / `decisionDCOConsequence` | Details / menu hint | 39 / 17 | 29 / 8 | same |
| Other `decisionFor*` delegate / retry / close / resolve consequences (10 strings) | β‹― menu hints | 112 | 66 | word budget in `TestStageTrackerDecisionForHumanMerge` |
| `delegatedHumanMergeOutcome` rationale | "Let hive decide" outcome | 43 | 11 + fix line | `TestDelegatedDecisionReadyForHumanMergeAnswersWithMergeOptions` |

## SPA builders (`static-src/js`)

| Builder | Reaches | Before | After | Held by |
|---|---|---:|---:|---|
| `stageTrackerDecisionPopHtml` (`tracker-actions.js`) | chip popover / chevron popover | question + blocker + N buttons + legend + meta + stage echo (β‰ˆ 384 on #15315) | question + 1 button + "More β‹―" + meta (≀ 40), Details collapsed | `TestStageTrackerDecisionPopoverContent` (≀ 40 visible words, no duplicate sentence, banned-jargon list, no `a.b.c` keys) |
| `stageTrackerSayOnce` (new) | popover Details | β€” | β€” | same |
| `stageTrackerStripItems` 090 chevron tip (`tracker-row.js`) | chevron `title` / popover Details | word + reason + stage description + actor (β‰ˆ 70) | word + reason + actor (β‰ˆ 20) | `TestStageTrackerSentinelLane…` whyTip case |
| `stageTrackerTooltip` author line | row tooltip | `@x (author/clanker, inferred)` | `@x (agent, inferred)`; duplicate lines dropped | `TestStageTrackerRows` |
| `stageTrackerDCOCaveat` | confirm dialogs | 55 | 46 | `TestStageTrackerReauthor…` in `stage_tracker_row_actions_test.go` |
| Confirm: Approve & merge as maintainer | dialog | 76 | 53 | same |
| Confirm: Approve β€” let hive merge | dialog | 62 | 49 | same |
| β‹― menu hints (`stageTrackerLeadActions` β†’ `ham-menu-hint`) | β‹― menu | server consequences (11–31 each) | server consequences (≀ 12 each) | Go budget test |
| Toasts (`STAGE_TRACKER_ACTING_CAPTIONS`, acted labels) | toast | 2–4 each | unchanged | β€” |

## Totals

| | Before | After |
|---|---:|---:|
| Server builders above (sum of longest branches) | β‰ˆ 1,350 | β‰ˆ 620 (of which β‰ˆ 110 only ever shown inside Details) |
| #15315 hover, visible | β‰ˆ 384 | β‰ˆ 29 |

## Left as-is (follow-up)

- Merge-gate (080/095/100) chip tips in `stageTrackerMergeGateInfo` still say
*sweep* and *soak* ("next sweep in 42s", "soak 12m left"); they are live
clocks, short already, and a rename touches the gate's own tests. Tracked
under the same issue.
- The stage descriptions in `stagelabels.Table` are shared with the labels
and the docs and were not shortened; the 090 chevron tip simply stopped
appending them.
10 changes: 10 additions & 0 deletions src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,16 @@ These words have a special meaning in Hive. Each entry explains them again the f
- **Needs-human:** waiting on a person, for example for a decision or a review. It is also the name of a label.
- **Merge-eligible:** a pull request that passed every check Hive uses before it may merge it.

**Who is who in the activity monitor** ([#15394](https://github.com/hivecommons/hive/issues/15394)). Every hover, menu and caption uses these five nouns and no others:

- **Agent:** any automated worker β€” one of Hive's own agents or a contributor's connected agent. Hover text says *the author's agent* for the latter; the product noun **clanker** appears only where it names the contributor relay itself (the Contributors page, presence chips).
- **Contributor:** a person outside the maintainer team whose issue or pull request Hive is tracking.
- **Author:** whoever opened the pull request β€” a person, an agent or Hive. A **trusted author** is one Hive may merge for without asking.
- **Reviewer:** a person or agent that reviews a pull request; Hive's own review swarm is *the reviewer*.
- **Merge:** the one word for landing a pull request. *Merge it* is you merging now; *Let hive merge it* is you approving so Hive merges on its next pass.

Hover text follows one budget: one sentence of state in plain words, at most 40 visible words, one recommended action, and everything technical (config keys, stage numbers, how to change a setting) behind a single collapsed **Details**. The same sentence is never shown twice on one surface. The per-builder word counts live in [dashboard-copy-inventory.md](dashboard-copy-inventory.md).

**Dialogs on a phone.** Any dialog with a long body β€” the **What changed** release notes after an upgrade, alerts, the export viewer, the Level 6 auto-merge notice, settings bodies β€” fills the whole screen on a phone: title and a βœ• at the top, the text scrolls in the middle, and the buttons stay fixed at the bottom. A soft fade at the bottom edge means there is more to read; it disappears when you reach the end. Esc, the βœ•, the buttons and tapping the backdrop close it. On a desktop the same dialogs keep their usual size and only gain the fade and a thin scrollbar. See [Long-content modals](dashboard-design-system.md#long-content-modals-modal-scroll-and-the-mobile-sheet) for the convention.

## Overview
Expand Down
2 changes: 1 addition & 1 deletion src/pkg/dashboard/api_repo_item_decide_delegated_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -739,7 +739,7 @@ func TestDelegatedDecisionReadyForHumanMergeAnswersWithMergeOptions(t *testing.T
}
res := job.Result
t.Logf("outcome: %s\nnext: %s\nwhy: %s", res.Outcome, res.Next, res.Why)
for _, want := range []string{"I can't merge this: author @someone is untrusted on testrepo", "not a collaborator", "trusted or merger tier", "πŸ‘₯ Contributors"} {
for _, want := range []string{"I can't merge this: author @someone is untrusted on testrepo", "isn't a trusted author yet", "trusted tier under πŸ‘₯ Contributors"} {
if !strings.Contains(res.Outcome, want) {
t.Errorf("outcome %q missing %q", res.Outcome, want)
}
Expand Down
3 changes: 3 additions & 0 deletions src/pkg/dashboard/delegated_decision_human_merge.go
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,9 @@ func (s *Server) delegatedHumanMergeOutcome(repoFull string, number int, itemTyp
code = delegatedHumanMergeRule
}
why := stageTrackerUntrustedAuthorWhy(base, in.Author)
if fix := stageTrackerUntrustedAuthorFix(base, in.Author); why != "" && fix != "" {
why += ". " + strings.TrimSuffix(fix, ".")
}
if why == "" {
why = decisionPlainReason(base)
if base == "" || why == base {
Expand Down
Loading
Loading