From 67a60829e67b27637fe8f43ccfcb339068bbe472 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: Add WSL rebuild steps.

Previously, the rebuild steps for WSL in the recommended setup guide
incorrectly just included the Vagrant instructions.

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 database,
which is a much faster alternative for folks who just want that.

Fixes #32402.
---
 docs/development/setup-recommended.md |  2 +-
 docs/development/setup/wsl-rebuild.md | 42 +++++++++++++++++++++++++++
 2 files changed, 43 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..4aaad0ffde
--- /dev/null
+++ b/docs/development/setup/wsl-rebuild.md
@@ -0,0 +1,42 @@
+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 your development environment 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)
+
+If you just want to rebuild the development database, the following is
+much faster:
+
+```console
+$ ./tools/rebuild-dev-database
+```
+
+For more details, see the [schema migration
+documentation](/subsystems/schema-migrations.md#schema-and-initial-data-changes).