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]>

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,12 +72,35 @@
         ```
 
 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 })
         ```
 
+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
+        <div>
+          <VSCodeCheckbox
+            checked={terminalPowershellCounter ?? true}
+            onChange={(e: any) => setCachedStateField("terminalPowershellCounter", e.target.checked)}
+            data-testid="terminal-powershell-counter-checkbox">
+            <span className="font-medium">{t("settings:terminal.powershellCounter.label")}</span>
+          </VSCodeCheckbox>
+          <div className="text-vscode-descriptionForeground text-sm mt-1">
+            {t("settings:terminal.powershellCounter.description")}
+          </div>
+        </div>
+        ```
+
 ## For Select/Dropdown Settings
 
 1. Add the message type to WebviewMessage.ts:
@@ -98,6 +129,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
@@ -146,3 +178,167 @@ 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. **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<ExtensionState>({
+            	// 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.