Docs Party 2024 (#15876)

Co-authored-by: Raunak Raj <nkray21111983@gmail.com>
Co-authored-by: Thorsten Ball <mrnugget@gmail.com>
Co-authored-by: Bennet <bennet@zed.dev>
Co-authored-by: Marshall Bowers <elliott.codes@gmail.com>
Co-authored-by: Joseph T Lyons <JosephTLyons@gmail.com>
Co-authored-by: Mikayla <mikayla@zed.dev>
Co-authored-by: Jason <jason@zed.dev>
Co-authored-by: Antonio Scandurra <me@as-cii.com>
Co-authored-by: Max Brunsfeld <maxbrunsfeld@gmail.com>
Co-authored-by: Marshall <marshall@zed.dev>
Co-authored-by: Nathan Sobo <nathan@zed.dev>
Co-authored-by: Jason Mancuso <7891333+jvmncs@users.noreply.github.com>
Co-authored-by: Piotr Osiewicz <24362066+osiewicz@users.noreply.github.com>

docs/src/development/debugging-crashes.md

@@ -2,9 +2,12 @@
 
 ## Crashes
 
-When an app crashes, macOS creates a `.ips` file in `~/Library/Logs/DiagnosticReports`. You can view these using the built in Console app (`cmd-space Console`) under "Crash Reports".
+When an app crashes,
 
-If you have enabled Zed's telemetry these will be uploaded to us when you restart the app. They end up in Datadog, and a [Slack channel (internal only)](https://zed-industries.slack.com/archives/C04S6T1T7TQ).
+- macOS creates a `.ips` file in `~/Library/Logs/DiagnosticReports`. You can view these using the built in Console app (`cmd-space Console`) under "Crash Reports".
+- Linux creates a core dump. See the [man pages](https://man7.org/linux/man-pages/man5/core.5.html) for pointers to how your system might be configured to manage core dumps.
+
+If you have enabled Zed's telemetry these will be uploaded to us when you restart the app. They end up in a [Slack channel (internal only)](https://zed-industries.slack.com/archives/C04S6T1T7TQ).
 
 These crash reports are generated by the crashing binary, and contain a wealth of information; but they are hard to read for a few reasons:
 
@@ -12,9 +15,9 @@ These crash reports are generated by the crashing binary, and contain a wealth o
 - The symbols are [mangled](https://doc.rust-lang.org/rustc/symbol-mangling/index.html)
 - Inlined functions are elided
 
-To get a better sense of the backtrace of a crash you can download the `.ips` file locally and run:
+On macOS, to get a better sense of the backtrace of a crash you can download the `.ips` file locally and run:
 
-```
+```sh
 ./script/symbolicate ~/path/zed-XXX-XXX.ips
 ```
 
@@ -24,6 +27,6 @@ The output contains the source file and line number, and the demangled symbol in
 
 ## Panics
 
-When the app panics at the rust level, Zed creates a file in `~/Library/Logs/Zed` with the text of the panic, and a summary of the backtrace. On boot, if you have telemetry enabled, we upload these panics so we can keep track of them.
+When the app panics at the rust level, Zed creates a file in `~/Library/Logs/Zed` or `$XDG_DATA_HOME/logs` with the text of the panic, and a summary of the backtrace. On boot, if you have telemetry enabled, we upload these panics so we can keep track of them.
 
 A panic is also considered a crash, and so for most panics we get both the crash report and the panic.

docs/src/development/linux.md

@@ -8,13 +8,13 @@ Clone down the [Zed repository](https://github.com/zed-industries/zed).
 
 - Install [Rust](https://www.rust-lang.org/tools/install). If it's already installed, make sure it's up-to-date:
 
-  ```bash
+  ```sh
   rustup update
   ```
 
 - Install the necessary system libraries:
 
-  ```bash
+  ```sh
   script/linux
   ```
 
@@ -41,19 +41,19 @@ Once the dependencies are installed, you can build Zed using [Cargo](https://doc
 
 For a debug build of the editor:
 
-```
+```sh
 cargo run
 ```
 
 And to run the tests:
 
-```
+```sh
 cargo test --workspace
 ```
 
 In release mode, the primary user interface is the `cli` crate. You can run it in development with:
 
-```
+```sh
 cargo run -p cli
 ```
 
@@ -61,7 +61,7 @@ cargo run -p cli
 
 You can install a local build on your machine with:
 
-```
+```sh
 ./script/install-linux
 ```
 

docs/src/development/local-collaboration.md

@@ -10,7 +10,7 @@ First, make sure you've installed Zed's backend dependencies for your platform:
 
 Before you can run the `collab` server locally, you'll need to set up a `zed` Postgres database.
 
-```
+```sh
 script/bootstrap
 ```
 
@@ -18,7 +18,7 @@ This script will set up the `zed` Postgres database, and populate it with some u
 
 The script will seed the database with various content defined by:
 
-```
+```sh
 cat crates/collab/seed.default.json
 ```
 
@@ -35,18 +35,14 @@ To use a different set of admin users, you can create your own version of that j
 
 In one terminal, run Zed's collaboration server and the `livekit` dev server:
 
-```
-
+```sh
 foreman start
-
 ```
 
 In a second terminal, run two or more instances of Zed.
 
-```
-
+```sh
 script/zed-local -2
-
 ```
 
 This script starts one to four instances of Zed, depending on the `-2`, `-3` or `-4` flags. Each instance will be connected to the local `collab` server, signed in as a different user from `.admins.json` or `.admins.default.json`.
@@ -55,7 +51,7 @@ This script starts one to four instances of Zed, depending on the `-2`, `-3` or
 
 If you want to run your own version of the zed collaboration service, you can, but note that this is still under development, and there is no good support for authentication nor extensions.
 
-Configuration is done through environment variables. By default it will read the configuration from [`.env.toml`](../../crates/collab/.env.toml) and you should use that as a guide for setting this up.
+Configuration is done through environment variables. By default it will read the configuration from [`.env.toml`](https://github.com/zed-industries/zed/blob/main/crates/collab/.env.toml) and you should use that as a guide for setting this up.
 
 By default Zed assumes that the DATABASE_URL is a Postgres database, but you can make it use Sqlite by compiling with `--features sqlite` and using a sqlite DATABASE_URL with `?mode=rwc`.
 

docs/src/development/macos.md

@@ -13,19 +13,19 @@ Clone down the [Zed repository](https://github.com/zed-industries/zed).
 
 - Install [Xcode command line tools](https://developer.apple.com/xcode/resources/)
 
-  ```bash
+  ```sh
   xcode-select --install
   ```
 
 - Ensure that the Xcode command line tools are using your newly installed copy of Xcode:
 
-  ```
+  ```sh
   sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
   ```
 
 * Install the Rust wasm toolchain:
 
-  ```bash
+  ```sh
   rustup target add wasm32-wasi
   ```
 
@@ -36,7 +36,7 @@ If you are developing collaborative features of Zed, you'll need to install the
 - Install [Postgres](https://postgresapp.com)
 - Install [Livekit](https://formulae.brew.sh/formula/livekit) and [Foreman](https://formulae.brew.sh/formula/foreman)
 
-  ```bash
+  ```sh
   brew install livekit foreman
   ```
 
@@ -52,19 +52,19 @@ Once you have the dependencies installed, you can build Zed using [Cargo](https:
 
 For a debug build:
 
-```
+```sh
 cargo run
 ```
 
 For a release build:
 
-```
+```sh
 cargo run --release
 ```
 
 And to run the tests:
 
-```
+```sh
 cargo test --workspace
 ```
 
@@ -72,7 +72,7 @@ cargo test --workspace
 
 ### Error compiling metal shaders
 
-```
+```sh
 error: failed to run custom build command for gpui v0.1.0 (/Users/path/to/zed)`**
 
 xcrun: error: unable to find utility "metal", not a developer tool or in PATH
@@ -88,7 +88,7 @@ Try `cargo clean` and `cargo build`.
 
 If you encounter an error similar to:
 
-```bash
+```sh
 src/platform/mac/dispatch.h:1:10: fatal error: 'dispatch/dispatch.h' file not found
 
 Caused by:
@@ -105,20 +105,20 @@ Caused by:
 
 This file is part of Xcode. Ensure you have installed the Xcode command line tools and set the correct path:
 
-```bash
+```sh
 xcode-select --install
 sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
 ```
 
 Additionally, set the `BINDGEN_EXTRA_CLANG_ARGS` environment variable:
 
-```bash
+```sh
 export BINDGEN_EXTRA_CLANG_ARGS="--sysroot=$(xcrun --show-sdk-path)"
 ```
 
 Then clean and rebuild the project:
 
-```bash
+```sh
 cargo clean
 cargo run
 ```

docs/src/development/windows.md

@@ -10,13 +10,13 @@ Clone down the [Zed repository](https://github.com/zed-industries/zed).
 
 - Install [Rust](https://www.rust-lang.org/tools/install). If it's already installed, make sure it's up-to-date:
 
-  ```bash
+  ```sh
   rustup update
   ```
 
 - Install the Rust wasm toolchain:
 
-  ```bash
+  ```sh
   rustup target add wasm32-wasi
   ```
 
@@ -44,34 +44,36 @@ Once you have the dependencies installed, you can build Zed using [Cargo](https:
 
 For a debug build:
 
-```
+```sh
 cargo run
 ```
 
 For a release build:
 
-```
+```sh
 cargo run --release
 ```
 
 And to run the tests:
 
-```
+```sh
 cargo test --workspace
 ```
 
 ## Installing from msys2
 
-[MSYS2](https://msys2.org/) distribution provides Zed as a package. To download the prebuilt binary, run
+[MSYS2](https://msys2.org/) distribution provides Zed as a package [mingw-w64-zed](https://packages.msys2.org/base/mingw-w64-zed). To download the prebuilt binary, run
 
-```
+```sh
 pacman -Syu
 pacman -S mingw-w64-ucrt-x86_64-zed
 ```
 
 then you can run `zed` in a UCRT64 shell.
 
-> Please, report any issue in https://github.com/msys2/MINGW-packages/issues first.
+You can see the [build script](https://github.com/msys2/MINGW-packages/blob/master/mingw-w64-zed/PKGBUILD) for more details.
+
+> Please, report any issue in [msys2/MINGW-packages/issues](https://github.com/msys2/MINGW-packages/issues?q=is%3Aissue+is%3Aopen+zed) first.
 
 ## Troubleshooting