SDD: onboarding-setup-ux (requirements + spec + plan)#25
Conversation
There was a problem hiding this comment.
Pull request overview
Adds spec-driven development (SDD) documentation for the “Onboarding & Setup UX” epic, describing the intended unified FOSSE admin onboarding flow and an extensible provider architecture for ActivityPub + Bluesky setup/status.
Changes:
- Add requirements document capturing UX goals, constraints, and linked issues.
- Add a technical spec detailing the provider/registry architecture and OAuth bridge approach.
- Add an implementation plan and implementation notes document for the epic.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
sdd/onboarding-setup-ux/spec.md |
Defines the target UX and technical approach (menu, providers, OAuth bridge). |
sdd/onboarding-setup-ux/requirements.md |
Captures product requirements, constraints, and source references for the epic. |
sdd/onboarding-setup-ux/plan.md |
Breaks implementation into sequenced tasks and verification steps. |
sdd/onboarding-setup-ux/implementation-notes.md |
Records claimed deviations/limitations, but currently contains statements that don’t match the repository state. |
kraftbj
left a comment
kraftbj
left a comment
There was a problem hiding this comment.
Partial review focused on requirements.md and implementation-notes.md; haven't done a deep pass on spec.md yet. Leaving inline comments below for discussion before I dive further.
Add spec-driven development documents for the Onboarding & Setup UX epic (DOTCOM-16793). Covers the unified FOSSE admin menu, inline ActivityPub configuration, Bluesky OAuth bridge via Atmosphere, the connection-status dashboard, and the extensible Connection_Provider architecture for future protocol integrations. Updated after review feedback from @kraftbj: - Upstream-first OAuth (PRs to Atmosphere, not wp_redirect intercept) - Option projection pattern (fosse_ap_* with pre_option_* filters) - Minimum viable AP config (actor mode + post types only) - Bluesky handle setup friction acknowledged - Upstream-first policy added to constraints - implementation-notes.md reframed as forward-looking decisions
RCowles
force-pushed
the
add/onboarding-setup-ux-sdd
branch
from
0efde9c to
11c3c55
Compare
kraftbj
left a comment
kraftbj
left a comment
There was a problem hiding this comment.
Second pass after the force-push. requirements.md and spec.md both look good to go — every review point was addressed cleanly. plan.md still needs a full refresh to match the updated spec (stale wp_redirect intercept, missing option-projection steps, no upstream-PR task, outdated "Backfill" framing for Task 9). Copilot flagged the wp_redirect piece too — fully agree with that comment. Also agree with Copilot's suggestion to rename the implementation-notes.md H1 / intro so it doesn't mismatch the filename. Two tiny residual nits on spec.md inline below — optional, but while you're in there.
Resolving the threads that have been substantively addressed by the rewrite.
- Fix implementation-notes.md H1/intro to match filename - Update plan.md: remove wp_redirect intercept from Task 4, add option projection steps to Task 3, add upstream Atmosphere PR task (new Task 4), renumber tasks, fix Backfill framing to Update SDD docs - Update spec.md: remove OAuth bridge wording from Bluesky_Provider description and File Changes table, update Bluesky test description Agent-Logs-Url: https://github.com/Automattic/fosse/sessions/476965db-29b3-4ece-a383-b66e0fd9b43d Co-authored-by: RCowles <1421894+RCowles@users.noreply.github.com>
All addressed in 8233743:
|
Agent-Logs-Url: https://github.com/Automattic/fosse/sessions/e31a4ea3-d7b4-4027-ab63-b09b524b8380 Co-authored-by: RCowles <1421894+RCowles@users.noreply.github.com>
kraftbj
left a comment
kraftbj
left a comment
There was a problem hiding this comment.
Two follow-ups from a comprehensive review pass (full inventory below; the rest all checked out — claims about bundled/ source verified accurate, upstream-first honored, structural parity with sdd/bundled-backends/, AGENTS.md compliance clean).
- AP menu suppression scope — plan currently hides only AP's Settings submenu. AP also registers a top-level Dashboard page (
activitypub-social-web) and two Users submenus (activitypub-followers-list,activitypub-following-list). Since FOSSE is claiming the full admin surface for federation setup, those should all be hidden too — we can build FOSSE-owned equivalents later. Start clean. Details inline. - Deactivation/deletion story — deliberately deferred out of this epic. Tracked in DOTCOM-16865. A one-line note under "Known Limitations" in
planned-decisions.mdpointing at that issue is enough.
Everything else is fine. Ship once these are in.
| ## Requirements | ||
|
|
||
| 1. **Single top-level FOSSE admin menu** replacing the need to find AP under Settings and Atmosphere under Settings separately. Two sub-pages: Setup and Status. | ||
| 2. **Hide bundled plugins' native admin submenus** from the Settings menu so users are not confused by duplicate surfaces. Pages remain accessible by direct URL for power users. |
There was a problem hiding this comment.
Expand the scope here — not just the Settings submenu. Verified against bundled/activitypub/includes/wp-admin/class-menu.php:
- Line 28 — AP's Settings submenu (
activitypub, underoptions-general.php). Already handled. - Lines 42-49 — AP registers a top-level Dashboard page (
activitypub-social-web) whenactivitypub_reader_uiis on. Not handled. - Lines 57-79 — AP registers two Users submenus (
activitypub-followers-list,activitypub-following-list). Not handled.
FOSSE is claiming the unified admin surface for federation setup, so all of these should be hidden for consistency. We can add FOSSE-owned equivalents (follower lists, dashboard) later when we have a story for them. Better to start with one clean surface and build up than ship with three disjoint entry points.
Suggested requirement rewording: "Hide all bundled-plugin admin entries (Settings submenu, top-level Dashboard page, Users submenus) so FOSSE is the single admin surface for federation setup. Pages remain accessible by direct URL for power users."
| - **Do**: | ||
| 1. Create `Menu` class with `register()` static method that fires `fosse_register_providers`, calls `register_hooks()` on available providers, hooks `admin_menu` at priority 9 (register menu) and 99 (hide bundled menus), and hooks `admin_enqueue_scripts` for CSS. | ||
| 2. `add_menu_page('fosse')` with `dashicons-share` icon. Two submenu pages: Setup (slug `fosse`) and Status (slug `fosse-status`). | ||
| 3. `remove_submenu_page('options-general.php', 'activitypub')` and `remove_submenu_page('options-general.php', 'atmosphere')` at priority 99. |
There was a problem hiding this comment.
Task 2 step 3 should expand with the broader menu scope. The current plan only removes the two Settings submenu entries:
remove_submenu_page('options-general.php', 'activitypub')
remove_submenu_page('options-general.php', 'atmosphere')
Add removals for AP's top-level Dashboard and Users submenus:
remove_menu_page('activitypub-social-web')
remove_submenu_page('users.php', 'activitypub-followers-list')
remove_submenu_page('users.php', 'activitypub-following-list')
(Pages remain registered, so direct-URL access still works for power users.)
Atmosphere's admin is a single Settings submenu, so no additional removal there.
Verify step should add: "Playground: no AP or Atmosphere entries appear in Settings, Users, or the top-level menu."
| - **Decision**: `Menu::register()` fires `fosse_register_providers`, then iterates registered providers and calls `register_hooks()` on each. Provider hooks (like `admin_post_*` handlers) are only registered in admin context. | ||
| - **Reason**: Avoids registering admin-post handlers on front-end requests. The `is_admin()` guard in `fosse.php` already limits this to admin context, but having `Menu::register()` control the lifecycle is cleaner. | ||
|
|
||
| ## Known Limitations (Expected) |
There was a problem hiding this comment.
Add a deferral note under "Known Limitations (Expected)" covering the deactivation/deletion story:
Deactivation/deletion behavior is deferred. This epic does not define what happens to
fosse_ap_*options or menu state when FOSSE is deactivated or deleted, nor how FOSSE behaves if ActivityPub or Atmosphere are also installed as standalone plugins. Tracked separately in DOTCOM-16865 so the decision happens before production distribution.
The option-projection pattern (FOSSE stores fosse_ap_*, projects via pre_option_activitypub_*) is clean for the "FOSSE is active" case but needs a companion story for lifecycle events. Not blocking for MVP.
Expand AP menu suppression scope to cover all bundled-plugin admin entries (top-level Dashboard page, Users submenus) not just Settings. Add deactivation/deletion deferral note pointing to DOTCOM-16865. Update Bluesky_Provider descriptions to reflect upstream-first approach.
Add spec-driven development documents for the Onboarding & Setup UX epic (DOTCOM-16793). Covers the unified FOSSE admin menu, inline ActivityPub configuration, Bluesky OAuth bridge via Atmosphere, the connection-status dashboard, and the extensible
Connection_Providerarchitecture for future protocol integrations.