From 7ec5fac5f867a1a75be306317b68f1c8a53815ed Mon Sep 17 00:00:00 2001 From: Eric Wheeler Date: Wed, 9 Apr 2025 21:02:09 -0700 Subject: [PATCH 1/4] 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 --- cline_docs/settings.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/cline_docs/settings.md b/cline_docs/settings.md index f4b06826023..219107fecd3 100644 --- a/cline_docs/settings.md +++ b/cline_docs/settings.md @@ -1,12 +1,20 @@ ## For All Settings -1. Add the setting to ExtensionMessage.ts: +1. Add the setting to schema definitions: - - Add the setting to the ExtensionState interface - - Make it required if it has a default value, optional if it can be undefined - - Example: `preferredLanguage: string` + - Add the item to `globalSettingsSchema` in `schemas/index.ts` + - Add the item to `globalSettingsRecord` in `schemas/index.ts` + - Example: `terminalCommandDelay: z.number().optional(),` -2. Add test coverage: +2. Add the setting to type definitions: + + - Add the item to `exports/types.ts` + - Add the item to `exports/roo-code.d.ts` + - Add the setting to `shared/ExtensionMessage.ts` + - Add the setting to the WebviewMessage type in `shared/WebviewMessage.ts` + - Example: `terminalCommandDelay?: number | undefined` + +3. Add test coverage: - Add the setting to mockState in ClineProvider.test.ts - Add test cases for setting persistence and state updates - Ensure all tests pass before submitting changes @@ -64,7 +72,8 @@ ``` 5. Add the setting to handleSubmit in SettingsView.tsx: - - Add a vscode.postMessage call to send the setting's value when clicking Done + - Add a vscode.postMessage call to send the setting's value when clicking Save + - This step is critical for persistence - without it, the setting will not be saved when the user clicks Save - Example: ```typescript vscode.postMessage({ type: "multisearchDiffEnabled", bool: multisearchDiffEnabled }) @@ -98,6 +107,7 @@ - Add the setting to the return value in getState with a default value - Add the setting to the destructured variables in getStateToPostToWebview - Add the setting to the return value in getStateToPostToWebview + - This step is critical for UI display - without it, the setting will not be displayed in the UI - Add a case in setWebviewMessageListener to handle the setting's message type - Example: ```typescript From c948b74ee22447c4da6fdd70309ea921ec5be076 Mon Sep 17 00:00:00 2001 From: Eric Wheeler Date: Wed, 9 Apr 2025 21:33:23 -0700 Subject: [PATCH 2/4] 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 --- cline_docs/settings.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/cline_docs/settings.md b/cline_docs/settings.md index 219107fecd3..95e89690679 100644 --- a/cline_docs/settings.md +++ b/cline_docs/settings.md @@ -72,6 +72,7 @@ ``` 5. Add the setting to handleSubmit in SettingsView.tsx: + - Add a vscode.postMessage call to send the setting's value when clicking Save - This step is critical for persistence - without it, the setting will not be saved when the user clicks Save - Example: @@ -79,6 +80,27 @@ vscode.postMessage({ type: "multisearchDiffEnabled", bool: multisearchDiffEnabled }) ``` +6. Style Considerations: + - Use the VSCodeCheckbox component from @vscode/webview-ui-toolkit/react instead of HTML input elements + - Wrap each checkbox in a div element for proper spacing + - Use a span with className="font-medium" for the checkbox label inside the VSCodeCheckbox component + - Place the description in a separate div with className="text-vscode-descriptionForeground text-sm mt-1" + - Maintain consistent spacing between configuration options + - Example: + ```typescript +
+ setCachedStateField("terminalPowershellCounter", e.target.checked)} + data-testid="terminal-powershell-counter-checkbox"> + {t("settings:terminal.powershellCounter.label")} + +
+ {t("settings:terminal.powershellCounter.description")} +
+
+ ``` + ## For Select/Dropdown Settings 1. Add the message type to WebviewMessage.ts: From 8beae0c8eae47bf7cdacad8fddf557f1b65eb004 Mon Sep 17 00:00:00 2001 From: Eric Wheeler Date: Thu, 10 Apr 2025 17:48:40 -0700 Subject: [PATCH 3/4] 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 --- cline_docs/settings.md | 65 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/cline_docs/settings.md b/cline_docs/settings.md index 95e89690679..5d303cadf52 100644 --- a/cline_docs/settings.md +++ b/cline_docs/settings.md @@ -178,3 +178,68 @@ These steps ensure that: - The setting's value is properly synchronized between the webview and extension - The setting has a proper UI representation in the settings view - Test coverage is maintained for the new setting + +## Adding a New Configuration Item: Summary of Required Changes + +To add a new configuration item to the system, the following changes are necessary: + +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** + + - Add the item to globalSettingsSchema in schemas/index.ts + - Add the item to globalSettingsRecord in schemas/index.ts + +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** + + - 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** + + - 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** + + - 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** + + - Add a case for the item in webviewMessageHandler.ts + +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** + + - Add test cases for the new settings in appropriate test files + - Verify settings persistence and state updates + +10. **Avoiding Duplicates** + - Be careful to avoid duplicate handlers or UI components when adding new settings + - Check for existing similar settings to maintain consistent patterns From b18e809f0011d7f2300b2102697f3aecf8198bd9 Mon Sep 17 00:00:00 2001 From: Eric Wheeler Date: Thu, 10 Apr 2025 18:23:41 -0700 Subject: [PATCH 4/4] 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 --- cline_docs/settings.md | 105 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 102 insertions(+), 3 deletions(-) diff --git a/cline_docs/settings.md b/cline_docs/settings.md index 5d303cadf52..ce69076416c 100644 --- a/cline_docs/settings.md +++ b/cline_docs/settings.md @@ -240,6 +240,105 @@ To add a new configuration item to the system, the following changes are necessa - Add test cases for the new settings in appropriate test files - Verify settings persistence and state updates -10. **Avoiding Duplicates** - - Be careful to avoid duplicate handlers or UI components when adding new settings - - Check for existing similar settings to maintain consistent patterns +10. **Ensuring Settings Persistence Across Reload** + + To ensure settings persist across application reload, several key components must be properly configured: + + 1. **Initial State in ExtensionStateContextProvider**: + + - Add the setting to the initial state in the useState call + - Example: + ```typescript + const [state, setState] = useState({ + // existing settings... + newSetting: false, // Default value for the new setting + }) + ``` + + 2. **State Loading in ClineProvider**: + + - Add the setting to the getState method to load it from storage + - Example: + ```typescript + return { + // existing settings... + newSetting: stateValues.newSetting ?? false, + } + ``` + + 3. **State Initialization in resolveWebviewView**: + + - Add the setting to the initialization in resolveWebviewView + - Example: + ```typescript + this.getState().then( + ({ + // existing settings... + newSetting, + }) => { + // Initialize the setting with its stored value or default + FeatureClass.setNewSetting(newSetting ?? false) + }, + ) + ``` + + 4. **State Transmission to Webview**: + + - Add the setting to the getStateToPostToWebview method + - Example: + ```typescript + return { + // existing settings... + newSetting: newSetting ?? false, + } + ``` + + 5. **Setter Method in ExtensionStateContext**: + - Add the setter method to the contextValue object + - Example: + ```typescript + const contextValue: ExtensionStateContextType = { + // existing properties and methods... + setNewSetting: (value) => setState((prevState) => ({ ...prevState, newSetting: value })), + } + ``` + +11. **Debugging Settings Persistence Issues** + + If a setting is not persisting across reload, check the following: + + 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 + + 2. **Default Values Consistency**: + + - Ensure default values are consistent across all locations + - Inconsistent defaults can cause unexpected behavior + + 3. **Message Handling**: + + - Confirm the webviewMessageHandler.ts has a case for the setting + - Verify the message type matches what's sent from the UI + + 4. **UI Integration**: + + - Check that the setting is included in the handleSubmit function in SettingsView.tsx + - Ensure the UI component correctly updates the state + + 5. **Type Definitions**: + + - 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 + + These checks help identify and resolve common issues with settings persistence.