From db6fbd5c32c0dfcdc6a613b8f601834b580ef716 Mon Sep 17 00:00:00 2001
From: Apoorva Pendse <apoorvavpendse@gmail.com>
Date: Thu, 21 Nov 2024 07:47:24 +0530
Subject: [PATCH] docs: Correct WSL rebuild steps in guide

Previously, the rebuild steps for WSL in the recommended setup guide
mentioned destroying the Vagrant instance, which was not relevant
to WSL and had no mention earlier in the documentation.

This commit fixes the issue by adding the appropriate steps to delete
the WSL instance using `wsl --unregister` in the docs.

Additionally, it includes steps to rebuild the development and test
databases for convenience.

Fixes #32402
---
 docs/development/setup-recommended.md |  2 +-
 docs/development/setup/wsl-rebuild.md | 39 +++++++++++++++++++++++++++
 2 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 docs/development/setup/wsl-rebuild.md

diff --git a/docs/development/setup-recommended.md b/docs/development/setup-recommended.md
index 87536b465d..60503e7cf9 100644
--- a/docs/development/setup-recommended.md
+++ b/docs/development/setup-recommended.md
@@ -552,7 +552,7 @@ help.
 :::{tab-item} Windows (WSL)
 :sync: os-windows
 
-```{include} setup/vagrant-rebuild.md
+```{include} setup/wsl-rebuild.md
 
 ```
 
diff --git a/docs/development/setup/wsl-rebuild.md b/docs/development/setup/wsl-rebuild.md
new file mode 100644
index 0000000000..279660c67a
--- /dev/null
+++ b/docs/development/setup/wsl-rebuild.md
@@ -0,0 +1,39 @@
+If you ever want to recreate your development environment again from
+scratch (e.g., to test a change you've made to the provisioning
+process, or because you think something is broken), you can do so using the following steps:
+
+1. To find the distribution name to unregister(delete), open Command Prompt or PowerShell and use the following command:
+
+```console
+$ wsl --list --verbose
+```
+
+If you are unsure about which distribution to unregister, you can log into the WSL distributions to ensure you are deleting the one containing Zulip using the command:
+
+```console
+wsl -d <Distribution Name>
+```
+
+2. To uninstall your WSL distribution, enter the command:
+
+```console
+$ wsl --unregister <Distribution Name>
+```
+
+For more information, checkout the [official documentation for WSL commands](https://learn.microsoft.com/en-us/windows/wsl/basic-commands#unregister-or-uninstall-a-linux-distribution)
+
+3. **Next, follow the setup instructions**, starting from [[Step 1: Install prerequisites]](/development/setup-recommended.md#step-1-install-prerequisites)
+
+Additionally, if you would only like to rebuild the dev database, you can use:
+
+```console
+$ ./tools/rebuild-dev-database
+```
+
+To rebuild the database used in automated testing:
+
+```
+$ ./tools/rebuild-test-database
+```
+
+For more details checkout our [schema migration documentation](/subsystems/schema-migrations.md#schema-and-initial-data-changes)