Conventions

This repository is zed-industries/zed trimmed to GPUI. It exists so DeltaQ products (Rexa, Zedra) can use GPUI changes before Zed merges them, ship their own GPUI changes, and send those changes back to Zed, all without waiting on Zed's release cycle.

Everything specific to this fork lives under deltaq/, site/, and .github/workflows/deltaq-*.yml. Those paths never exist upstream, so upstream merges never touch them.

The one rule

Edits to kept upstream files happen only inside a tracked change.

Two kinds of commits touch this repository:

1. Trim and sync commits (the initial trim, every sync-upstream). These never edit a kept file. They only delete paths not in deltaq/keep.txt and regenerate the root Cargo.toml. Every kept file is byte-identical to upstream after such a commit. This is what keeps git merge upstream/main mechanical.
2. Change commits. Editing crates/gpui/src/window.rs for a feature or fix is normal and expected. It is done on a change/<name> branch, recorded in deltaq/changes.toml, and merged into gpui by pull request.

What is forbidden is a loose commit on gpui that edits a kept file without a changes.toml entry. Such a commit belongs to no change, so it cannot be cherry-picked onto upstream/main for a Zed PR, cannot be dropped once Zed merges an equivalent, and will conflict on every future sync.

Branches

upstream is a remote (https://github.com/zed-industries/zed), never a work branch. Feature work happens on the trimmed tree, which builds in a fraction of the time.

Workflows

Sync with upstream (weekly by CI, or by hand):

deltaq/scripts/sync-upstream      # merge, strip, regenerate Cargo.toml, resolve
                                  # exit 2 = real conflict in a kept crate

Adopt a Zed PR before Zed merges it:

deltaq/scripts/adopt-pr 12345     # branch, merge into adopt/pr-12345, record in changes.toml

Start an own change and send it to Zed:

deltaq/scripts/new-change fast-tables        # change/fast-tables off gpui
# commit work, open a PR against gpui
deltaq/scripts/prepare-upstream-pr fast-tables   # cherry-pick onto upstream/main, open Zed PR

See where things stand:

deltaq/scripts/status
deltaq/scripts/track-changes      # queries GitHub for each tracked Zed PR

Change lifecycle

Every non-upstream diff on gpui is one entry in deltaq/changes.toml.

1. tracking: the Zed PR is open. The daily Track changes workflow watches its head. When it moves, a fork PR titled Update Zed #n follows it.
2. merged-upstream: Zed merged it. The next sync-upstream takes upstream's version of the change's files (Zed squash-merges, so the content matches) and flips the entry to done.
3. closed-upstream: Zed closed it unmerged. Decide: keep it as an own change (edit the entry to kind = "own", zed_pr = 0, status = "tracking") or revert it from gpui.

Keep changes small and single-purpose. A change that Zed will not take (for example a DeltaQ-only platform target) is still tracked, with zed_pr = 0, so that syncs know which files to expect conflicts in.

Documentation site

site/ is an Astro project using DeltaQ's Mines theme, published at https://gpui.deltaq.dev. Vercel's Git integration builds it from the gpui branch (root directory site, pnpm build, output dist, with "Include source files outside of the Root Directory" enabled so the build can read the rest of the tree) and gives every pull request a preview URL; the Docs site workflow only checks that the site builds.

cd site
pnpm install
pnpm build      # also writes llms.txt, <page>.md routes and the search index
pnpm preview

Pages are MDX under site/src/content/docs, ordered by numeric prefix. Files that live elsewhere in the tree (crates/gpui/README.md, crates/gpui/docs/*, deltaq/CONVENTIONS.md, deltaq/changes.toml) are pulled in at build time with an include code fence whose body is the path relative to the page:

```include
../../../../../crates/gpui/docs/contexts.md
```

Never copy those files into site/; a copy would drift from the tree it documents. site/src/includes.ts expands the fence for both the HTML pages and the raw-Markdown routes.

Consuming this repository

Vendor it as a git submodule and use path dependencies:

gpui = { path = "vendor/gpui/crates/gpui" }
gpui_platform = { path = "vendor/gpui/crates/gpui_platform" }

[patch.crates-io]
# Cargo applies [patch] only from the root workspace, so the consumer must
# repeat the entries gpui needs. Copy them from this repository's Cargo.toml.
async-task = { git = "https://github.com/smol-rs/async-task.git", rev = "..." }
calloop = { git = "https://github.com/zed-industries/calloop" }
# If the consumer also depends on crates that pull `gpui` from crates.io
# (for example gpui-component), point that name at the vendored copy:
gpui = { path = "vendor/gpui/crates/gpui" }

Set shallow = true for the submodule in .gitmodules; the full history is about 400 MB.

Licensing

Every crate kept here is Apache-2.0 (deltaq/scripts/check-licenses enforces it). LICENSE-APACHE at the root is the licence for the whole tree.

• Apache-2.0 requires modified files to carry a notice that they changed. This fork satisfies that at repository level: README.md states that the tree is a modified subset of Zed, and every change is listed in deltaq/changes.toml.
• "Zed" and "GPUI" are Zed Industries names. Do not publish these crates to crates.io under their upstream names.
• Fonts under assets/fonts are SIL OFL 1.1; keep their licence files.
• Third-party crate licences are checked with cargo-about using upstream's accepted list (script/licenses/zed-licenses.toml).
• Contributing to Zed requires signing Zed's CLA on your first Zed PR.