docs(contributing): add bootstrap troubleshooting guide

CONTRIBUTING.md

@@ -141,6 +141,129 @@ cargo run            # build and run Warp
 ./script/presubmit   # fmt, clippy, and tests
 ```
 
+## Bootstrap Troubleshooting
+
+The bootstrap script (`./script/bootstrap`) sets up your machine for Warp development. If it fails, the sections below may help you resolve the issue.
+
+### macOS
+
+**Missing Xcode or Command Line Tools**
+If bootstrap reports that Xcode is not found, download Xcode from the Mac App Store. After installing, accept the license agreement and run:
+```bash
+sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+xcodebuild -runFirstLaunch
+```
+
+**Homebrew issues**
+If `brew` commands fail, check your PATH includes Homebrew's bin directory (typically `/opt/homebrew/bin` on Apple Silicon or `/usr/local/bin` on Intel). You can verify with:
+```bash
+echo $PATH
+```
+If it's missing, add it to your shell profile (~/.zshrc or ~/.bashrc):
+```bash
+echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+To fix a broken Homebrew installation:
+```bash
+cd "$(brew --repo)"
+git fetch origin
+git reset --hard origin/master
+```
+
+**Rust toolchain errors**
+If `cargo` is not found after installation, start a new terminal session. If the problem persists:
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source ~/.cargo/env
+```
+
+### Linux
+
+**Missing dependencies**
+If the build fails due to missing libraries, update apt and re-run the dependency installation:
+```bash
+sudo apt update -y
+./script/linux/install_test_deps
+```
+
+**Rust version mismatch**
+Warp requires a recent Rust version. Check your version:
+```bash
+rustc --version
+cargo --version
+```
+If outdated, update with:
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+source ~/.cargo/env
+```
+
+**gcloud authentication**
+If prompted about missing gcloud authentication:
+```bash
+gcloud auth login
+```
+
+### Windows (WSL2)
+
+Warp development on Windows is supported via WSL2. Ensure you are running Ubuntu inside WSL2 and not using Docker or a VM.
+
+Install WSL2 and set up your environment:
+```powershell
+wsl --install -d Ubuntu
+```
+
+After entering the WSL2 terminal, run bootstrap as normal:
+```bash
+./script/bootstrap
+```
+
+**Visual Studio Build Tools**
+If native compilation is needed and `cl` is not found, install Visual Studio Build Tools:
+1. Download Visual Studio Build Tools from https://visualstudio.microsoft.com/downloads/
+2. Select "Desktop development with C++" workload
+3. Restart your terminal and ensure the VS Developer Command Prompt is not active (it can conflict with WSL2)
+
+### Network and Timeout Issues
+
+**Slow or failing downloads**
+If bootstrap fails while downloading packages, check your internet connection and try again. For slow network conditions, you can set a longer timeout for curl:
+```bash
+export CURL_TIMEOUT=120
+./script/bootstrap
+```
+
+**Git LFS errors**
+If `git lfs pull` times out or fails:
+```bash
+git lfs install
+git lfs fetch
+git lfs checkout
+```
+
+### When Bootstrap Fails Completely
+
+If bootstrap consistently fails:
+
+1. **Check required tools** — Ensure Git, curl, and a package manager are installed and up-to-date:
+   ```bash
+   git --version
+   curl --version
+   ```
+
+2. **Run steps manually** — Bootstrap is a thin dispatcher; you can run the platform-specific script directly to isolate the failure:
+   - macOS: `./script/macos/bootstrap`
+   - Linux: `./script/linux/bootstrap`
+
+3. **Check system requirements** — Ensure your OS version and architecture are supported. Check [README.md](README.md) for the current requirements.
+
+4. **Ask for help** — If you've tried the above and still can't bootstrap, open a GitHub issue with:
+   - Your OS version and architecture (`uname -a`)
+   - The exact error output
+   - Steps you've already tried
+
 ## Testing
 
 Tests are required for most code changes:
@@ -168,6 +291,57 @@ Run unit tests with `cargo nextest run`.
 - Branch names should be prefixed with your handle (e.g. `alice/fix-parser`).
 - Commit messages should explain *what* and *why*, not just *what*.
 
+## Release Process
+
+Warp publishes releases on three channels: **dev** (nightly), **preview** (weekly), and **stable** (weekly).
+
+### Release schedule
+
+| Channel | Frequency | Trigger |
+|---------|-----------|---------|
+| dev | Nightly (every morning at 3am EST) | Automated cron |
+| preview | Weekly (Wednesday mornings at 3am EST) | Automated cron |
+| stable | Weekly (Wednesday mornings at 3am EST) | Automated cron |
+
+All three channels can also be triggered manually via the **Cut New Releases** workflow on GitHub Actions.
+
+### Cutting a release candidate
+
+Release candidates (RCs) are cut manually on a dedicated release branch. The branch name determines the target channel:
+
+```
+<channel>_release/<date-or-name>
+```
+
+For example: `stable_release/2024-01-15`, `preview_release/rc-42`.
+
+To cut an RC:
+
+1. Create and push a branch following the naming convention above.
+2. Go to the **Cut New Release Candidate** workflow in GitHub Actions and click **Run workflow** on your branch.
+3. The workflow creates the RC artifacts and updates the [channel-versions](https://github.com/warpdotdev/channel-versions) repository.
+
+### Testing a release candidate
+
+RCs are available to test as soon as they are published. To access an RC:
+
+- **Dev/Preview RCs**: Use the Warp beta download links surfaced by the workflow run, or install from the corresponding pre-release assets.
+- **Stable RCs**: Stable RCs are promoted to the stable channel after a soak period. Testing details (e.g., specific test racks, feedback channels) are posted in the `#release` Slack channel when the RC is cut.
+
+When testing an RC, focus on regressions in core workflows — the kind of issues that would block a stable release. File bugs against the RC milestone or post in `#oss-contributors` with a link to the regression.
+
+### Final releases
+
+Final releases are produced by the automated **Cut New Releases** workflow, which runs on schedule and can also be triggered manually. The workflow:
+
+1. Creates release artifacts for each targeted channel.
+2. Publishes them to the appropriate distribution endpoints.
+3. Updates the [channel-versions](https://github.com/warpdotdev/channel-versions) repository so Warp clients receive the new version.
+
+### Release-related questions
+
+For release scheduling, RC testing, or publication issues, reach out in **[#oss-contributors](https://warpcommunity.slack.com/archives/C0B0LM8N4DB)** on Slack or mention **@oss-maintainers** on a GitHub issue or PR.
+
 ## Code of Conduct
 
 This project adopts the [Contributor Covenant](https://www.contributor-covenant.org/) (v2.1) as its code of conduct. All contributors and maintainers are expected to follow it in every project space. See [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) for the full text, or report violations to warp-coc at warp.dev.