Add troubleshooting and best-practices guides for VSCode extension #331 & #332

docs/guides/best-practices-vscode.md

@@ -0,0 +1,80 @@
+---
+title: Best practices for using the VSCode extension
+description: Recommended ways to get the most out of CodeRabbit's VSCode extension.
+---
+
+Maximize your productivity and code quality with these best practices for the CodeRabbit VSCode extension. For setup instructions, see [Install the VSCode extension](/guides/install-vscode). To get started, visit [Use the VSCode extension](/guides/use-vscode).
+
+## Recommended setup
+
+- **Set a default comparison branch**  
+  Choose your main development branch (e.g., `main`, `develop`, or trunk) as the default for reviews. This ensures consistent and relevant diffs.  
+  → Use `CodeRabbit: Base Branch` in the Command Palette.
+
+- **Enable auto-reviews on commit**  
+  Let CodeRabbit automatically review your code after each commit to catch issues early and maintain momentum.  
+  → Toggle `CodeRabbit: Auto Review on Commit` in extension settings.
+
+- **Pin CodeRabbit to the sidebar**  
+  Keep the CodeRabbit icon visible in the activity bar for instant access to reviews and history.
+
+- **Keep Git in sync**  
+  Regularly fetch and rebase or merge from your base branch. This keeps your diffs clean and prevents unnecessary noise in reviews.
+
+---
+
+## Daily workflow tips
+
+### 1. Commit often, review often
+
+Make small, frequent commits. CodeRabbit can review incremental changes, helping you spot issues early and keep reviews manageable.
+
+### 2. Use manual reviews for partial code
+
+For work-in-progress or uncommitted changes, use `CodeRabbit: Review Selected Files` or `Review Current Changes`. This is ideal for exploratory or experimental work.
+
+### 3. Follow up on comments
+
+Always address CodeRabbit’s suggestions. Even if you disagree, double-check the feedback. Use comments as a checklist before pushing to remote.
+
+### 4. Re-review after refactoring
+
+After significant changes or refactoring, run `Review Current Branch` again to validate new logic and catch regressions.
+
+---
+
+## Performance tips
+
+- **Avoid large, monolithic commits**  
+  Break up big changes into logical units. This speeds up reviews and improves feedback accuracy.
+
+- **Close unused VSCode windows**  
+  Running multiple VSCode instances with the extension can impact performance.
+
+- **Use `.coderabbitignore`**  
+  Exclude files or directories you don’t want reviewed to reduce clutter and speed up analysis.
+
+---
+
+## Team collaboration tips
+
+- **Share `.vscode/settings.json`**  
+  Align CodeRabbit settings (like base branch and ignored paths) across your team for consistency.
+
+- **Document your CodeRabbit workflow**  
+  Add a section to your project README outlining when to run reviews, what to check, and how to handle feedback.
+
+- **Integrate with CI**  
+  Use CodeRabbit both locally and in your CI pipeline for consistent, automated code reviews.
+
+---
+
+## Keep your tools updated
+
+- Regularly update the CodeRabbit extension for the latest features and fixes.
+- Keep VSCode and Git up to date for best compatibility.
+- Watch the [CodeRabbit GitHub repo](https://github.com/coderabbitai/coderabbit-vscode) for release notes and updates.
+
+---
+
+By following these practices, you’ll catch bugs earlier, streamline your workflow, and write more reliable code with confidence.

docs/guides/troubleshooting-vscode.md

@@ -0,0 +1,95 @@
+---
+title: Troubleshoot the VSCode extension
+description: Fix issues with CodeRabbit reviews in VSCode.
+---
+
+This guide will help you quickly resolve common problems with the CodeRabbit VSCode extension for local code reviews. If you haven’t set up the extension yet, see [Install the VSCode extension](/guides/install-vscode). For everyday usage tips, check [Use the VSCode extension](/guides/use-vscode).
+
+## Common issues and solutions
+
+### 1. The extension isn't activating
+
+#### Symptoms
+
+- No CodeRabbit icon in the sidebar
+- No reviews appear
+- "CodeRabbit" missing from the Command Palette
+
+#### How to fix
+
+- Confirm the extension is installed and enabled in VSCode.
+- Reload the VSCode window (`Cmd/Ctrl + Shift + P` → “Reload Window”).
+- Ensure your workspace is a valid Git repository; CodeRabbit requires Git context to activate.
+
+---
+
+### 2. Reviews aren't triggered on commit
+
+#### Symptoms
+
+- Committing changes does not trigger a review
+- No output or errors are shown
+
+#### How to fix
+
+- Open the Command Palette and run `CodeRabbit: Review latest commit` to test manually.
+- Check that "Auto Review on Commit" is enabled in the extension settings.
+- Verify the comparison branch (e.g., `main`, `develop`) is set correctly.
+- Restart VSCode to reset event listeners if needed.
+
+---
+
+### 3. Error: “Failed to compare branches”
+
+#### Symptoms
+
+- Error message in Output or CodeRabbit panel
+- No diff is displayed
+
+#### How to fix
+
+- Ensure the comparison branch exists locally. Run `git fetch` to update references.
+- Confirm your current branch has diverged commits from the comparison branch.
+- Set the correct base branch in CodeRabbit settings:  
+  `CodeRabbit: Base Branch` → set to `main` or another relevant branch.
+
+---
+
+### 4. Review results are incorrect or missing files
+
+#### Symptoms
+
+- Some changes are missing from the review
+- Comments appear on incorrect lines or files
+
+#### How to fix
+
+- Make sure all changes are staged and committed; unstaged changes may be ignored.
+- Check your Git client settings for line-ending conversions or whitespace trimming, which can affect diffs.
+- Reload VSCode or run a fresh diff to force a new comparison.
+
+---
+
+### 5. The extension crashes or becomes unresponsive
+
+#### Symptoms
+
+- VSCode freezes or slows down
+- CodeRabbit UI is unresponsive
+
+#### How to fix
+
+- Open the Output panel (`View > Output`) and select `CodeRabbit` from the dropdown to check for error logs.
+- Disable other extensions that might conflict, such as custom Git diff viewers.
+- Report persistent issues on the [CodeRabbit GitHub repository](https://github.com/coderabbitai/coderabbit-vscode/issues).
+
+---
+
+## Additional help
+
+If you’re still experiencing issues, try:
+
+- Restarting VSCode or your computer
+- Updating VSCode and the CodeRabbit extension
+- Reinstalling the extension
+- Checking the [FAQs](/faq) or contacting [support](mailto:support@coderabbit.ai)

sidebars.ts

@@ -128,6 +128,8 @@ const sidebars: SidebarsConfig = {
 				"guides/install-vscode",
 				"guides/use-vscode",
 				"guides/config-vscode",
+				"guides/best-practices-vscode",
+				"guides/troubleshooting-vscode",
 				"guides/uninstall-vscode",
 			],
 		},