From 1dd09c3e760cb854e97dd62a71e204683eaf0309 Mon Sep 17 00:00:00 2001 From: Mikayla Maki Date: Fri, 6 Mar 2026 14:14:53 -0800 Subject: [PATCH] Add Zed Feature Process document (#50747) Release Notes: - N/A --- CONTRIBUTING.md | 2 + docs/src/development/feature-process.md | 51 +++++++++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 docs/src/development/feature-process.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 740b33dd55790bd3cabfc75146d71854eca6375d..e7e7629825b5f487a3b00af525d36458eb91956c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,6 +26,8 @@ If you're looking for concrete ideas: - [Triaged bugs with confirmed steps to reproduce](https://github.com/zed-industries/zed/issues?q=is%3Aissue%20state%3Aopen%20type%3ABug%20label%3Astate%3Areproducible). - [Area labels](https://github.com/zed-industries/zed/labels?q=area%3A*) to browse bugs in a specific part of the product you care about (after clicking on an area label, add type:Bug to the search). +If you're thinking about proposing or building a larger feature, read the [Zed Feature Process](./docs/src/development/feature-process.md) for how we think about feature design — what context to provide, what integration points to consider, and how to put together a strong proposal. + ## Sending changes The Zed culture values working code and synchronous conversations over long diff --git a/docs/src/development/feature-process.md b/docs/src/development/feature-process.md new file mode 100644 index 0000000000000000000000000000000000000000..811e1a4fd6130fdf0abc687f6943f58b24e81b08 --- /dev/null +++ b/docs/src/development/feature-process.md @@ -0,0 +1,51 @@ +# Zed's Feature Development Process + +This is for moderate-to-large features — new UI, behavior changes, or work that cuts across multiple parts of Zed. Small keybindings or settings tweaks don't need all of this. + +> **Before you start:** If you're an external contributor, make sure the feature is something the team wants before investing significant effort. That said, coming prepared with background research makes it much easier for the team to understand and approve the proposal. Read the [Contributing guide](../../../CONTRIBUTING.md#sending-changes) — if there isn't already a GitHub issue with staff confirmation, start with a GitHub Discussion or a Discord message rather than a PR. + +## 1. Why does this matter? + +Every feature starts as an idea. Before writing any code, ground it: + +- **What problem does this solve?** +- **What's the evidence?** GitHub issues, Discord requests, thumbs-up counts, blog posts. +- **Is there prior art?** If it's in VS Code, JetBrains, Neovim, or a wildly popular plugin, that's a strong signal. If the idea is more novel, name what it's based on — "This is X, adapted for Zed's multi-buffers" is far more useful than "I think this would be cool." + +## 2. What is it? + +Write a short, concrete feature statement, then back it up with the context gathered above. If you can't describe the feature in a few sentences, it might be too big or too vague. + +Here's an example format, though adapt it to whatever your feature needs: + +> **Feature:** Inline Git Blame +> **Purpose:** Show the last commit author and message for each line directly after the editor text, so developers can understand code history without opening the git blame. +> **Background:** +> This is standard across all major code editors +> \[screenshot of VSCode] +> \[screenshot of Intellij] +> \[screenshot of Neovim] +> and has 146 thumbs up on the [github issue](https://github.com). +> **Decisions:** +> We have to decide whether to use the git CLI or a git library. Zed uses a git library but its blame implementation is too slow for a code editor, so we should use the CLI's porcelain interface. + +## 3. What else does this affect? + +Walk through this list before you start building. Not everything will apply: + +- **Actions & keybindings.** What actions does your feature define? Do the default keybindings conflict with existing ones? +- **Settings.** Is any behavior configurable? Per-user vs. per-project vs. per-language? Don't forget to add new settings to the Settings UI. +- **Themes & styling.** Does this need a new semantic token? Does it look right in both light and dark mode? +- **Vim mode.** Vim users might have different expectations for this feature. +- **Remote development.** Does your feature work with remote projects? File paths, shell commands, and environment variables all might behave differently. +- **Persistence across restarts.** Should your feature's state persist across restarts? +- **Accessibility.** Is it keyboard-navigable? Are focus states clear? +- **Platform differences.** Does behavior differ on macOS, Linux, or Windows? +- **Performance.** How does it behave with large files or big projects? Are interactions instant? +- **Security.** How does this feature interact with Workspace Trust? Does it open new attack surfaces in Zed? + +If your feature touches the **editor** specifically: the editor has a lot of coexisting features — gutter elements, inline blocks, multiple cursors, folding, edit predictions, code intelligence popovers, the minimap. Test your changes with different combinations of them active. Features that work in a normal buffer might need to be disabled in a multi-buffer. + +## 4. Ship it + +Use this as the basis for your GitHub Discussion, issue, or PR description. Good product research gets everyone aligned on goals, the state of the art, and any tradeoffs we might need to consider.