scriptoriumadmin/Roo-Code
1
0
Fork 0
mirror of https://github.com/RooVetGit/Roo-Code.git synced 2026-09-06 08:18:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: document process for adding new settings (#2552)

Browse source 
Add documentation explaining how to implement new settings in Roo Code,
using the command risk level feature as a practical example.

Signed-off-by: Eric Wheeler <roo-code@z.ewheeler.org>
Co-authored-by: Eric Wheeler <roo-code@z.ewheeler.org>
This commit is contained in:
KJ7LNW 2025-04-12 20:54:43 -07:00 • committed by GitHub
parent 08110ae35b
commit e94e58ff1a
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 132 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

165
cline_docs/settings.md
View file

@ -183,39 +183,39 @@ These steps ensure that:
To add a new configuration item to the system, the following changes are necessary:
1. **Feature-Specific Class** (if applicable)
1. **Feature-Specific Class** (if applicable)
- For settings that affect specific features (e.g., Terminal, Browser, etc.)
- Add a static property to store the value
- Add getter/setter methods to access and modify the value
2. **Schema Definition**
2. **Schema Definition**
- Add the item to globalSettingsSchema in schemas/index.ts
- Add the item to globalSettingsRecord in schemas/index.ts
3. **Type Definitions**
3. **Type Definitions**
- Add the item to exports/types.ts
- Add the item to exports/roo-code.d.ts
- Add the item to shared/ExtensionMessage.ts
- Add the item to shared/WebviewMessage.ts
4. **UI Component**
4. **UI Component**
- Create or update a component in webview-ui/src/components/settings/
- Add appropriate slider/input controls with min/max/step values
- Ensure the props are passed correctly to the component in SettingsView.tsx
- Update the component's props interface to include the new settings
5. **Translations**
5. **Translations**
- Add label and description in webview-ui/src/i18n/locales/en/settings.json
- Update all other languages
- If any language content is changed, synchronize all other languages with that change
- Translations must be performed within "translation" mode so change modes for that purpose
6. **State Management**
6. **State Management**
- Add the item to the destructuring in SettingsView.tsx
- Add the item to the handleSubmit function in SettingsView.tsx
@ -223,11 +223,11 @@ To add a new configuration item to the system, the following changes are necessa
- Add the item to getState in ClineProvider.ts with appropriate default values
- Add the item to the initialization in resolveWebviewView in ClineProvider.ts
7. **Message Handling**
7. **Message Handling**
- Add a case for the item in webviewMessageHandler.ts
8. **Implementation-Specific Logic**
8. **Implementation-Specific Logic**
- Implement any feature-specific behavior triggered by the setting
- Examples:
@ -235,7 +235,7 @@ To add a new configuration item to the system, the following changes are necessa
- API configuration changes for provider settings
- UI behavior modifications for display settings
9. **Testing**
9. **Testing**
- Add test cases for the new settings in appropriate test files
- Verify settings persistence and state updates
@ -305,40 +305,139 @@ To add a new configuration item to the system, the following changes are necessa
11. **Debugging Settings Persistence Issues**
If a setting is not persisting across reload, check the following:
If a setting is not persisting across reload, check the following:
1. **Complete Chain of Persistence**:
1. **Complete Chain of Persistence**:
- Verify that the setting is added to all required locations:
- globalSettingsSchema and globalSettingsRecord in schemas/index.ts
- Initial state in ExtensionStateContextProvider
- getState method in ClineProvider.ts
- getStateToPostToWebview method in ClineProvider.ts
- resolveWebviewView method in ClineProvider.ts (if feature-specific)
- A break in any part of this chain can prevent persistence
- Verify that the setting is added to all required locations:
- globalSettingsSchema and globalSettingsRecord in schemas/index.ts
- Initial state in ExtensionStateContextProvider
- getState method in ClineProvider.ts
- getStateToPostToWebview method in ClineProvider.ts
- resolveWebviewView method in ClineProvider.ts (if feature-specific)
- A break in any part of this chain can prevent persistence
2. **Default Values Consistency**:
2. **Default Values Consistency**:
- Ensure default values are consistent across all locations
- Inconsistent defaults can cause unexpected behavior
- Ensure default values are consistent across all locations
- Inconsistent defaults can cause unexpected behavior
3. **Message Handling**:
3. **Message Handling**:
- Confirm the webviewMessageHandler.ts has a case for the setting
- Verify the message type matches what's sent from the UI
- Confirm the webviewMessageHandler.ts has a case for the setting
- Verify the message type matches what's sent from the UI
4. **UI Integration**:
4. **UI Integration**:
- Check that the setting is included in the handleSubmit function in SettingsView.tsx
- Ensure the UI component correctly updates the state
- Check that the setting is included in the handleSubmit function in SettingsView.tsx
- Ensure the UI component correctly updates the state
5. **Type Definitions**:
5. **Type Definitions**:
- Verify the setting is properly typed in all relevant interfaces
- Check for typos in property names across different files
- Verify the setting is properly typed in all relevant interfaces
- Check for typos in property names across different files
6. **Storage Mechanism**:
- For complex settings, ensure proper serialization/deserialization
- Check that the setting is being correctly stored in VSCode's globalState
6. **Storage Mechanism**:
- For complex settings, ensure proper serialization/deserialization
- Check that the setting is being correctly stored in VSCode's globalState
These checks help identify and resolve common issues with settings persistence.
12. **Advanced Troubleshooting: The Complete Settings Persistence Chain**
Settings persistence requires a complete chain of state management across multiple components. Understanding this chain is critical for both humans and AI to effectively troubleshoot persistence issues:
1. **Schema Definition (Entry Point)**:
- Settings must be properly defined in `globalSettingsSchema` and `globalSettingsRecord`
- Enum values should use proper zod schemas: `z.enum(["value1", "value2"])`
- Example:
```typescript
// In schemas/index.ts
export const globalSettingsSchema = z.object({
// Existing settings...
commandRiskLevel: z.enum(["readOnly", "reversibleChanges", "complexChanges"]).optional(),
})
const globalSettingsRecord: GlobalSettingsRecord = {
// Existing settings...
commandRiskLevel: undefined,
}
```
2. **UI Component (User Interaction)**:
- Must use consistent components (Select vs. select) with other similar settings
- Must use `setCachedStateField` for state updates, not direct state setting
- Must generate the correct message type through `vscode.postMessage`
- Example:
```tsx
// In a settings component
<Select value={commandRiskLevel} onValueChange={(value) => setCachedStateField("commandRiskLevel", value)}>
<SelectTrigger className="w-full">
<SelectValue placeholder={t("settings:common.select")} />
</SelectTrigger>
<SelectContent>
<SelectGroup>
<SelectItem value="readOnly">{t("label.readOnly")}</SelectItem>
{/* Other options... */}
</SelectGroup>
</SelectContent>
</Select>
```
3. **Message Handler (State Saving)**:
- Must use correct message type in `webviewMessageHandler.ts`
- Must use `updateGlobalState` with properly typed values
- Must call `postStateToWebview` after updates
- Example:
```typescript
// In webviewMessageHandler.ts
case "commandRiskLevel":
await updateGlobalState(
"commandRiskLevel",
(message.text ?? "readOnly") as "readOnly" | "reversibleChanges" | "complexChanges"
)
await provider.postStateToWebview()
break
```
4. **State Retrieval (Reading State)**:
- In `getState`, state must be properly retrieved from stateValues
- In `getStateToPostToWebview`, the setting must be in the destructured parameters
- The setting must be included in the return value
- Use `contextProxy.getGlobalState` for direct access when needed
- Example:
```typescript
// In ClineProvider.ts getStateToPostToWebview
const {
// Other state properties...
commandRiskLevel,
} = await this.getState()
return {
// Other state properties...
commandRiskLevel: commandRiskLevel ?? "readOnly",
}
```
5. **Debugging Strategies**:
- **Follow the State Flow**: Watch the setting's value at each step in the chain
- **Type Safety**: Ensure the same type is used throughout the chain
- **Component Consistency**: Use the same pattern as other working settings
- **Check Return Values**: Ensure the setting is included in all return objects
- **State vs. Configuration**: Understand when to use state vs. VSCode configuration
6. **Common Pitfalls**:
- **Type Mismatch**: Using string where an enum is expected
- **Chain Breaks**: Missing the setting in return objects
- **UI Inconsistency**: Using different component patterns
- **DefaultValue Issues**: Inconsistent default values across components
- **Missing Schema**: Not adding to schema or record definitions
Remember: A break at ANY point in this chain can cause persistence failures. When troubleshooting, systematically check each link in the chain to identify where the issue occurs.