docs: Fix development environment setup on Windows.

Windows users end up having to follow an odd chain of links because
the recommended installation instructions live on a different
page than the rest of the instructions about the environment setup.

All the tutorials about recommended install prerequisites for each
platform should be on the same page.

This moves the section about using WSL 2 from the advanced setup page
to the recommended environment setup tutorial page.

Renames sidebar and section titles to more accurately reflect the
information in the Recommended setup vs. the Advanced setup page.
Updates relevant text and links accordingly.

Fixes: #13696.

docs/development/index.md

@@ -6,8 +6,8 @@ maxdepth: 3
 ---
 
 Development environment installation <overview>
-Recommended setup (Vagrant) <setup-vagrant>
+Recommended setup <setup-vagrant>
-Advanced setup (non-Vagrant) <setup-advanced>
+Advanced setup <setup-advanced>
 Using the development environment <using>
 Developing remotely <remote>
 Authentication in the development environment <authentication>

docs/development/overview.md

@@ -84,4 +84,4 @@ machine, take a look at our tips for
 [using-dev-env]: using.md
 [testing]: ../testing/testing.md
 [ci]: ../git/cloning.md#step-3-configure-continuous-integration-for-your-fork
-[install-via-wsl]: setup-advanced.md#installing-directly-on-windows-10-with-wsl-2
+[install-via-wsl]: setup-vagrant.md#windows-10

docs/development/setup-advanced.md

@@ -3,7 +3,7 @@
 Contents:
 
 - [Installing directly on Ubuntu, Debian, CentOS, or Fedora](#installing-directly-on-ubuntu-debian-centos-or-fedora)
-- [Installing directly on Windows 10 with WSL 2](#installing-directly-on-windows-10-with-wsl-2)
+- [Installing using Vagrant with VirtualBox on Windows 10](#installing-using-vagrant-with-virtualbox-on-windows-10)
 - [Using the Vagrant Hyper-V provider on Windows](#using-the-vagrant-hyper-v-provider-on-windows-beta)
 - [Newer versions of supported platforms](#newer-versions-of-supported-platforms)
 
@@ -53,112 +53,91 @@ on using the Zulip development
 environment](setup-vagrant.md#step-4-developing),
 ignoring the parts about `vagrant` (since you're not using it).
 
-## Installing directly on Windows 10 with WSL 2
+## Installing using Vagrant with VirtualBox on Windows 10
 
-Zulip's development environment is most easily set up on Windows using
+:::{note}
-the Windows Subsystem for Linux ([WSL
+We recommend using [WSL 2 for Windows development](setup-vagrant.md#windows-10)
-2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-about))
+because it is easier to set up and provides a substantially better experience.
-installation method described here.
+:::
 
-1. Enable virtualization through your BIOS settings. This sequence
+1. Install [Git for Windows][git-bash], which installs _Git BASH_.
-   depends on your specific hardware and brand, but here are [some
+2. Install [VirtualBox][vbox-dl] (latest).
-   basic instructions.][windows-bios-virtualization]
+3. Install [Vagrant][vagrant-dl] (latest).
 
-1. [Install WSL 2](https://docs.microsoft.com/en-us/windows/wsl/setup/environment).
+(Note: While _Git BASH_ is recommended, you may also use [Cygwin][cygwin-dl].
+If you do, make sure to **install default required packages** along with
+**git**, **curl**, **openssh**, and **rsync** binaries.)
 
-1. Launch the Ubuntu shell as an administrator and run the following command:
+Also, you must have hardware virtualization enabled (VT-x or AMD-V) in your
+computer's BIOS.
 
-   ```bash
+#### Running Git BASH as an administrator
-   sudo apt update && sudo apt upgrade
-   ```
 
-1. Install dependencies with the following command:
+It is important that you **always run Git BASH with administrator
+privileges** when working on Zulip code, as not doing so will cause
+errors in the development environment (such as symlink creation). You
+might wish to configure your Git BASH shortcut to always run with
+these privileges enabled (see this [guide][bash-admin-setup] for how
+to set this up).
 
-   ```bash
+##### Enable native symlinks
-   sudo apt install rabbitmq-server memcached redis-server postgresql
-   ```
 
-1. Open `/etc/rabbitmq/rabbitmq-env.conf` using e.g.:
+The Zulip code includes symbolic links (symlinks). By default, native Windows
+symlinks are not enabled in either Git BASH or Cygwin, so you need to do a bit
+of configuration. **You must do this before you clone the Zulip code.**
 
-   ```bash
+In **Git for BASH**:
-   sudo nano /etc/rabbitmq/rabbitmq-env.conf
-   ```
 
-   Confirm the following lines are at the end of your file, and add
+Open **Git BASH as an administrator** and run:
-   them if not present. Then save your changes (`Ctrl+O`, then `Enter`
-   to confirm the path), and exit `nano` (`Ctrl+X`).
 
-   ```ini
+```console
-   NODE_IP_ADDRESS=127.0.0.1
+$ git config --global core.symlinks true
-   NODE_PORT=5672
+```
-   ```
 
-1. Run the command below to make sure you are inside the WSL disk and not in a Windows mounted disk.
+Now confirm the setting:
-   You will run into permission issues if you run `provision` from `zulip`
-   in a Windows mounted disk.
 
-   ```bash
+```console
-   cd ~  # or cd /home/USERNAME
+$ git config core.symlinks
-   ```
+true
+```
 
-1. [Create your fork](../git/cloning.md#step-1a-create-your-fork) of
+If you see `true`, you are ready for [Step 2: Get Zulip code](setup-vagrant.md#step-2-get-zulip-code).
-   the [Zulip server repository](https://github.com/zulip/zulip).
 
-1. [Create a new SSH key][create-ssh-key] for the WSL-2 Virtual
+Otherwise, if the above command prints `false` or nothing at all, then symlinks
-   Machine and add it to your GitHub account. Note that SSH keys
+have not been enabled.
-   linked to your Windows computer will not work within the virtual
-   machine.
 
-1. Clone and connect to the Zulip upstream repository:
+In **Cygwin**:
 
-   ```bash
+Open a Cygwin window **as an administrator** and do this:
-   git clone --config pull.rebase git@github.com:YOURUSERNAME/zulip.git ~/zulip
-   cd zulip
-   git remote add -f upstream https://github.com/zulip/zulip.git
-   ```
 
-1. Run the following to install the Zulip development environment and
+```console
-   start it. (If Windows Firewall creates popups to block services, simply click `Allow Access`.)
+christie@win10 ~
+$ echo 'export "CYGWIN=$CYGWIN winsymlinks:native"' >> ~/.bash_profile
+```
 
-   ```bash
+Next, close that Cygwin window and open another. If you `echo` $CYGWIN you
-   # Start database, cache, and other services
+should see:
-   ./tools/wsl/start_services
-   # Install/update the Zulip development environment
-   ./tools/provision
-   # Enter the Zulip Python environment
-   source /srv/zulip-py3-venv/bin/activate
-   # Start the development server
-   ./tools/run-dev.py
-   ```
 
-   :::{note}
+```console
-   If you shut down WSL, after starting it again, you will have to manually start
+christie@win10 ~
-   the services using `./tools/wsl/start_services`.
+$ echo $CYGWIN
-   :::
+winsymlinks:native
+```
 
-1. If you are facing problems or you see error messages after running `./tools/run-dev.py`,
+Now you are ready for [Step 2: Get Zulip code](setup-vagrant.md#step-2-get-zulip-code).
-   you can try running `./tools/provision` again.
 
-1. The [Visual Studio Code Remote -
+(Note: The **GitHub Desktop client** for Windows has a bug where it
-   WSL](https://code.visualstudio.com/docs/remote/wsl) extension is
+will automatically set `git config core.symlink false` on a repository
-   recommended for editing files when developing with WSL. When you
+if you use it to clone a repository, which will break the Zulip
-   have it installed, you can run:
+development environment, because we use symbolic links. For that
+reason, we recommend avoiding using GitHub Desktop client to clone
+projects and to instead follow these instructions exactly.)
 
-   ```bash
+[cygwin-dl]: https://cygwin.com
-   code .
+[git-bash]: https://git-for-windows.github.io
-   ```
+[vbox-dl]: https://www.virtualbox.org/wiki/Downloads
-
+[vagrant-dl]: https://www.vagrantup.com/downloads.html
-   to open VSCode connected to your WSL environment.
+[bash-admin-setup]: https://superuser.com/questions/1002262/run-applications-as-administrator-by-default-in-windows-10
-
-1. You're done! You can pick up the [documentation on using the
-   Zulip development environment](setup-vagrant.md#step-4-developing),
-   ignoring the parts about `vagrant` (since you're not using it).
-
-WSL 2 can be uninstalled by following [Microsoft's documentation][uninstall-wsl]
-
-[create-ssh-key]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account
-[uninstall-wsl]: https://docs.microsoft.com/en-us/windows/wsl/faq#how-do-i-uninstall-a-wsl-distribution-
-[windows-bios-virtualization]: https://www.thewindowsclub.com/disable-hardware-virtualization-in-windows-10
 
 ## Using the Vagrant Hyper-V provider on Windows (beta)
 

docs/development/setup-vagrant.md

@@ -1,13 +1,13 @@
-## Vagrant environment setup tutorial
+## Recommended environment setup tutorial
 
 This section guides first-time contributors through installing the
 Zulip development environment on Windows, macOS, and Linux.
 
-The recommended method for installing the Zulip development environment is to use
+The recommended method for installing the Zulip development environment is
-Vagrant with VirtualBox on Windows, and Vagrant with Docker on
+to use WSL 2 on Windows, and Vagrant with Docker on macOS and Linux.
-macOS and Linux. This method creates a virtual machine (for Windows)
+This methoduses the Windows Subsystem for Linux or creates a Linux container
-or a Linux container (for macOS and Linux) inside which the Zulip server and
+(for macOS and Linux) inside which the Zulip server and all related
-all related services will run.
+services will run.
 
 Contents:
 
@@ -47,7 +47,8 @@ an active internet connection throughout the entire installation
 processes. (See [Specifying a proxy](#specifying-a-proxy) if you need
 a proxy to access the internet.)
 
-- **All**: 2GB available RAM, Active broadband internet connection, [GitHub account][set-up-git].
+- **All**: 2GB available RAM, Active broadband internet connection,
+  [GitHub account](#step-0-set-up-git--github).
 - **macOS**: macOS (10.11 El Capitan or newer recommended)
 - **Ubuntu LTS**: 20.04 or 22.04
 - **Debian**: 11
@@ -158,83 +159,109 @@ docker distribution, you can follow
 
 #### Windows 10
 
-:::{note}
+Zulip's development environment is most easily set up on Windows using
-We recommend using [WSL 2 for Windows development](setup-advanced.md#installing-directly-on-windows-10-with-wsl-2).
+the Windows Subsystem for Linux ([WSL
-:::
+2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-about))
+installation method described here.
 
-1. Install [Git for Windows][git-bash], which installs _Git BASH_.
+1. Enable virtualization through your BIOS settings. This sequence
-2. Install [VirtualBox][vbox-dl] (latest).
+   depends on your specific hardware and brand, but here are [some
-3. Install [Vagrant][vagrant-dl] (latest).
+   basic instructions.][windows-bios-virtualization]
 
-(Note: While _Git BASH_ is recommended, you may also use [Cygwin][cygwin-dl].
+1. [Install WSL 2](https://docs.microsoft.com/en-us/windows/wsl/setup/environment).
-If you do, make sure to **install default required packages** along with
-**git**, **curl**, **openssh**, and **rsync** binaries.)
 
-Also, you must have hardware virtualization enabled (VT-x or AMD-V) in your
+1. Launch the Ubuntu shell as an administrator and run the following command:
-computer's BIOS.
 
-#### Running Git BASH as an administrator
+   ```bash
+   sudo apt update && sudo apt upgrade
+   ```
 
-It is important that you **always run Git BASH with administrator
+1. Install dependencies with the following command:
-privileges** when working on Zulip code, as not doing so will cause
-errors in the development environment (such as symlink creation). You
-might wish to configure your Git BASH shortcut to always run with
-these privileges enabled (see this [guide][bash-admin-setup] for how
-to set this up).
 
-##### Enable native symlinks
+   ```bash
+   sudo apt install rabbitmq-server memcached redis-server postgresql
+   ```
 
-The Zulip code includes symbolic links (symlinks). By default, native Windows
+1. Open `/etc/rabbitmq/rabbitmq-env.conf` using e.g.:
-symlinks are not enabled in either Git BASH or Cygwin, so you need to do a bit
-of configuration. **You must do this before you clone the Zulip code.**
 
-In **Git for BASH**:
+   ```bash
+   sudo nano /etc/rabbitmq/rabbitmq-env.conf
+   ```
 
-Open **Git BASH as an administrator** and run:
+   Confirm the following lines are at the end of your file, and add
+   them if not present. Then save your changes (`Ctrl+O`, then `Enter`
+   to confirm the path), and exit `nano` (`Ctrl+X`).
 
-```console
+   ```ini
-$ git config --global core.symlinks true
+   NODE_IP_ADDRESS=127.0.0.1
-```
+   NODE_PORT=5672
+   ```
 
-Now confirm the setting:
+1. Run the command below to make sure you are inside the WSL disk and not
+   in a Windows mounted disk. You will run into permission issues if you
+   run `provision` from `zulip` in a Windows mounted disk.
 
-```console
+   ```bash
-$ git config core.symlinks
+   cd ~  # or cd /home/USERNAME
-true
+   ```
-```
 
-If you see `true`, you are ready for [Step 2: Get Zulip
+1. [Create your fork](../git/cloning.md#step-1a-create-your-fork) of
-code](#step-2-get-zulip-code).
+   the [Zulip server repository](https://github.com/zulip/zulip).
 
-Otherwise, if the above command prints `false` or nothing at all, then symlinks
+1. [Create a new SSH key][create-ssh-key] for the WSL-2 Virtual
-have not been enabled.
+   Machine and add it to your GitHub account. Note that SSH keys
+   linked to your Windows computer will not work within the virtual
+   machine.
 
-In **Cygwin**:
+1. Clone and connect to the Zulip upstream repository:
 
-Open a Cygwin window **as an administrator** and do this:
+   ```bash
+   git clone --config pull.rebase git@github.com:YOURUSERNAME/zulip.git ~/zulip
+   cd zulip
+   git remote add -f upstream https://github.com/zulip/zulip.git
+   ```
 
-```console
+1. Run the following to install the Zulip development environment and
-christie@win10 ~
+   start it. (If Windows Firewall creates popups to block services, simply click `Allow Access`.)
-$ echo 'export "CYGWIN=$CYGWIN winsymlinks:native"' >> ~/.bash_profile
-```
 
-Next, close that Cygwin window and open another. If you `echo` $CYGWIN you
+   ```bash
-should see:
+   # Start database, cache, and other services
+   ./tools/wsl/start_services
+   # Install/update the Zulip development environment
+   ./tools/provision
+   # Enter the Zulip Python environment
+   source /srv/zulip-py3-venv/bin/activate
+   # Start the development server
+   ./tools/run-dev.py
+   ```
 
-```console
+   :::{note}
-christie@win10 ~
+   If you shut down WSL, after starting it again, you will have to manually start
-$ echo $CYGWIN
+   the services using `./tools/wsl/start_services`.
-winsymlinks:native
+   :::
-```
 
-Now you are ready for [Step 2: Get Zulip code](#step-2-get-zulip-code).
+1. If you are facing problems or you see error messages after running `./tools/run-dev.py`,
+   you can try running `./tools/provision` again.
 
-(Note: The **GitHub Desktop client** for Windows has a bug where it
+1. The [Visual Studio Code Remote -
-will automatically set `git config core.symlink false` on a repository
+   WSL](https://code.visualstudio.com/docs/remote/wsl) extension is
-if you use it to clone a repository, which will break the Zulip
+   recommended for editing files when developing with WSL. When you
-development environment, because we use symbolic links. For that
+   have it installed, you can run:
-reason, we recommend avoiding using GitHub Desktop client to clone
+
-projects and to instead follow these instructions exactly.)
+   ```bash
+   code .
+   ```
+
+   to open VSCode connected to your WSL environment.
+
+1. You're done! Now you're ready for [Step 4: Developing](#step-4-developing),
+   ignoring the parts about `vagrant` (since you're not using it).
+
+WSL 2 can be uninstalled by following [Microsoft's documentation][uninstall-wsl]
+
+[create-ssh-key]: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account
+[uninstall-wsl]: https://docs.microsoft.com/en-us/windows/wsl/faq#how-do-i-uninstall-a-wsl-distribution-
+[windows-bios-virtualization]: https://www.thewindowsclub.com/disable-hardware-virtualization-in-windows-10
 
 ### Step 2: Get Zulip code
 
@@ -1046,15 +1073,11 @@ If at any time you wish to revert back to the default settings, simply
 remove the `GUEST_CPUS` and `GUEST_MEMORY_MB` lines from
 `~/.zulip-vagrant-config`.
 
-[cygwin-dl]: https://cygwin.com/
 [vagrant-dl]: https://www.vagrantup.com/downloads.html
-[vbox-dl]: https://www.virtualbox.org/wiki/Downloads
 [install-advanced]: setup-advanced.md
 [rtd-git-guide]: ../git/index.md
 [rtd-testing]: ../testing/testing.md
 [rtd-using-dev-env]: using.md
 [rtd-dev-remote]: remote.md
-[git-bash]: https://git-for-windows.github.io/
-[bash-admin-setup]: https://superuser.com/questions/1002262/run-applications-as-administrator-by-default-in-windows-10
 [set-up-git]: ../git/setup.md
 [ci]: ../git/cloning.md#step-3-configure-continuous-integration-for-your-fork

docs/git/cloning.md

@@ -99,6 +99,9 @@ If you haven't already, now is a good time to install the Zulip development envi
 source projects in general, we recommend following our [detailed guide for
 first-time contributors][zulip-rtd-dev-first-time].
 
+If you are in the middle of installing the recommended setup on Windows 10,
+you are ready to [continue with step 8](../development/setup-vagrant.md#windows-10).
+
 ## Step 3: Configure continuous integration for your fork
 
 This step is optional, but recommended.

docs/git/setup.md

@@ -8,8 +8,9 @@ can skip this section. Otherwise, read on!
 If you're not already using Git, you might need to [install][gitbook-install]
 and [configure][gitbook-setup] it.
 
-**If you are using Windows 10, make sure you [are running Git BASH as an
+**If you are using Windows 10 without [WSL
-administrator][git-bash-admin] at all times.**
+2](https://docs.microsoft.com/en-us/windows/wsl/wsl2-about), make sure you
+[are running Git BASH as an administrator][git-bash-admin] at all times.**
 
 You'll also need a GitHub account, which you can sign up for
 [here][github-join].
@@ -29,6 +30,9 @@ We also highly recommend the following:
 - Install the command auto-completion and/or git-prompt plugins available for
   [Bash][gitbook-other-envs-bash] and [Zsh][gitbook-other-envs-zsh].
 
+If you are installing the Zulip development environment, now you are ready to
+continue with [Step 1: Install prerequisites](../development/setup-vagrant.md#step-1-install-prerequisites).
+
 ## Get a graphical client
 
 Even if you're comfortable using Git on the command line, having a graphical
@@ -49,7 +53,7 @@ text-mode interface to Git.
 
 And, if none of the above are to your liking, try [one of these][gitbook-guis].
 
-[git-bash-admin]: ../development/setup-vagrant.md#running-git-bash-as-an-administrator
+[git-bash-admin]: ../development/setup-advanced.md#running-git-bash-as-an-administrator
 [gitbook-aliases]: https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases
 [gitbook-config]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration
 [gitbook-guis]: https://git-scm.com/downloads/guis