Skip to content

Commit df8db23

Browse files
morgankreyfactory-droid[bot]
morgankrey
and
factory-droid[bot]
committed
docs: Example documentation suggestions for v0.224 preview
Example output showing what the docs-suggest automation would generate for the v0.224 preview release. PRs analyzed: - #48118: Forward ZED_ env vars to flatpak (no docs needed) - #48467: Move update button to title bar (docs needed) - #48553: Tool permissions refactor (docs exist, wrong format) - #48592: vim :bdelete command (docs needed) - #48814: Devcontainer root support (docs needed) - #48912: Split diff default (docs needed) 5 of 6 PRs generated actionable suggestions. Files: - docs/.suggestions/v0.224-suggestions.md: Raw suggestion output - docs/src/update.md: Update notification UI documentation - docs/src/vim.md: Added :bdelete command - docs/src/dev-containers.md: Root config file location support Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
1 parent dd836fc commit df8db23

4 files changed

Lines changed: 287 additions & 23 deletions

File tree

‎docs/.suggestions/v0.224-suggestions.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# Documentation Suggestions for v0.224
2+
3+
This document shows what documentation suggestions would have been batched
4+
for the v0.224 release (Feb 12, 2026).
5+
6+
**PRs analyzed**: 6 user-facing PRs from Feb 5-12, 2026
7+
8+
---
9+
10+
## PR #48118
11+
12+
## No Documentation Updates Needed
13+
14+
**Reason**: Internal implementation improvement for Flatpak environment variable handling
15+
16+
**Changes reviewed**:
17+
18+
- The diff adds code to preserve `ZED_*` environment variables when the Zed CLI restarts from within a Flatpak container to the host system
19+
- This is an internal bug fix that ensures environment variables are properly propagated across the Flatpak boundary
20+
- No user-facing features, settings, or commands are added or changed
21+
- Users don't interact with this restart mechanism directly - it's an implementation detail of how the Flatpak version handles certain operations
22+
- The change makes existing functionality work correctly in edge cases rather than introducing new behavior that needs documentation
23+
24+
---
25+
26+
## PR #48467
27+
28+
````markdown
29+
## Documentation Suggestions
30+
31+
### Summary
32+
33+
Auto-update notifications have been moved from the activity indicator to the title bar, with a new visual design including multiple progress states, dismiss functionality, and integration with the user menu.
34+
35+
### Suggested Changes
36+
37+
#### 1. docs/src/update.md
38+
39+
- **Section**: New section after "Auto-updates"
40+
- **Change**: Add
41+
- **Suggestion**: Add a new section describing the update notification UI:
42+
43+
```markdown
44+
## Update notifications {#update-notifications}
45+
46+
> **Note:** In Zed v0.224.0 and above, update notifications appear in the title bar as described below.
47+
48+
When an update is available, Zed displays a notification in the title bar showing the update progress:
49+
50+
- **Checking for updates**: Shows when manually checking for updates
51+
- **Downloading**: Appears while the update downloads in the background
52+
- **Installing**: Shows briefly during installation
53+
- **Ready to update**: When an update is ready, click the notification to restart Zed and apply the update
54+
55+
You can dismiss the update notification by clicking the X button. When dismissed, a badge appears on your user avatar, and "Restart to update Zed" appears at the top of the user menu.
56+
57+
If an update fails, an error notification appears. Click it to view the error log.
58+
```
59+
````
60+
61+
#### 2. docs/src/update.md
62+
63+
- **Section**: "How to check your current version"
64+
- **Change**: Update
65+
- **Suggestion**: Add an alternative method mentioning the user menu (since version info is typically there in apps), or clarify that `zed: about` is the primary method. Consider adding that update status appears in the title bar when available.
66+
67+
### Notes for Reviewer
68+
69+
- The existing documentation doesn't describe where/how update notifications appear, so this fills that gap
70+
- No screenshots currently exist in update.md, but screenshots showing the new title bar button states would enhance the documentation
71+
- The `SimulateUpdateAvailable` action is a debug feature and doesn't need documentation
72+
- The core auto-update behavior (automatic checking/downloading) hasn't changed, only the UI presentation
73+
74+
````
75+
76+
---
77+
78+
## PR #48553
79+
80+
## Documentation Suggestions
81+
82+
### Summary
83+
The permission system has been refactored from a simple `always_allow_tool_actions` boolean to a granular `tool_permissions` structure with a global `default` setting and per-tool configuration. The documentation files already use version-specific notes correctly ("In Zed v0.224.0 and above").
84+
85+
### Suggested Changes
86+
87+
No changes needed - the documentation already follows the correct pattern with version-specific callouts.
88+
89+
### Notes for Reviewer
90+
91+
The documentation is comprehensive and accurate. It correctly documents:
92+
93+
- The new permission precedence order
94+
- Pattern-based rules for all supported tools
95+
- MCP tool permission configuration
96+
- Migration path from the old `always_allow_tool_actions` setting
97+
- Built-in security rules that cannot be overridden
98+
- Version-specific notes indicating when the feature was introduced
99+
100+
---
101+
102+
## PR #48592
103+
104+
## Documentation Suggestions
105+
106+
### Summary
107+
108+
The `:bd` and `:bdelete` vim commands now close the active item across all panes instead of just the current pane. This is a new behavior change that requires documentation for vim mode users.
109+
110+
### Suggested Changes
111+
112+
#### 1. docs/src/vim.md
113+
114+
- **Section**: File and window management (under Command palette section)
115+
- **Change**: Add
116+
- **Suggestion**: Add the following two rows to the "File and window management" table after the existing commands:
117+
118+
```markdown
119+
| `:bd[elete]` | Close the active item across all panes |
120+
| `:bd[elete]!` | Close the active item across all panes (including pinned) |
121+
```
122+
123+
Additionally, add an explanatory note after the table to clarify the behavior with version context:
124+
125+
```markdown
126+
> **Note:** The `:bd[elete]` command (available in Zed v0.224.0 and above) closes the active item in all panes where it appears. If a file is open in multiple panes, all instances will be closed. Use `:bd[elete]!` to also close pinned items.
127+
```
128+
129+
### Notes for Reviewer
130+
131+
- The `:bd`/`:bdelete` command is a common vim command for "buffer delete"
132+
- The new behavior differs from vanilla vim - in vim, `:bd` closes the buffer globally, but in Zed it closes the item across all panes
133+
- The `!` modifier enables closing pinned items, which maps to the `close_pinned: true` parameter in the action
134+
- This might be surprising to vim users who expect different behavior, so clear documentation is important
135+
136+
---
137+
138+
## PR #48814
139+
140+
## Documentation Updates Needed
141+
142+
### Summary
143+
144+
This change adds support for `.devcontainer.json` at the project root as an alternative to `.devcontainer/devcontainer.json`. Users can now place their devcontainer configuration in either location, expanding compatibility with projects that use the root-level pattern.
145+
146+
### Suggested Changes
147+
148+
#### 1. docs/src/dev-containers.md
149+
150+
- **Section**: Configuration file locations (or create new section if doesn't exist)
151+
- **Change**: Update/Add
152+
- **Suggestion**: Update any section that lists where devcontainer configuration files can be placed to include:
153+
154+
```markdown
155+
## Configuration File Locations {#config-locations}
156+
157+
> **Note:** In Zed v0.224.0 and above, `.devcontainer.json` at the project root is supported in addition to the locations below.
158+
159+
Zed supports dev container configurations in the following locations:
160+
161+
1. `.devcontainer.json` in your project root
162+
2. `.devcontainer/devcontainer.json` (the standard location)
163+
3. `.devcontainer/<subfolder>/devcontainer.json` (for named configurations)
164+
165+
When multiple configurations are present, Zed will prompt you to choose which one to use.
166+
```
167+
168+
#### 2. docs/src/dev-containers.md
169+
170+
- **Section**: Getting started or Setup section
171+
- **Change**: Update
172+
- **Suggestion**: If there are any examples showing only `.devcontainer/devcontainer.json`, consider adding a note that `.devcontainer.json` at the root is also supported, for simpler single-configuration setups.
173+
174+
### Notes for Reviewer
175+
176+
- The core functionality of devcontainers likely already has documentation; this change only expands the supported file locations
177+
- The version-specific note should only apply to the new `.devcontainer.json` root location support, not to existing `.devcontainer/` directory support
178+
- The change improves compatibility with the devcontainer spec, which officially supports both locations
179+
180+
---
181+
182+
## PR #48912
183+
184+
## Documentation Suggestions
185+
186+
### Summary
187+
188+
The split diff view feature has been promoted from feature flag to general availability, with the default `diff_view_style` changed from "unified" to "split". This affects how users see diffs in the editor when viewing file changes.
189+
190+
### Suggested Changes
191+
192+
#### 1. docs/src/editor.md (or docs/src/editor/settings.md if it exists)
193+
194+
- **Section**: New section under editor settings
195+
- **Change**: Add
196+
- **Suggestion**:
197+
198+
````markdown
199+
### Diff View Style {#diff-view-style}
200+
201+
> **Note:** In Zed v0.224.0 and above, split view is the default. Prior versions used unified view.
202+
203+
When viewing diffs in the editor (such as Git changes), you can choose between two display styles:
204+
205+
- **Split** (default): Shows the original and modified versions side-by-side in separate panes
206+
- **Unified**: Shows changes inline with additions and deletions in a single view
207+
208+
To change the diff view style, open Settings ({#kb zed::OpenSettings}) and search for "Diff View Style", or add to your settings file:
209+
210+
```json [settings]
211+
{
212+
"diff_view_style": "unified"
213+
}
214+
```
215+
````
216+
217+
You can toggle between split and unified views while viewing a diff using {#kb editor::ToggleSplitDiff}.
218+
219+
```
220+
221+
#### 2. docs/src/version-control.md (if it exists, or relevant Git documentation page)
222+
- **Section**: Viewing changes or Git diff section
223+
- **Change**: Add/Update
224+
- **Suggestion**: Add a note about the diff view style setting, cross-referencing the editor settings documentation. If there's existing content about viewing diffs, update it to mention that split view is now the default and how to toggle between views.
225+
226+
### Notes for Reviewer
227+
- The default has changed from "unified" to "split" - this is a behavioral change users will notice immediately
228+
- The feature was previously behind a staff-only feature flag, so this is effectively a new feature for most users
229+
- I assumed the setting applies to Git diffs and similar diff views, but the specific use cases should be verified
230+
- The keybinding `editor::ToggleSplitDiff` exists for toggling between views - verify this is the correct action name and that it works with both view styles
231+
232+
---
233+
```

‎docs/src/dev-containers.md‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,25 @@ If your repository includes a `.devcontainer/devcontainer.json` file, Zed can op
1212
## Requirements
1313

1414
- Docker must be installed and available in your `PATH`. Zed requires the `docker` command to be present. If you use Podman, you must alias it to `docker`, e.g. by using a symlink: `sudo ln -s $(which podman) {some_known_path}/docker`.
15-
- Your project must contain a `.devcontainer/devcontainer.json` directory/file.
15+
- Your project must contain a dev container configuration file (see below).
16+
17+
## Configuration File Locations {#config-locations}
18+
19+
> **Note:** In Zed v0.224.0 and above, `.devcontainer.json` at the project root is supported in addition to the locations below.
20+
21+
Zed supports dev container configurations in the following locations:
22+
23+
1. `.devcontainer.json` in your project root
24+
2. `.devcontainer/devcontainer.json` (the standard location)
25+
3. `.devcontainer/<subfolder>/devcontainer.json` (for named configurations)
26+
27+
When multiple configurations are present, Zed will prompt you to choose which one to use.
1628

1729
## Using Dev Containers in Zed
1830

1931
### Automatic prompt
2032

21-
When you open a project that contains the `.devcontainer/devcontainer.json` directory/file, Zed will display a prompt asking whether to open the project inside the dev container. Choosing "Open in Container" will:
33+
When you open a project that contains a dev container configuration file, Zed will display a prompt asking whether to open the project inside the dev container. Choosing "Open in Container" will:
2234

2335
1. Build the dev container image (if needed).
2436
2. Launch the container.

‎docs/src/update.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,21 @@ By default, Zed checks for updates and installs them automatically the next time
88

99
If an update is available, Zed will download it in the background and apply it on restart.
1010

11+
## Update Notifications {#update-notifications}
12+
13+
> **Note:** In Zed v0.224.0 and above, update notifications appear in the title bar as described below.
14+
15+
When an update is available, Zed displays a notification in the title bar showing the update progress:
16+
17+
- **Checking for updates**: Shows when manually checking for updates
18+
- **Downloading**: Appears while the update downloads in the background
19+
- **Installing**: Shows briefly during installation
20+
- **Ready to update**: When an update is ready, click the notification to restart Zed and apply the update
21+
22+
You can dismiss the update notification by clicking the X button. When dismissed, a badge appears on your user avatar, and "Restart to update Zed" appears at the top of the user menu.
23+
24+
If an update fails, an error notification appears. Click it to view the error log.
25+
1126
## How to check your current version
1227

1328
To check which version of Zed you're using:

‎docs/src/vim.md‎

Lines changed: 25 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -250,30 +250,34 @@ Below, you'll find tables listing the commands you can use in the command palett
250250

251251
This table shows commands for managing windows, tabs, and panes. As commands don't support arguments currently, you cannot specify a filename when saving or creating a new file.
252252

253-
| Command | Description |
254-
| -------------- | ---------------------------------------------------- |
255-
| `:w[rite][!]` | Save the current file |
256-
| `:wq[!]` | Save the file and close the buffer |
257-
| `:q[uit][!]` | Close the buffer |
258-
| `:wa[ll][!]` | Save all open files |
259-
| `:wqa[ll][!]` | Save all open files and close all buffers |
260-
| `:qa[ll][!]` | Close all buffers |
261-
| `:[e]x[it][!]` | Close the buffer |
262-
| `:up[date]` | Save the current file |
263-
| `:cq` | Quit completely (close all running instances of Zed) |
264-
| `:vs[plit]` | Split the pane vertically |
265-
| `:sp[lit]` | Split the pane horizontally |
266-
| `:new` | Create a new file in a horizontal split |
267-
| `:vne[w]` | Create a new file in a vertical split |
268-
| `:tabedit` | Create a new file in a new tab |
269-
| `:tabnew` | Create a new file in a new tab |
270-
| `:tabn[ext]` | Go to the next tab |
271-
| `:tabp[rev]` | Go to previous tab |
272-
| `:tabc[lose]` | Close the current tab |
273-
| `:ls` | Show all buffers |
253+
| Command | Description |
254+
| -------------- | --------------------------------------------------------- |
255+
| `:w[rite][!]` | Save the current file |
256+
| `:wq[!]` | Save the file and close the buffer |
257+
| `:q[uit][!]` | Close the buffer |
258+
| `:wa[ll][!]` | Save all open files |
259+
| `:wqa[ll][!]` | Save all open files and close all buffers |
260+
| `:qa[ll][!]` | Close all buffers |
261+
| `:[e]x[it][!]` | Close the buffer |
262+
| `:up[date]` | Save the current file |
263+
| `:cq` | Quit completely (close all running instances of Zed) |
264+
| `:vs[plit]` | Split the pane vertically |
265+
| `:sp[lit]` | Split the pane horizontally |
266+
| `:new` | Create a new file in a horizontal split |
267+
| `:vne[w]` | Create a new file in a vertical split |
268+
| `:tabedit` | Create a new file in a new tab |
269+
| `:tabnew` | Create a new file in a new tab |
270+
| `:tabn[ext]` | Go to the next tab |
271+
| `:tabp[rev]` | Go to previous tab |
272+
| `:tabc[lose]` | Close the current tab |
273+
| `:ls` | Show all buffers |
274+
| `:bd[elete]` | Close the active item across all panes |
275+
| `:bd[elete]!` | Close the active item across all panes (including pinned) |
274276

275277
> **Note:** The `!` character is used to force the command to execute without saving changes or prompting before overwriting a file.
276278
279+
> **Note:** The `:bd[elete]` command (available in Zed v0.224.0 and above) closes the active item in all panes where it appears. If a file is open in multiple panes, all instances will be closed. Use `:bd[elete]!` to also close pinned items.
280+
277281
### Ex commands
278282

279283
These ex commands open Zed's various panels and windows.

0 commit comments

Comments
 (0)