Skip to content

docs: document process for adding new settings #2552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mrubens merged 1 commit into from
Apr 13, 2025
Merged

docs: document process for adding new settings #2552

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 132 additions & 33 deletions cline_docs/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,59 +183,59 @@ 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
- Add the item to getStateToPostToWebview in ClineProvider.ts
- 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:
- Environment variables for terminal settings
- 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
Expand Down Expand Up @@ -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.