Skip to content

Commit 4ed4a50

Browse files
committed
docs(FR-2571): address PR #6631 review feedback (excl. model store)
Addresses review comments on PR #6631 (Allowed client IPs / login screenshots) across all 4 languages. Model-store items are intentionally deferred to a separate change. Text edits: - header: rewrite V2 API wording (both Allowed client IPs and Original password notes) to explicit version gating — 'Backend.AI 26.4.0 and later' - vfolder §10.1: add clarification that the top-bar project is auto-selected for project folders - vfolder: rewrite write_content description as a per-folder (vfolder) RBAC permission, not a storage-host setting (verified via FolderExplorerModal.tsx — reads vfolder_node.permissions) - vfolder §10.3: describe folder rename as available only inside the detail drawer - vfolder §10.7: remove empty 'Folder Categories' heading - overview §3.3: add Project page row to the accessible-menu table Screenshots recaptured (EN + copied to ja/ko/th): - menu_collapse.png (Fig 7.2 sidebar — no customer-specific plugins) - data_page.png (Fig 10.1 / folder list with Controls merged into Name) - vfolder_create_modal.png (current folder-creation modal) - rename_vfolder.png (rename inside folder detail drawer) - move_to_trash.png (new Ant Design Modal, replacing Popconfirm) - vfolder_delete_dialog.png (current Delete Forever modal) - sessions_page.png (Fig 11.1 current Sessions page) - launch_session_resource_2.png (Cluster Mode step) - launch_session_data.png (Data & Storage step) Remaining TODO: header.png Login Session Timer (dev env has enableExtendLoginSession=false; timer not visible without backend config change). Applied identically across en/ko/ja/th with structural parity.
1 parent 197a31a commit 4ed4a50

54 files changed

Lines changed: 89 additions & 47 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.claude/agents/docs-screenshot-capturer.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,27 @@ Open the browser and log in:
130130
- Use `browser_snapshot` to find the correct `ref` for the element you want to capture
131131
- When UI has icon-only buttons, **always verify the button's accessible name** in the snapshot before clicking — e.g., "trash bin" vs download icon can look similar
132132

133+
**Re-capture preflight (when overwriting an existing screenshot):**
134+
135+
The filename of an existing screenshot encodes a contract about what it shows. Silently broadening the scope (e.g., turning a header strip into a full-page capture) breaks documentation that references it. Before overwriting any existing image:
136+
137+
1. Inspect the previous version's dimensions and visual scope:
138+
```bash
139+
git show main:packages/backend.ai-webui-docs/src/en/images/foo.png > /tmp/old.png
140+
file /tmp/old.png # note WIDTH x HEIGHT
141+
```
142+
2. Open `/tmp/old.png` and identify its scope:
143+
- Header strip: very wide, ≤300 px tall (e.g., 2358×222) → use `ref` of `[data-testid="webui-header"]`
144+
- Modal/dialog only: medium, no chrome (e.g., 988×804) → use `ref` of `.ant-modal-wrap .ant-modal` or `[role="dialog"]`
145+
- Sidebar segment: narrow column → use `ref` of `.ant-layout-sider`
146+
- Wizard step / panel: capture the specific panel `ref`, not the layout root
147+
- Full page (~viewport × viewport): `fullPage: true` is acceptable
148+
3. After capture, sanity-check dimensions match the same order of magnitude as the old. If new dimensions differ by more than ~2× in either axis, you broke the framing — recapture with `ref`.
149+
150+
**Anti-pattern observed in PR #6708**: `header.png` was 2358×222 (header strip) on `main`, recaptured as 2880×1800 (full viewport including sidebar + main content). The filename promised "header" but the new image showed everything. Always run the preflight above before overwriting.
151+
152+
If the framing genuinely needs to change, **rename the file** to reflect the new scope (e.g., `header.png``top_bar_with_session_timer.png`) and update all markdown references — never silently broaden an existing image.
153+
133154
```
134155
.playwright-mcp/packages/backend.ai-webui-docs/src/en/images/{filename}.png ← captured with English UI
135156
.playwright-mcp/packages/backend.ai-webui-docs/src/ko/images/{filename}.png ← captured with Korean UI

packages/backend.ai-webui-docs/SCREENSHOT-GUIDELINES.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,37 @@ Standards for capturing, naming, and maintaining screenshots in the Backend.AI W
6161
- Full-page captures are appropriate for page overview screenshots, but for feature-specific documentation, crop to the relevant area so users can clearly identify what is being described
6262
- Include just enough surrounding context for users to orient themselves
6363

64+
### Match the Existing Screenshot's Framing (for re-captures)
65+
66+
When **replacing an existing screenshot** (same filename), the new image MUST match the previous image's framing scope. The filename encodes a contract about what the image shows.
67+
68+
**Before recapturing**, run the following preflight on the file you intend to replace:
69+
70+
```bash
71+
# 1. Inspect the previous version's dimensions and visual scope
72+
git show main:path/to/images/foo.png > /tmp/old.png
73+
file /tmp/old.png # note WIDTH x HEIGHT
74+
# 2. Open /tmp/old.png and identify:
75+
# - Is it a header strip? (very wide, very short — e.g., 2358x222)
76+
# - Is it a modal/dialog only? (medium, no chrome — e.g., 988x804)
77+
# - Is it a sidebar segment? (narrow column — e.g., 1500x1098)
78+
# - Is it a full page? (~viewport width × viewport height — e.g., 2880x1800)
79+
```
80+
81+
Then capture the new screenshot at the **same scope**:
82+
83+
| Old image scope | Capture method |
84+
|---|---|
85+
| Header strip (e.g., `header.png`) | `ref` of `header`/top-bar element only — never `fullPage: true` |
86+
| Modal/dialog only | `ref` of `.ant-modal-wrap .ant-modal` or `[role="dialog"]` |
87+
| Sidebar segment | `ref` of the sidebar element |
88+
| Page region (e.g., a step in a wizard) | `ref` of the specific panel, not the whole layout |
89+
| Full page overview | `fullPage: true` is acceptable |
90+
91+
**Anti-pattern observed in PR #6708**: `header.png` was 2358×222 (header strip only) on `main`, recaptured as 2880×1800 (full viewport including sidebar + main content + breadcrumbs). The filename promises "header" but the new image shows everything. **Always run the preflight above before re-capturing.**
92+
93+
If the framing genuinely needs to change (e.g., the feature now spans more of the page), update the filename to reflect the new scope (e.g., `header.png``top_bar_with_session_timer.png`) rather than silently broadening an existing image.
94+
6495
### Cleanup After Capture
6596

6697
- **Always delete any resources created during screenshot capture** (folders, files, sessions, etc.)

packages/backend.ai-webui-docs/src/en/header/header.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ Each item has the following meaning. Enter the desired value and click the
112112

113113
- **Full Name**: User's name (up to 64 characters).
114114
- **Original password**: Your current password. This field is shown only when
115-
the server does not support the V2 user update API, and you must enter it
115+
connecting to a server prior to Backend.AI 26.4.0, and you must enter it
116116
when setting a new password on such servers.
117117
- **New password**: New password (8 characters or more containing at least 1
118118
alphabet, number, and symbol). Click the eye icon to reveal the input.
@@ -126,8 +126,7 @@ Each item has the following meaning. Enter the desired value and click the
126126
you must enter an OTP code at login.
127127

128128
:::note
129-
The **Allowed client IPs** field is available when the server supports the V2
130-
user update API.
129+
The **Allowed client IPs** field is available from Backend.AI 26.4.0 and later.
131130
:::
132131

133132
:::note
136 KB
Loading
-17.5 KB
Loading

packages/backend.ai-webui-docs/src/en/images/launce_session_resource_2.png renamed to packages/backend.ai-webui-docs/src/en/images/launch_session_resource_2.png

File renamed without changes.
-47.1 KB
Loading
-160 KB
Loading
57.9 KB
Loading
-65 KB
Loading

0 commit comments

Comments
 (0)