Skip to content

Commit 3cc81c7

Browse files
KJ7LNWEric Wheeler
KJ7LNW
and
Eric Wheeler
authored
docs: update settings.md with comprehensive steps (#2451)
* docs: update settings.md with comprehensive steps Update the settings documentation to include all necessary steps for adding a new configuration item, including schema definitions, type definitions, and critical steps for persistence and UI display. This ensures the documentation accurately reflects the complete process required when adding new settings to the application. Signed-off-by: Eric Wheeler <[email protected]> * docs: add style considerations for checkbox settings Add documentation about styling checkbox settings in the UI, including: - Using VSCodeCheckbox component - Proper wrapping and spacing - Consistent styling for labels and descriptions - Example implementation based on terminalPowershellCounter Signed-off-by: Eric Wheeler <[email protected]> * docs: add comprehensive guide for adding new configuration items Add a new section to settings.md that provides a complete checklist for adding new configuration items to the system. This guide covers all aspects from UI to persistence to functionality, based on implementation experience. Signed-off-by: Eric Wheeler <[email protected]> * docs: update settings documentation with persistence guidelines Add comprehensive guidance for ensuring settings persist across reload Include debugging steps for troubleshooting persistence issues Replace 'Avoiding Duplicates' section with more detailed information Signed-off-by: Eric Wheeler <[email protected]> --------- Signed-off-by: Eric Wheeler <[email protected]> Co-authored-by: Eric Wheeler <[email protected]>
1 parent e41d6a4 commit 3cc81c7

File tree

1 file changed

+202
-6
lines changed

1 file changed

+202
-6
lines changed

‎cline_docs/settings.md‎

Lines changed: 202 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,20 @@
11
## For All Settings
22

3-
1. Add the setting to ExtensionMessage.ts:
3+
1. Add the setting to schema definitions:
44

5-
- Add the setting to the ExtensionState interface
6-
- Make it required if it has a default value, optional if it can be undefined
7-
- Example: `preferredLanguage: string`
5+
- Add the item to `globalSettingsSchema` in `schemas/index.ts`
6+
- Add the item to `globalSettingsRecord` in `schemas/index.ts`
7+
- Example: `terminalCommandDelay: z.number().optional(),`
88

9-
2. Add test coverage:
9+
2. Add the setting to type definitions:
10+
11+
- Add the item to `exports/types.ts`
12+
- Add the item to `exports/roo-code.d.ts`
13+
- Add the setting to `shared/ExtensionMessage.ts`
14+
- Add the setting to the WebviewMessage type in `shared/WebviewMessage.ts`
15+
- Example: `terminalCommandDelay?: number | undefined`
16+
17+
3. Add test coverage:
1018
- Add the setting to mockState in ClineProvider.test.ts
1119
- Add test cases for setting persistence and state updates
1220
- Ensure all tests pass before submitting changes
@@ -64,12 +72,35 @@
6472
```
6573

6674
5. Add the setting to handleSubmit in SettingsView.tsx:
67-
- Add a vscode.postMessage call to send the setting's value when clicking Done
75+
76+
- Add a vscode.postMessage call to send the setting's value when clicking Save
77+
- This step is critical for persistence - without it, the setting will not be saved when the user clicks Save
6878
- Example:
6979
```typescript
7080
vscode.postMessage({ type: "multisearchDiffEnabled", bool: multisearchDiffEnabled })
7181
```
7282

83+
6. Style Considerations:
84+
- Use the VSCodeCheckbox component from @vscode/webview-ui-toolkit/react instead of HTML input elements
85+
- Wrap each checkbox in a div element for proper spacing
86+
- Use a span with className="font-medium" for the checkbox label inside the VSCodeCheckbox component
87+
- Place the description in a separate div with className="text-vscode-descriptionForeground text-sm mt-1"
88+
- Maintain consistent spacing between configuration options
89+
- Example:
90+
```typescript
91+
<div>
92+
<VSCodeCheckbox
93+
checked={terminalPowershellCounter ?? true}
94+
onChange={(e: any) => setCachedStateField("terminalPowershellCounter", e.target.checked)}
95+
data-testid="terminal-powershell-counter-checkbox">
96+
<span className="font-medium">{t("settings:terminal.powershellCounter.label")}</span>
97+
</VSCodeCheckbox>
98+
<div className="text-vscode-descriptionForeground text-sm mt-1">
99+
{t("settings:terminal.powershellCounter.description")}
100+
</div>
101+
</div>
102+
```
103+
73104
## For Select/Dropdown Settings
74105

75106
1. Add the message type to WebviewMessage.ts:
@@ -98,6 +129,7 @@
98129
- Add the setting to the return value in getState with a default value
99130
- Add the setting to the destructured variables in getStateToPostToWebview
100131
- Add the setting to the return value in getStateToPostToWebview
132+
- This step is critical for UI display - without it, the setting will not be displayed in the UI
101133
- Add a case in setWebviewMessageListener to handle the setting's message type
102134
- Example:
103135
```typescript
@@ -146,3 +178,167 @@ These steps ensure that:
146178
- The setting's value is properly synchronized between the webview and extension
147179
- The setting has a proper UI representation in the settings view
148180
- Test coverage is maintained for the new setting
181+
182+
## Adding a New Configuration Item: Summary of Required Changes
183+
184+
To add a new configuration item to the system, the following changes are necessary:
185+
186+
1. **Feature-Specific Class** (if applicable)
187+
188+
- For settings that affect specific features (e.g., Terminal, Browser, etc.)
189+
- Add a static property to store the value
190+
- Add getter/setter methods to access and modify the value
191+
192+
2. **Schema Definition**
193+
194+
- Add the item to globalSettingsSchema in schemas/index.ts
195+
- Add the item to globalSettingsRecord in schemas/index.ts
196+
197+
3. **Type Definitions**
198+
199+
- Add the item to exports/types.ts
200+
- Add the item to exports/roo-code.d.ts
201+
- Add the item to shared/ExtensionMessage.ts
202+
- Add the item to shared/WebviewMessage.ts
203+
204+
4. **UI Component**
205+
206+
- Create or update a component in webview-ui/src/components/settings/
207+
- Add appropriate slider/input controls with min/max/step values
208+
- Ensure the props are passed correctly to the component in SettingsView.tsx
209+
- Update the component's props interface to include the new settings
210+
211+
5. **Translations**
212+
213+
- Add label and description in webview-ui/src/i18n/locales/en/settings.json
214+
- Update all other languages
215+
- If any language content is changed, synchronize all other languages with that change
216+
- Translations must be performed within "translation" mode so change modes for that purpose
217+
218+
6. **State Management**
219+
220+
- Add the item to the destructuring in SettingsView.tsx
221+
- Add the item to the handleSubmit function in SettingsView.tsx
222+
- Add the item to getStateToPostToWebview in ClineProvider.ts
223+
- Add the item to getState in ClineProvider.ts with appropriate default values
224+
- Add the item to the initialization in resolveWebviewView in ClineProvider.ts
225+
226+
7. **Message Handling**
227+
228+
- Add a case for the item in webviewMessageHandler.ts
229+
230+
8. **Implementation-Specific Logic**
231+
232+
- Implement any feature-specific behavior triggered by the setting
233+
- Examples:
234+
- Environment variables for terminal settings
235+
- API configuration changes for provider settings
236+
- UI behavior modifications for display settings
237+
238+
9. **Testing**
239+
240+
- Add test cases for the new settings in appropriate test files
241+
- Verify settings persistence and state updates
242+
243+
10. **Ensuring Settings Persistence Across Reload**
244+
245+
To ensure settings persist across application reload, several key components must be properly configured:
246+
247+
1. **Initial State in ExtensionStateContextProvider**:
248+
249+
- Add the setting to the initial state in the useState call
250+
- Example:
251+
```typescript
252+
const [state, setState] = useState<ExtensionState>({
253+
// existing settings...
254+
newSetting: false, // Default value for the new setting
255+
})
256+
```
257+
258+
2. **State Loading in ClineProvider**:
259+
260+
- Add the setting to the getState method to load it from storage
261+
- Example:
262+
```typescript
263+
return {
264+
// existing settings...
265+
newSetting: stateValues.newSetting ?? false,
266+
}
267+
```
268+
269+
3. **State Initialization in resolveWebviewView**:
270+
271+
- Add the setting to the initialization in resolveWebviewView
272+
- Example:
273+
```typescript
274+
this.getState().then(
275+
({
276+
// existing settings...
277+
newSetting,
278+
}) => {
279+
// Initialize the setting with its stored value or default
280+
FeatureClass.setNewSetting(newSetting ?? false)
281+
},
282+
)
283+
```
284+
285+
4. **State Transmission to Webview**:
286+
287+
- Add the setting to the getStateToPostToWebview method
288+
- Example:
289+
```typescript
290+
return {
291+
// existing settings...
292+
newSetting: newSetting ?? false,
293+
}
294+
```
295+
296+
5. **Setter Method in ExtensionStateContext**:
297+
- Add the setter method to the contextValue object
298+
- Example:
299+
```typescript
300+
const contextValue: ExtensionStateContextType = {
301+
// existing properties and methods...
302+
setNewSetting: (value) => setState((prevState) => ({ ...prevState, newSetting: value })),
303+
}
304+
```
305+
306+
11. **Debugging Settings Persistence Issues**
307+
308+
If a setting is not persisting across reload, check the following:
309+
310+
1. **Complete Chain of Persistence**:
311+
312+
- Verify that the setting is added to all required locations:
313+
- globalSettingsSchema and globalSettingsRecord in schemas/index.ts
314+
- Initial state in ExtensionStateContextProvider
315+
- getState method in ClineProvider.ts
316+
- getStateToPostToWebview method in ClineProvider.ts
317+
- resolveWebviewView method in ClineProvider.ts (if feature-specific)
318+
- A break in any part of this chain can prevent persistence
319+
320+
2. **Default Values Consistency**:
321+
322+
- Ensure default values are consistent across all locations
323+
- Inconsistent defaults can cause unexpected behavior
324+
325+
3. **Message Handling**:
326+
327+
- Confirm the webviewMessageHandler.ts has a case for the setting
328+
- Verify the message type matches what's sent from the UI
329+
330+
4. **UI Integration**:
331+
332+
- Check that the setting is included in the handleSubmit function in SettingsView.tsx
333+
- Ensure the UI component correctly updates the state
334+
335+
5. **Type Definitions**:
336+
337+
- Verify the setting is properly typed in all relevant interfaces
338+
- Check for typos in property names across different files
339+
340+
6. **Storage Mechanism**:
341+
- For complex settings, ensure proper serialization/deserialization
342+
- Check that the setting is being correctly stored in VSCode's globalState
343+
344+
These checks help identify and resolve common issues with settings persistence.

0 commit comments

Comments
 (0)