Skip to content

docs(rfc): record the sidebar app menu and status marks decision - #31104

Open
Pearcekieser wants to merge 1 commit into
mainfrom
pearcekieser/rfc-sidebar-app-menu
Open

Pearcekieser wants to merge 1 commit into
mainfrom
pearcekieser/rfc-sidebar-app-menu

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record which actions the sidebar app menu carries and which status marks a sidebar app row shows, so the implementation has an accepted design to follow.

#7883 asks for app management from the sidebar. #26362 added a right-click menu with Details and Unpin, and the rest of the menu waited on a product decision. Pearce (Pearcekieser) asked for the full menu and for marks such as "update available" on the sidebar row.

Why it matters

Without an accepted RFC on main, the implementation PR changes what a sidebar row does for every user with no recorded decision, and the First Principles lane blocks it. Today a user must go through Apps and Library to update, disable or uninstall an app, and the sidebar does not show that an update is waiting.

Not a goal

What changed (motivation → approach → change)

This PR adds docs/request-for-change/rfc-sidebar-app-menu.md with status accepted and adds its row to the RFC index. The document records the menu items in order and when each shows: Update to vX, Details, Open in Library, Mark notifications as read, Disable, Unpin and Uninstall…. It also records the two new row marks and their labels, the "N more" toggle mark, keyboard access, and how a touch hold opens the menu. Each item reuses an existing path. Update goes through the detail page and its trust consent. Disable and Uninstall run on the Library page, which already shows their results and errors, and Uninstall keeps its confirmation dialog. Disable and Unpin each carry a one-line hint that says what they do. Open, Enable and Settings are left out, and so is the Library tile's Sync, and the document says why. When the registry list fails to load, the menu keeps today's failure notice and agent hand-off as its last group. A backend that keeps failing to start gets the same pair, and the phone chat rail, which has no menu, leaves that mark out.

Backwards compatibility

Compatible: the PR adds a document and an index row and changes no code.

Removes nothing: no code, file or key is removed.

Tests

Proof: not provable -- docs or config only

Manual verification

N/A -- a document only. I verified the "Current behavior" claims against 4f7b1ee782 by reading the files that the document names.

Related Issues

Part of #7883

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@Pearcekieser
Pearcekieser requested review from a team and KiroCrewCaptain as code owners November 6, 2026 05:30
@Pearcekieser
Pearcekieser requested a review from Zedmor November 6, 2026 05:30
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 66f370931ab4486fc80d187e99c55d85faf59a7c touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 66f370931ab4486fc80d187e99c55d85faf59a7c ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 66f370931ab4486fc80d187e99c55d85faf59a7c — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

The PR adds only a design document and an index row, so it renders nothing and takes nothing away. The decision reuses existing paths: detail-page autoAction, Library dialogs and ackNotification.

Notes

  • Touch rule "the menu opens when the drag ends within 5 px of where the hold started" also catches a hold the user meant as a reorder that got cancelled. The implementation PR should test that a short jitter-and-release opens the menu rather than reading as a cancelled drag.
  • "The Library accepts these two requests from router state only" adds a new trigger surface for destructive actions on LibraryPage. The implementation PR should name it in its security section, alongside the detail page's autoAction rule.

[DESIGN-REVIEWED] 66f3709

Description read

[DESCRIPTION-READ] d9d5277461f3eabbfb210f75e22bb7f1a2ddc6bf0cc15c9076076f88d53f8e41

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 66f370931ab4486fc80d187e99c55d85faf59a7c and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 66f3709

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 66f370931ab4486fc80d187e99c55d85faf59a7c false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 66f370931ab4486fc80d187e99c55d85faf59a7c — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 66f3709

Verdict parsed from the review's SHA-scoped output markers for commit 66f370931ab4486fc80d187e99c55d85faf59a7c.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 66f370931ab4486fc80d187e99c55d85faf59a7c false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 6, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Hold at abde113: this needs a human product decision.

The document is accurate and well scoped, and every check is green. Approving it is the decision, though. The RFC says a maintainer accepts it by approving this PR (L17), and on #7883 the rest of the menu was described as waiting on a product decision. The menu set is a product choice: it puts Disable and Uninstall on the sidebar row, leaves out Enable and Settings, and adds two status marks. An automated review should not be the acceptance.

To clear this, a maintainer who owns the apps and sidebar surface approves the PR, which records acceptance. Until then, the front matter could read draft instead of accepted.

Non-blocking note: the Design lane's touch-gesture note is already covered by exit criterion 5.

— crew-pr-reviewer (r147)

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

note: Agreed. A maintainer's approval of this PR is the acceptance, and no automated lane stands in for it. The status line in the document says the same thing. I am keeping status: accepted because the file records the decision only when it merges, and the merge needs that approval anyway. If the approving maintainer wants draft until then, I will change it.

@bolichen97, you picked up #7883 on 11-05. Can you review this RFC and approve it if the menu items and the row marks look right to you? The implementation PR comes next and is linked to #7883.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Design brief for abde113 (RFC, docs only).

What it does: records the decision on #7883 for sidebar app rows: a full actions menu (on right-click, Shift+F10 or the context-menu key, and touch) in place of today's Details and Unpin, plus status marks on the row. It builds on #26362 and verifies today's behaviour at 4f7b1ee782 (AppRailMenu, appNavTarget, the detail-page update flow, the Library's disable and uninstall, the unread count and backend_status.restart_exhausted). It adds a README index row.

Pros: the actions a user already has in the Library become reachable from the row, through flows that exist today (the detail page's consented update, the Library's uninstall preview), so no new action path is designed here. Keyboard and touch entry are stated, and the touch hold is reconciled with the existing drag sensor.

Cons: it is a decision record only; nothing is built yet, so the menu's real behaviour still needs its own implementation PR and review.

Long-term tech debt: no.

Recommendation: sign. As an RFC, the sign-off belongs to the repository owner, so this is a comment rather than an approval. All 96 checks pass.

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This changes behaviour users already rely on, so it needs a design sign-off from a maintainer before it can merge. A maintainer will post the decision here.

To propose a design, follow the request-for-change process in CONTRIBUTING.md (docs/request-for-change/).

Review result on abde113: no blocking findings. The diff adds the RFC and one index row. No blocking repository rule applies to either path. The review checked each Current behavior claim against the named files at 4f7b1ee, and they hold. Merging this PR records the decision as accepted, so the approval has to come from a maintainer. Done well: every Current behavior claim names the file and symbol it depends on. The design also keeps two existing safeguards: the new Library requests are accepted from router state only, and Uninstall keeps its confirmation dialog.

Optional:

  • rfc-sidebar-app-menu.md:17 and README.md:203 record accepted but name only the requester. Other accepted rows on main name the maintainer who decided and the date. When a maintainer approves, consider adding that name, the date and doc-pr: 31104.
  • Line 50 shows "Mark notifications as read" whenever the row shows an unread count, and line 74 says that item clears the count. An app that pushes its own count with useNavBadge() overrides the bell count, so marking the notes as read leaves that count on the row. Consider naming both count sources on line 33 and basing line 50 on unacknowledged bell notes.
  • The ordered item list and exit criterion 1 (line 103) leave out the menu's existing registry-failure notice and its hand-off item. One sentence saying they stay would keep a failed registry read from looking like "no update", and it would match feat(sidebar): full actions menu and update and attention marks on app rows #31959.

@Pearcekieser
Pearcekieser force-pushed the pearcekieser/rfc-sidebar-app-menu branch from abde113 to 580bf91 Compare November 8, 2026 00:59
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Thanks. Two of the optional points are in 580bf91.

  • Mark notifications as read now shows while the app has unacknowledged bell notes, not whenever the row shows a count. Current behavior item 5 names both count sources: a count the app pushes with useNavBadge() wins over the bell-note count through mergeAppBadges, and the status-marks table says that a pushed count is the app's to clear. This matches the implementation in feat(sidebar): full actions menu and update and attention marks on app rows #31959.
  • The front matter now has doc-pr: 31104.

I left the decider's name and the date for the maintainer who approves, so the record names the person who made the decision.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 8, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Design brief for 580bf91. All 97 checks pass. I compared it with abde113, which my earlier brief covered.

What changed in the RFC text:

  • A row's unread count now has two named sources. An app that pushes its own count through useNavBadge() shows that count; otherwise the count comes from the app's unacknowledged bell notes (appNotificationBadges).
  • "Mark notifications as read" now shows when the app has unacknowledged bell notes, not whenever a count is shown. A count the app pushes itself is the app's to clear, and the status-mark table says the same.
  • doc-pr is now 31104, and the README row moves with main.

The direction is the same as before: one row menu with Update, Details, Open in Library, Mark notifications as read, Disable, Unpin and Uninstall, plus the update arrow and attention triangle. The edit is a correctness fix, since a menu item that cannot clear an app-pushed count is no longer offered for it.

  • Pros: the menu no longer offers an action that would leave the badge in place.
  • Cons: with an app-pushed count and no bell notes, the person has no menu way to clear the badge. That is by design, since the app owns that count.
  • Tech debt: none added. It records an existing split, and no code changes.

The sign-off stays with the owner.

@Pearcekieser
Pearcekieser force-pushed the pearcekieser/rfc-sidebar-app-menu branch from 580bf91 to d46a0d9 Compare November 8, 2026 02:13
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 8, 2026
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/rfc-sidebar-app-menu branch from 4e8d29b to 74710ab Compare November 9, 2026 03:29
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Thanks. Push 74710ab records that trade-off as accepted. On the phone chat page a failing backend shows only once the nav drawer is open, because a triangle on a row with no menu would leave the failure in a tooltip that touch cannot open. The sentence sits under Status marks, right after the one about the phone chat rail.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision readiness: checking Automated validation is still running labels Nov 9, 2026
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/rfc-sidebar-app-menu branch from 74710ab to 6cd6d54 Compare November 16, 2026 15:46
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 16, 2026
@KiroCrewCaptain

KiroCrewCaptain commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 7% chance that this change introduces a defect, within the 12% limit for approving on its own, but it is held at tier 2: design-doc-gate: D.

Docs-only RFC recording the sidebar app menu items and row status marks, plus its index row. I checked the Current behavior claims against head: AppRailMenu (Details/Unpin, registry ErrorNotice, trigger disabled during drag), appNavTarget excluding disabled/unavailable apps, LaunchpadTile's Disable/Uninstall (non-locked)/Sync rules, LibraryPage's uninstall preview dialog, TOUCH_HOLD_ACTIVATION 250ms/5px, restart_exhausted shown only on Dev Fleet, and AppDetailPage's router-state-only autoAction. All of them are accurate. The design reuses existing paths, and its new trust surface (Library accepts Disable/Uninstall from router state only) follows the established autoAction rule, which cross-site links cannot reach. Uninstall keeps its confirmation. Landing at status accepted with the doc PR follows the repository's convention. No code changes, CI green.

Tier: 2, held for a person: design-doc-gate: D.

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 66f370931a · 111 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 18, 2026
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/rfc-sidebar-app-menu branch from 6cd6d54 to 620c1b2 Compare November 18, 2026 14:31
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 18, 2026
@Pearcekieser
Pearcekieser enabled auto-merge (squash) November 18, 2026 22:13
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 19, 2026
@Pearcekieser
Pearcekieser force-pushed the pearcekieser/rfc-sidebar-app-menu branch from 620c1b2 to 66f3709 Compare November 19, 2026 10:59
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 19, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants