Development workflow

Branch and PR cycle

1. Fork or branch off main.
2. Implement the change. Keep the PR scoped to a single concern.
3. Run cargo test and ./script/clippy locally.
4. Open a PR following the hygiene rules.
5. Reviewers are auto-assigned by .github/workflows/assign-reviewers.yml based on REVIEWERS.conl.
6. If your change touches an area with a dedicated reviewer (e.g. gpui, lsp, vim), expect them to weigh in.

Branches and releases

Zed runs three release channels in parallel: nightly, preview, stable. The wiring lives in crates/release_channel. Channel handling for cherry-picks is automated:

• script/cherry-pick — port a fix back to a release branch.
• .github/workflows/cherry_pick.yml — assist with cherry-picking on PRs labelled accordingly.
• .github/workflows/hotfix-review-monitor.yml — extra scrutiny on hotfix PRs.
• script/draft-release-notes and script/get-release-notes-since — generate release notes from the PRs since a tag.
• script/bump-zed-version, script/bump-nightly, script/bump-extension-cli — version bumps.

Building locally

Common entry points:

cargo run                          # debug build of zed
cargo run --release                # release build
cargo run --bin cli                # zed CLI launcher
cargo run --bin collab -- serve api
cargo run --bin remote_server

Hot-loop tip: combine with --profile release-fast for faster iteration when debug performance is too slow but full release is overkill.

When you change a crate's public API

• Workspace-wide consumers will recompile. Run cargo check from the workspace root before pushing.
• If the crate is referenced by crates/zed/src/main.rs, expect the entire app to be touched.
• If you change settings shape, run the migrator: see crates/migrator and the script/check-keymaps invariants.

When you add a new crate

Per .rules:

• Specify the library root in Cargo.toml via [lib] path = "src/<name>.rs". Avoid the default lib.rs.
• Avoid mod.rs. Use src/some_module.rs for the module root.
• Add the crate to the workspace members list in the root Cargo.toml.
• Set publish = false if it should not be published to crates.io (most internal crates do this).

When you add a dependency

• Add it to the workspace [workspace.dependencies] block in the root Cargo.toml so all crates pull the same version.
• Run ./script/check-licenses to make sure the license is acceptable.
• If cargo-about cannot find the license, add a clarification in script/licenses/zed-licenses.toml.

When you change UI

• Add a screenshot or recording to the PR.
• Update visual regression tests if applicable. See crates/zed/src/visual_test_runner.rs and the visual-tests Cargo feature on the zed crate.
• Walk the UI/UX checklist from CONTRIBUTING.md.

Working with AI assistance

The repo's .rules file is read by AI agents. If you discover a non-obvious pattern that future agent sessions would benefit from, do not edit .rules inline. Instead, include a Suggested .rules additions heading in your PR body. Reviewers decide what merges.

The bar for new rules is high (from .rules):

1. Non-obvious — someone familiar with the codebase would still get it wrong without the rule.
2. Repeatedly encountered — it has come up more than once.
3. Specific enough to act on — concrete, not vague principles.

Single-crate rules go in that crate's own .rules file, not the repo root.