From ab399231c29ab31d982769b6f235ea06bee312c1 Mon Sep 17 00:00:00 2001 From: Blake McAnally Date: Thu, 5 Nov 2026 12:11:22 -0600 Subject: [PATCH] docs: mark desktop/ as the deprecated Buzz 0.X app (#8840) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary `desktop/` is the Buzz 0.X desktop app. Buzz 1.0 lives in [block/buzz-app](https://github.com/block/buzz-app), and its README already says so. Nothing in this repo says it, so contributors and agents keep opening feature PRs against `desktop/`. This PR adds the rule in three places: - **`AGENTS.md`**: a notice at the top of "Desktop App" and a note in the repo layout. Agents read this file first. The notice also says that CLI PRs do not update the 0.X agent guidance in `nest_skill.md`. - **`CONTRIBUTING.md`**: a new item in "PRs We're Unlikely to Merge". - **`desktop/README.md`**: a notice at the top. The rule: build desktop features in block/buzz-app, or as a Buzz plugin. Change `desktop/` here only to fix a 0.X bug, or to keep it compiling after a shared crate changes. ## Testing - This PR changes only documentation. I checked the diff and the two block/buzz-app links. ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Blake McAnally Co-authored-by: Claude Opus 5.5 --- AGENTS.md | 19 +++++++++++++------ CONTRIBUTING.md | 16 ++++++++++++---- desktop/README.md | 6 ++++++ 3 files changed, 31 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c7b6d363ac..27322f8ee8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -74,11 +74,12 @@ confirmation, not app runs. ## Ecosystem -Buzz spans five repos. This one (`block/buzz`) is the OSS source for the relay, desktop, mobile, and CLI. The others handle internal builds and deployment: +Buzz spans six repos. This one (`block/buzz`) is the OSS source for the relay, mobile, CLI, and the deprecated Buzz 0.X desktop app. [block/buzz-app](https://github.com/block/buzz-app) is the OSS source for the Buzz 1.0 desktop and web app. The others handle internal builds and deployment: | Repo | Purpose | |------|---------| -| [block/buzz](https://github.com/block/buzz) | OSS source โ€” relay, desktop app, mobile app, CLI, agent harness | +| [block/buzz](https://github.com/block/buzz) | OSS source โ€” relay, mobile app, CLI, agent harness, deprecated Buzz 0.X desktop app | +| [block/buzz-app](https://github.com/block/buzz-app) | OSS source โ€” Buzz 1.0 desktop and web app; all new desktop feature work | | [squareup/buzz-releases](https://github.com/squareup/buzz-releases) | Buildkite pipelines producing Block-signed macOS + iOS builds with `-block` desktop version suffix | | [squareup/sprout-oss](https://github.com/squareup/sprout-oss) | CI pipeline building the relay Docker image and pushing to internal ECR | | [squareup/block-coder-tf-stacks](https://github.com/squareup/block-coder-tf-stacks) | Terraform + ArgoCD deploying the relay to the staging Kubernetes cluster | @@ -130,7 +131,7 @@ crates/ buzz-test-client # Integration test client and E2E test suite sprig # All-in-one harness bundling ACP, agent, and dev MCP -desktop/ # Legacy Tauri 2 + React 19 desktop app (being replaced by block/buzz-app) +desktop/ # Buzz 0.X Tauri desktop app (deprecated: new desktop work goes to block/buzz-app) web/ # Browser web client (repo browser, served by the relay) mobile/ # Flutter mobile app migrations/ # SQL migrations (run at relay startup when BUZZ_AUTO_MIGRATE is on: binary default off, Helm default on; deployments at scale apply them out of band โ€” see docs/database.md) @@ -646,9 +647,15 @@ description. See [PR #803](https://github.com/block/buzz/pull/803). ## Desktop App -> **Legacy.** `desktop/` will soon be superseded by -> [block/buzz-app](https://github.com/block/buzz-app). Never use it as an -> implementation or design reference for the mobile app, which is current. +> **`desktop/` is deprecated.** It is the Buzz 0.X desktop app. The Buzz 1.0 +> desktop app lives in [block/buzz-app](https://github.com/block/buzz-app). +> Do not open block/buzz PRs that add features to `desktop/`; build desktop +> features in block/buzz-app (or as a Buzz plugin) instead. Change `desktop/` +> here only to fix a 0.X bug, or to keep it compiling when a shared crate it +> depends on changes. This includes agent guidance bundled with the 0.X app, +> such as `desktop/src-tauri/src/managed_agents/nest_skill.md`: CLI PRs do not +> need to update it. Never use it as an implementation or design reference for +> the mobile app, which is current. The desktop app is Tauri 2 + React 19 + Vite + Tailwind CSS. Features are organized under `desktop/src/features/`. Biome handles linting and formatting. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8495d521b7..404c8532a7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -442,6 +442,11 @@ because we can't safely review them without prior discussion: - **Cosmetic renames or style-only churn** that doesn't fix a bug or improve clarity - **Entirely new features** with no prior discussion +- **Feature work in `desktop/`** โ€” `desktop/` is the deprecated Buzz 0.X + desktop app. Build desktop features in + [block/buzz-app](https://github.com/block/buzz-app) instead; change + `desktop/` here only to fix a 0.X bug or to keep it compiling after a shared + crate change - **Drive-by changes bundled into an unrelated fix** โ€” split them out If you're considering any of these, open an issue first and we'll tell you @@ -482,15 +487,18 @@ to existing clients. ## Ecosystem Buzz is developed across multiple repositories. This repo (`block/buzz`) -is the open-source home for all application code โ€” the relay, desktop app, -mobile app, CLI, and agent harness. Internal repositories handle +is the open-source home for the relay, mobile app, CLI, and agent harness. +It also holds `desktop/`, the deprecated Buzz 0.X desktop app. The Buzz 1.0 +desktop and web app lives in [block/buzz-app](https://github.com/block/buzz-app), +and all new desktop feature work goes there. Internal repositories handle enterprise-signed builds and infrastructure deployment. See [AGENTS.md ยง Ecosystem](AGENTS.md#ecosystem) for the full repo table and dependency diagram. -**External contributors:** Fork `block/buzz`, open a PR, and CI runs -automatically. No special access is required. +**External contributors:** Fork `block/buzz` (or `block/buzz-app` for +desktop work), open a PR, and CI runs automatically. No special access is +required. **Block team members:** See the internal [sprout-releases CONTRIBUTING.md](https://github.com/squareup/sprout-releases/blob/main/CONTRIBUTING.md) diff --git a/desktop/README.md b/desktop/README.md index d53698a9d0..79921e4d29 100644 --- a/desktop/README.md +++ b/desktop/README.md @@ -1,5 +1,11 @@ # Buzz +> [!IMPORTANT] +> **This is the deprecated Buzz 0.X desktop app.** Buzz 1.0 lives in +> [block/buzz-app](https://github.com/block/buzz-app). Build new desktop +> features there. Change this directory only to fix a 0.X bug, or to keep it +> compiling after a shared crate change. + Desktop chat shell with: - Tauri + React + TypeScript + Vite