docs: Upgrade development environment page to use synced tabs.

This greatly reduces how much content for other platforms a reader has
to scroll past in order to get the development environment set up.

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-recommended.md#windows-10-or-11
+[install-via-wsl]: setup-recommended.md

docs/development/setup-advanced.md

@@ -66,7 +66,7 @@ ignoring the parts about `vagrant` (since you're not using it).
 ## Installing using Vagrant with VirtualBox on Windows 10
 
 :::{note}
-We recommend using [WSL 2 for Windows development](setup-recommended.md#windows-10-or-11)
+We recommend using [WSL 2 for Windows development](setup-recommended.md)
 because it is easier to set up and provides a substantially better experience.
 :::
 

docs/development/setup-recommended.md

@@ -41,20 +41,47 @@ When reporting your issue, please include the following information:
 
 ### Requirements
 
-Installing the Zulip development environment with Vagrant requires
-downloading several hundred megabytes of dependencies. You will need
-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.)
+Installing the Zulip development environment requires downloading several
+hundred megabytes of dependencies. You will need 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](#step-0-set-up-git--github).
-- **macOS**: macOS (10.11 El Capitan or newer recommended)
-- **Ubuntu LTS**: 20.04, 22.04, or 24.04
-- **Debian**: 11 or 12
-- **Fedora**: tested for 36
-- **Windows**: Windows 64-bit (Windows 10 recommended), hardware
-  virtualization enabled (VT-x or AMD-V), administrator access.
+- 2GB available RAM
+- active broadband internet connection
+- [GitHub account](#step-0-set-up-git--github)
+
+::::{tab-set}
+
+:::{tab-item} Windows
+:sync: os-windows
+:name: windows-10-or-11
+
+- Windows 64-bit (Windows 10 recommended)
+- hardware virtualization enabled (VT-x or AMD-V)
+- administrator access
+  :::
+
+:::{tab-item} macOS
+:sync: os-mac
+
+- macOS (10.11 El Capitan or newer recommended)
+  :::
+
+:::{tab-item} Ubuntu/Debian
+:sync: os-ubuntu
+
+- Ubuntu 20.04, 22.04, or 24.04
+- Debian 11 or 12
+  :::
+
+:::{tab-item} Fedora
+:sync: os-fedora
+
+- tested for Fedora 36
+  :::
+
+::::
 
 Other Linux distributions work great too, but we don't maintain
 documentation for installing Vagrant and Docker on those systems, so
@@ -73,50 +100,10 @@ GitHub account using
 
 ### Step 1: Install prerequisites
 
-Jump to:
+::::{tab-set}
 
-- [macOS](#macos)
-- [Ubuntu](#ubuntu)
-- [Debian](#debian)
-- [Fedora](#fedora)
-- [Windows](#windows-10-or-11)
-
-#### macOS
-
-1. Install [Vagrant][vagrant-dl] (latest).
-2. Install [Docker Desktop](https://docs.docker.com/desktop/mac/install/) (latest).
-
-Now you are ready for [Step 2: Get Zulip code](#step-2-get-zulip-code).
-
-#### Ubuntu
-
-##### 1. Install Vagrant, Docker, and Git
-
-```console
-$ sudo apt install vagrant docker.io git
-```
-
-```{include} setup/install-docker.md
-
-```
-
-Now you are ready for [Step 2: Get Zulip code](#step-2-get-zulip-code).
-
-#### Debian
-
-The setup for Debian is the same as that [for Ubuntu above](#ubuntu).
-
-#### Fedora
-
-The setup for Fedora is mostly equivalent to the [setup for Ubuntu](#ubuntu).
-The only difference is the installation of Docker. Fedora does not include the
-official `docker-ce` package (named `docker.io` in the
-[setup for Ubuntu](#ubuntu)) in their repositories. They provide the package
-`moby-engine` which you can choose instead. In case you prefer the official
-docker distribution, you can follow
-[their documentation to install Docker on Fedora](https://docs.docker.com/engine/install/fedora/).
-
-#### Windows 10 or 11
+:::{tab-item} Windows
+:sync: os-windows
 
 Zulip's development environment is most easily set up on Windows using
 the Windows Subsystem for Linux ([WSL
@@ -152,14 +139,16 @@ installation method described here. We require version 0.67.6+ of WSL 2.
    ```
 
    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`).
+   them if not present:
 
    ```ini
    NODE_IP_ADDRESS=127.0.0.1
    NODE_PORT=5672
    ```
 
+   Then save your changes (`Ctrl+O`, then `Enter` to confirm the path),
+   and exit `nano` (`Ctrl+X`).
+
 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 `./tools/provision` from `zulip` in a Windows mounted disk.
@@ -168,58 +157,64 @@ installation method described here. We require version 0.67.6+ of WSL 2.
    $ cd ~  # or cd /home/USERNAME
    ```
 
-1. [Create your fork](../git/cloning.md#step-1a-create-your-fork) of
-   the [Zulip server repository](https://github.com/zulip/zulip).
-
 1. [Create a new SSH key][create-ssh-key] for the WSL 2 virtual
    machine and add it to your GitHub account. Note that SSH keys
    linked to your Windows computer will not work within the virtual
    machine.
 
-1. Clone and connect to the Zulip upstream repository:
-
-   ```console
-   $ 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
-   start it. (If Windows Firewall creates popups to block services,
-   simply click **Allow access**.)
-
-   ```console
-   $ # 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
-   ```
-
-1. If you are facing problems or you see error messages after running `./tools/run-dev`,
-   you can try running `./tools/provision` again.
-
-1. The [Visual Studio Code Remote -
-   WSL](https://code.visualstudio.com/docs/remote/wsl) extension is
-   recommended for editing files when developing with WSL. When you
-   have it installed, you can run:
-
-   ```console
-   $ code .
-   ```
-
-   to open VS Code 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-
+[uninstall-wsl]: https://learn.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
 
+:::
+
+:::{tab-item} macOS
+:sync: os-mac
+
+1. Install [Vagrant][vagrant-dl] (latest).
+2. Install [Docker Desktop](https://docs.docker.com/desktop/mac/install/) (latest).
+   :::
+
+:::{tab-item} Ubuntu/Debian
+:sync: os-ubuntu
+
+##### 1. Install Vagrant, Docker, and Git
+
+```console
+$ sudo apt install vagrant docker.io git
+```
+
+```{include} setup/install-docker.md
+
+```
+
+:::
+
+:::{tab-item} Fedora
+:sync: os-fedora
+
+##### 1. Install Vagrant, Docker, and Git
+
+```console
+$ sudo yum install vagrant git moby-engine
+```
+
+Fedora does not include the
+official `docker-ce` package in their repositories. They provide the package
+`moby-engine` which you can choose instead. In case you prefer the official
+docker distribution, you can follow
+[their documentation to install Docker on Fedora](https://docs.docker.com/engine/install/fedora/).
+
+```{include} setup/install-docker.md
+
+```
+
+:::
+
+::::
+
 ### Step 2: Get Zulip code
 
 1. In your browser, visit <https://github.com/zulip/zulip>
@@ -254,35 +249,42 @@ Checking connectivity... done.
 Checking out files: 100% (1912/1912), done.
 ```
 
-Now you are ready for [Step 3: Start the development
-environment](#step-3-start-the-development-environment).
-
 ### Step 3: Start the development environment
 
+::::{tab-set}
+
+:::{tab-item} Windows (WSL)
+:sync: os-windows
+
+Run the following to install the Zulip development environment and
+start it. (If Windows Firewall creates popups to block services,
+simply click **Allow access**.)
+
+```console
+$ # 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
+```
+
+If you are facing problems or you see error messages after running `./tools/run-dev`,
+you can try running `./tools/provision` again.
+:::
+
+:::{tab-item} Windows (VM)
+:sync: os-windows-vm
+
 Change into the zulip directory and tell Vagrant to start the Zulip
 development environment with `vagrant up`:
 
 ```console
-$ # On Windows:
 $ cd zulip
 $ vagrant plugin install vagrant-vbguest
 $ vagrant up --provider=virtualbox
-
-$ # On macOS or Linux:
-$ cd zulip
-$ vagrant up --provider=docker
 ```
 
-:::{warning}
-There is a [known upstream issue on macOS](https://chat.zulip.org/#narrow/stream/21-provision-help/topic/provision.20error.20ERR_PNPM_LINKING_FAILED/near/1649241)
-that can cause provisioning to fail with `ERR_PNPM_LINKING_FAILED` or other errors. The temporary
-fix is to open the Docker desktop app's settings panel, and choose `osxfs (legacy)` under "Choose
-file sharing implementation for your containers." Once Docker restarts, you should be able to
-successfully run `vagrant up --provider=docker`. Back in Docker, you can return to using VirtioFS
-for better system performance while developing, but you may need to revert to `osxfs (legacy)`
-whenever you need to re-provision.
-:::
-
 ```{include} setup/vagrant-up.md
 
 ```
@@ -295,7 +297,83 @@ normal and is not a problem.
 
 ```
 
-Now you're ready for [Step 4: Developing](#step-4-developing).
+:::
+
+:::{tab-item} macOS
+:sync: os-mac
+
+Change into the zulip directory and tell Vagrant to start the Zulip
+development environment with `vagrant up`:
+
+```console
+$ cd zulip
+$ vagrant up --provider=docker
+```
+
+**Important note**: There is a [known upstream issue on
+macOS](https://chat.zulip.org/#narrow/stream/21-provision-help/topic/provision.20error.20ERR_PNPM_LINKING_FAILED/near/1649241)
+that can cause provisioning to fail with `ERR_PNPM_LINKING_FAILED` or
+other errors. The temporary fix is to open the Docker desktop app's
+settings panel, and choose `osxfs (legacy)` under "Choose file sharing
+implementation for your containers." Once Docker restarts, you should
+be able to successfully run `vagrant up --provider=docker`. Back in
+Docker, you can return to using VirtioFS for better system performance
+while developing, but you may need to revert to `osxfs (legacy)`
+whenever you need to re-provision.
+
+```{include} setup/vagrant-up.md
+
+```
+
+```{include} setup/vagrant-ssh.md
+
+```
+
+:::
+
+:::{tab-item} Ubuntu/Debian
+:sync: os-ubuntu
+
+Change into the zulip directory and tell Vagrant to start the Zulip
+development environment with `vagrant up`:
+
+```console
+$ cd zulip
+$ vagrant up --provider=docker
+```
+
+```{include} setup/vagrant-up.md
+
+```
+
+```{include} setup/vagrant-ssh.md
+
+```
+
+:::
+
+:::{tab-item} Fedora
+:sync: os-fedora
+
+Change into the zulip directory and tell Vagrant to start the Zulip
+development environment with `vagrant up`:
+
+```console
+$ cd zulip
+$ vagrant up --provider=docker
+```
+
+```{include} setup/vagrant-up.md
+
+```
+
+```{include} setup/vagrant-ssh.md
+
+```
+
+:::
+
+::::
 
 ### Step 4: Developing
 
@@ -318,6 +396,63 @@ run `tools/lint` often to make sure you're following our coding style
 (or use `tools/setup-git-repo` to run it on just the changed files
 automatically whenever you commit).
 
+#### VSCode setup (optional)
+
+::::{tab-set}
+
+:::{tab-item} Windows (WSL)
+:sync: os-windows
+
+The [Visual Studio Code Remote -
+WSL](https://code.visualstudio.com/docs/remote/wsl) extension is
+recommended for editing files when developing with WSL. When you
+have it installed, you can run:
+
+```console
+$ code .
+```
+
+to open VS Code connected to your WSL environment. See the [Remote development in WSL][remote-wsl] tutorial for more information.
+:::
+
+:::{tab-item} Windows (VM)
+:sync: os-windows-vm
+
+```{include} setup/vscode-vagrant.md
+
+```
+
+:::
+
+:::{tab-item} macOS
+:sync: os-mac
+
+```{include} setup/vscode-vagrant.md
+
+```
+
+:::
+
+:::{tab-item} Ubuntu/Debian
+:sync: os-ubuntu
+
+```{include} setup/vscode-vagrant.md
+
+```
+
+:::
+
+:::{tab-item} Fedora
+:sync: os-fedora
+
+```{include} setup/vscode-vagrant.md
+
+```
+
+:::
+
+::::
+
 #### Understanding run-dev debugging output
 
 It's good to have the terminal running `./tools/run-dev` up as you work since error
@@ -338,28 +473,221 @@ guide][rtd-git-guide].
 
 #### Maintaining the development environment
 
+::::{tab-set}
+
+:::{tab-item} Windows (WSL)
+:sync: os-windows
+
+If after rebasing onto a new version of the Zulip server, you receive
+new errors while starting the Zulip server or running tests, this is
+probably not because Zulip's `main` branch is broken. Instead, this
+is likely because we've recently merged changes to the development
+environment provisioning process that you need to apply to your
+development environment. To update your environment, you'll need to
+re-provision using `tools/provision` from your Zulip checkout; this
+should complete in about a minute.
+
+After provisioning, you'll want to
+[(re)start the Zulip development server](/development/setup-recommended.md#step-3-start-the-development-environment).
+
+If you run into any trouble, [#provision
+help](https://chat.zulip.org/#narrow/stream/21-provision-help) in the
+[Zulip development community
+server](https://zulip.com/development-community/) is a great place to ask for
+help.
+
+:::
+
+:::{tab-item} Windows (VM)
+:sync: os-windows-vm
+
 ```{include} setup/vagrant-update.md
 
 ```
 
+:::
+
+:::{tab-item} macOS
+:sync: os-mac
+
+```{include} setup/vagrant-update.md
+
+```
+
+:::
+
+:::{tab-item} Ubuntu/Debian
+:sync: os-ubuntu
+
+```{include} setup/vagrant-update.md
+
+```
+
+:::
+
+:::{tab-item} Fedora
+:sync: os-fedora
+
+```{include} setup/vagrant-update.md
+
+```
+
+:::
+
+::::
+
 #### Rebuilding the development environment
 
+::::{tab-set}
+
+:::{tab-item} Windows (WSL)
+:sync: os-windows
+
 ```{include} setup/vagrant-rebuild.md
 
 ```
 
+:::
+
+:::{tab-item} Windows (VM)
+:sync: os-windows-vm
+
+```{include} setup/vagrant-rebuild.md
+
+```
+
+:::
+
+:::{tab-item} macOS
+:sync: os-mac
+
+```{include} setup/vagrant-rebuild.md
+
+```
+
+:::
+
+:::{tab-item} Ubuntu/Debian
+:sync: os-ubuntu
+
+```{include} setup/vagrant-rebuild.md
+
+```
+
+:::
+
+:::{tab-item} Fedora
+:sync: os-fedora
+
+```{include} setup/vagrant-rebuild.md
+
+```
+
+:::
+
+::::
+
 #### Shutting down the development environment for use later
 
+::::{tab-set}
+
+:::{tab-item} Windows (WSL)
+:sync: os-windows
+
+On Windows with WSL 2, you do not need to shut down the environment. Simply
+close your terminal window(s).
+:::
+
+:::{tab-item} Windows (VM)
+:sync: os-windows-vm
+
 ```{include} setup/vagrant-halt.md
 
 ```
 
+:::
+
+:::{tab-item} macOS
+:sync: os-mac
+
+```{include} setup/vagrant-halt.md
+
+```
+
+:::
+
+:::{tab-item} Ubuntu/Debian
+:sync: os-ubuntu
+
+```{include} setup/vagrant-halt.md
+
+```
+
+:::
+
+:::{tab-item} Fedora
+:sync: os-fedora
+
+```{include} setup/vagrant-halt.md
+
+```
+
+:::
+
+::::
+
 #### Resuming the development environment
 
+::::{tab-set}
+
+:::{tab-item} Windows (WSL)
+:sync: os-windows
+
+On Windows with WSL 2, to resume developing you just need to open a new Git
+BASH window. Then change into your `zulip` folder and verify the Python
+environment was properly activated (you will see `(zulip-py3-venv)`). If the
+`(zulip-py3-venv)` part is missing, run
+`source /srv/zulip-py3-venv/bin/activate`.
+:::
+
+:::{tab-item} Windows (VM)
+:sync: os-windows-vm
+
 ```{include} setup/vagrant-resume.md
 
 ```
 
+:::
+
+:::{tab-item} macOS
+:sync: os-mac
+
+```{include} setup/vagrant-resume.md
+
+```
+
+:::
+
+:::{tab-item} Ubuntu/Debian
+:sync: os-ubuntu
+
+```{include} setup/vagrant-resume.md
+
+```
+
+:::
+
+:::{tab-item} Fedora
+:sync: os-fedora
+
+```{include} setup/vagrant-resume.md
+
+```
+
+:::
+
+::::
+
 ### Next steps
 
 Next, read the following to learn more about developing for Zulip:
@@ -853,6 +1181,8 @@ remove the `GUEST_CPUS` and `GUEST_MEMORY_MB` lines from
 
 [vagrant-dl]: https://www.vagrantup.com/downloads.html
 [install-advanced]: setup-advanced.md
+[remote-wsl]: https://code.visualstudio.com/docs/remote/wsl-tutorial
+[remote-ssh]: https://code.visualstudio.com/docs/remote/ssh-tutorial
 [rtd-git-guide]: ../git/index.md
 [rtd-testing]: ../testing/testing.md
 [rtd-using-dev-env]: using.md

docs/development/setup/vagrant-up.md

@@ -1,8 +1,7 @@
 The first time you run this command it will take some time because Vagrant
 does the following:
 
-- downloads the base Ubuntu 20.04 virtual machine image (for macOS and Windows)
-  or container (for Linux)
+- downloads the base Ubuntu 20.04 virtual machine/Docker image
 - configures this virtual machine/container for use with Zulip,
 - creates a shared directory mapping your clone of the Zulip code inside the
   virtual machine/container at `~/zulip`

docs/development/setup/vscode-vagrant.md

@@ -0,0 +1,34 @@
+If your preferred editor is Virtual Studio Code, the [Visual Studio
+Code Remote - SSH](https://code.visualstudio.com/docs/remote/ssh)
+extension is recommended for editing files when developing with
+Vagrant. When you have it installed, you can run:
+
+```console
+$ code .
+```
+
+to open VS Code connected to your Vagrant environment. See the
+[Remote development over SSH][remote-ssh] tutorial for more information.
+
+When using this plugin with Vagrant, you will want to run the command
+`vagrant ssh-config` from your `zulip` folder:
+
+```console
+$ vagrant ssh-config
+Host default
+  HostName 127.0.0.1
+  User vagrant
+  Port 2222
+  UserKnownHostsFile /dev/null
+  StrictHostKeyChecking no
+  PasswordAuthentication no
+  IdentityFile /PATH/TO/zulip/.vagrant/machines/default/docker/private_key
+  IdentitiesOnly yes
+  LogLevel FATAL
+  PubkeyAcceptedKeyTypes +ssh-rsa
+  HostKeyAlgorithms +ssh-rsa
+```
+
+Then copy that config into your `~/.ssh/config` file. You may want to change
+the host name from `default` to something more descriptive, like `zulip`.
+Finally, refresh the known remotes in Visual Studio Code's Remote Explorer.

docs/git/cloning.md

@@ -99,9 +99,6 @@ 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 or 11,
-you are ready to [continue with step 9](../development/setup-recommended.md#windows-10-or-11).
-
 ## Step 3: Configure continuous integration for your fork
 
 This step is optional, but recommended.