Skip to content

ENG-2407 Settings docs links point to wrong or unrelated docs pages - #1556

Merged
mdroidian merged 3 commits into
roam-setting-overhaulfrom
eng-2407-settings-docs-links-point-to-wrong-or-unrelated-docs-pages
Oct 27, 2026
Merged

mdroidian merged 3 commits into
roam-setting-overhaulfrom
eng-2407-settings-docs-links-point-to-wrong-or-unrelated-docs-pages

Conversation

@trangdoan982

@trangdoan982 trangdoan982 commented Oct 16, 2026 •

Copy link
Copy Markdown
Member

Reviewer brief

  • Stacked on Roam settings menu overhaul (M2) #1525 (roam-setting-overhaul). Merge that first.
  • Result: every docs link in Settings opens a page or section that describes its setting, and reads "View docs". Rows whose setting no docs page describes show no link.
  • Review focus: the link table in apps/roam/src/components/settings/utils/docs.tsx and the docsLink entries in apps/roam/src/components/settings/utils/settingsCatalog.ts. Components that pass their own description repeat the same link, so both places change together.
  • Deviation from the ticket: Auto canvas relations loses its link instead of getting a new one. No docs page describes adding relations automatically, so Done When 2 applies.
  • Risk or follow-up:
    • The rename also changes the Export dialog and the stored relations warning, since withDocsLink is shared. Both are in the screenshots below.
    • Descriptions with no closing period now read on into "View docs" (e.g. Overlay). The old "See more." had the same problem.

The diagram shows how each row's link was decided.

flowchart LR
  A["Setting row"] --> B{"Does a docs page<br/>describe the setting?"}
  B -- "whole page" --> C["Link the page<br/>(trigger, shortcut, context overlay)"]
  B -- "one section" --> D["Link the #anchor<br/>(tag, export options,<br/>enable stored relations, node Overlay)"]
  B -- "no" --> E["No link<br/>(format, template, specification, query,<br/>description, text popup, tool shortcut,<br/>auto canvas relations, append referenced node)"]
  C & D --> F["withDocsLink: 'View docs'"]
Loading

Verification

Scenario Input Expected Actual Pass
Export dialog link text Export Discourse Graph → Export → Export options Each docs link reads "View docs" and opens #export-options 6 links, all "View docs" → #export-options; "append referenced node" has none ✅
Stored relations warning Export Discourse Graph → Publish, with stored relations off The warning link reads "View docs" "View docs" → migration page ✅
Docs targets exist curl each URL in ROAM_DOCS on discoursegraphs.com 200, and the anchor id is present All 8 return 200; all 4 anchors present ✅
No regressions pnpm ci:validate Pass Pass ✅
Scenario Screenshot
Export dialog options read "View docs" Export dialog options read "View docs"
Stored relations warning reads "View docs" Stored relations warning reads "View docs"
  • No unit tests were added. The change only touches link URLs and link text, and no test asserts either.
  • Not verified: I didn't click through every Settings row in Roam. The links come from ROAM_DOCS, which the curl check covers.

Loom video

https://www.loom.com/share/eb434414651c46c78e98d22e701ebc11

Scope check

  • Ran $scope-check against the ENG ticket and final diff.
  • Scope beyond Done When: None. Links were also removed from rows the ticket didn't name: 4 Query settings, node Description, Text selection popup, Discourse tool keyboard shortcut, Export "append referenced node", and Auto canvas relations. They come from the full audit in the ticket's Solution and fall under "Rows with no matching docs show no link".

Standards check

  • Ran $dg-pr-adherence-check against the final diff and PR metadata.

No rule violations. The Loom is still outstanding.

Local delegated full review

  • Ran a comprehensive review of the entire final diff in a subagent with a fresh context. Use $dg-delegated-full-review when no other full-review workflow is available.

No correctness findings. The remaining notes were judgement calls on link targets, and they were settled during the audit.

🤖 Generated with Claude Code


Devin Review

trangdoan982 and others added 3 commits October 16, 2026 15:28
…ting

Link to section anchors where a page covers several settings, drop links
whose docs don't describe the setting, and rename "See more." to "View docs".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Entire-Checkpoint: 01M5330M4CR1A4PNK15KZZNZT2
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Entire-Checkpoint: 01M53396FYSXNFSKP0CH8ZB3Q1
No docs page describes adding relations automatically.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Entire-Checkpoint: 01M53BSZCK7MY7GHT5QBJ92TQQ
@vercel

vercel Bot commented Oct 16, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
discourse-graph Skipped Skipped Oct 16, 2026 10:34pm UTC

Request Review

@supabase

supabase Bot commented Oct 16, 2026

Copy link
Copy Markdown

This pull request has been ignored for the connected project zytfjzqyijgagqxrzbmz because there are no changes detected in packages/database/supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.


Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

@linear-code

linear-code Bot commented Oct 16, 2026

Copy link
Copy Markdown

ENG-2407

@devin-ai-integration devin-ai-integration Bot 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.

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

Devin Review

@mdroidian
mdroidian merged commit db82b0f into roam-setting-overhaul Oct 27, 2026
9 checks passed
@mdroidian
mdroidian deleted the eng-2407-settings-docs-links-point-to-wrong-or-unrelated-docs-pages branch October 27, 2026 02:19
trangdoan982 added a commit that referenced this pull request Nov 12, 2026
…1556)

* ENG-2407 Point settings docs links at the docs that describe each setting

Link to section anchors where a page covers several settings, drop links
whose docs don't describe the setting, and rename "See more." to "View docs".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Entire-Checkpoint: 01M5330M4CR1A4PNK15KZZNZT2

* ENG-2407 Pass unwrapped setting descriptions as plain JSX strings

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Entire-Checkpoint: 01M53396FYSXNFSKP0CH8ZB3Q1

* ENG-2407 Drop the Auto canvas relations docs link

No docs page describes adding relations automatically.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Entire-Checkpoint: 01M53BSZCK7MY7GHT5QBJ92TQQ

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
@trangdoan982 trangdoan982 mentioned this pull request Nov 12, 2026
3 tasks done

This branch was previously deployed

1 inactive deployment
Preview — 46710fbe Deployed Oct 16, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants