Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
Improve contribution guidelines and experience (#64296)
Finn Everse52ab15eac51
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex a948bb5acad..c8f3e56f37a 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -1,45 +1,19 @@-# Objective+## Summary-- Describe the objective or issue this PR addresses.-- If you're fixing a specific issue, use "Fixes #X" for each issue as [described in the GitHub docs](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword).--## Solution--- Describe the solution used to achieve the objective above.+What problem does this solve, how, and why does this change matter?+Use "Closes #123" for each issue resolved.+Include artifacts produced when testing: before/after screenshots, GIFs, videos, benchmarks.## Testing-- Did you test these changes? If so, how?-- Are there any parts that need more testing?-- How can other people (reviewers) test your changes? Is there anything specific they need to know?-- If relevant, what platforms did you test these changes on, and are there any important ones you can't test?--## Self-Review Checklist:--- [ ] I've reviewed my own diff for quality, security, and reliability-- [ ] Unsafe blocks (if any) have justifying comments-- [ ] The content adheres to Zed's UI standards ([UX/UI](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md#uiux-checklist) and [icon](https://github.com/zed-industries/zed/blob/main/crates/icons/README.md) guidelines)-- [ ] Tests cover the new/changed behavior-- [ ] Performance impact has been considered and is acceptable--## Showcase--> This section is optional. If this PR does not include a visual change or does not add a new user-facing feature, you can delete this section.--- Help others understand the result of this PR by showcasing your awesome work!-- If this PR includes a visual change, consider adding a screenshot, GIF, or video- - A before/after comparison is very useful for changes to existing features!--While a showcase should aim to be brief and digestible, you can use a toggleable section to save space on longer showcases:--<details>- <summary>Click to view showcase</summary>--My super cool demos here+Manually test your changes; report results, mention platforms if relevant.+How can reviewers test this easily? Include setup and steps.-</details>+## Self-review----+- [ ] I've reviewed my diff for quality, security, reliability, and performance.+- [ ] UI changes follow the [checklist](https://zed.dev/docs/development/ui-checklist).+- [ ] Tests cover the new or changed behavior.Release Notes:diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex ab0ad8a5085..a80791c97d6 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -2,185 +2,82 @@Thank you for helping us make Zed better!-All activity in Zed forums is subject to our [Code of-Conduct](https://zed.dev/code-of-conduct). Additionally, contributors must sign-our [Contributor License Agreement](https://zed.dev/cla) before their-contributions can be merged.+## Before you start-## Contribution ideas+- **Keep no more than three PRs open at a time.**+ This limit helps us keep up with reviews and ensures all contributors get a fair share of our reviewing capacity.+ Start with one and see it through; we're lucky to get a lot of contributions, and the pattern we've seen is that landing your first PR dramatically improves the odds for every PR after it.+ A stack of open PRs on the other hand tends to go stale as `main` changes.+- **Discuss features with us before you start writing code for them**.+ If there isn't a GitHub issue with staff confirmation that we want it, start a [GitHub discussion](https://github.com/zed-industries/zed/discussions), not a PR or a new issue.+ This especially applies to changes to the Zed Extension API.+ - Before proposing a larger feature, read the [Zed Feature Process](./docs/src/development/feature-process.md) for the context, integration points, and design decisions to cover.-Zed is a large project with a number of priorities. We spend most of-our time working on what we believe the product needs, but we also love working-with the community to improve the product in ways we haven't thought of (or had time to get to yet!)+All activity in Zed forums is subject to our [Code of Conduct](https://zed.dev/code-of-conduct).-In particular **we love PRs that are**:+### Things we will (probably) not merge-- Fixing or extending the **docs**.-- Fixing **bugs**.-- **Small** enhancements to existing features to **make them work for more people** (making things work on more platforms/modes/whatever).-- **Small** extra features, like keybindings or actions you miss from other editors or extensions.-- Part of a **Community Program** like [Let's Git Together](https://github.com/zed-industries/zed/issues/41541) or [The Guild](https://zed.dev/community/guild).-- Features we **explicitly called out as open to community contributions**+There are few hard-and-fast rules, but we typically don't merge:-If you're looking for concrete ideas:+- **Changes that can be provided by an extension**, such as new languages or themes. See the [extension development docs](https://zed.dev/docs/extensions/developing-extensions).+- **Extension API changes without prior discussion** involving Zed staff.+- **New file icons.** Our default icons are hand-designed to fit together; please don't submit off-the-shelf SVGs.+- **Features whose complexity outweighs their benefit**, in our judgement, for the number of people who would use them.+- **Giant refactorings.**+- **Non-trivial changes without tests.**+- **Style-only code changes that don't alter app logic.** Reducing allocations, removing `.unwrap()`s, and fixing typos are welcome; making code "more readable" alone may not be.+- **LLM-generated work the author doesn't understand.**-- [Docs issues](https://github.com/zed-industries/zed/issues?q=is%3Aissue%20state%3Aopen%20type%3ADocs)-- Issues suitable for [first-time contributors](https://github.com/zed-industries/zed/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22.contrib%2Fgood%20first%20issue%22) and [returning contributors](https://github.com/zed-industries/zed/issues?q=state%3Aopen%20label%3A%22.contrib%2Fgood%20non-first%20issue%22)-- [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)-- [The board with the features](https://github.com/orgs/zed-industries/projects/78/views/4) we explicitly invited the community's contributions for.+### We love PRs that...-**Thinking about proposing or building a larger feature? Don't start with a PR**, start with reading 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. The right place for the proposals is [GitHub discussions](https://github.com/zed-industries/zed/discussions) (not GitHub issues).+- **Fix or extend the docs**: browse [docs issues](https://github.com/zed-industries/zed/issues?q=is%3Aissue%20state%3Aopen%20type%3ADocs).+- **Close issues curated for the community:** [good first issues](https://github.com/zed-industries/zed/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22.contrib%2Fgood%20first%20issue%22), [good non-first issues](https://github.com/zed-industries/zed/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22.contrib%2Fgood%20non-first%20issue%22).+- **Fix bugs**: start with [triaged bugs with confirmed reproduction steps](https://github.com/zed-industries/zed/issues?q=is%3Aissue%20state%3Aopen%20type%3ABug%20label%3Astate%3Areproducible), or browse [area labels](https://github.com/zed-industries/zed/labels?q=area%3A*) for parts of Zed you care about.+ Select a label, then add `type:Bug` to the search.+- **Make existing features work for more people** through small enhancements, such as support for more platforms or modes.+- **Add small features**, like keybindings or actions you miss from other editors.+- **Join a Community Program** like [Let's Git Together](https://github.com/zed-industries/zed/issues/41541) or [The Guild](https://zed.dev/community/guild).+- **Build features we've explicitly invited contributions for**, listed on the [community feature board](https://github.com/orgs/zed-industries/projects/78/views/4).-## Sending changes--The Zed culture values working code and synchronous conversations over long-discussion threads.--The best way to get us to take a look at a proposed change (excluding new features) is to send a pull request. We will get back to you (though this sometimes takes longer than we'd like, sorry). **Pinging the maintainers by their username or writing them emails spends their time but does not bump the priority of a particular PR.**--If you need more feedback from us: the best way is to be responsive to-GitHub comments, or to offer up time to pair with us.--If you need help deciding how to fix a bug, or finish implementing a feature-that we've agreed we want, please open a PR early so we can discuss how to make-the change with code in hand.--Although we will take a look, we tend to only merge about half the PRs that are-submitted. **If you'd like your PR to have the best chance of being merged**:--- Make sure the change is **desired**: we're always happy to accept bugfixes,- but **features should be confirmed with us first** if you aim to avoid wasted- effort. If there isn't already a GitHub issue for your feature with staff- confirmation that we want it, start with a [GitHub discussion](https://github.com/zed-industries/zed/discussions) rather than a PR.- - This especially applies to any changes proposed to the Zed Extension API.-- Include a clear description of **what you're solving**, and why it's important.-- Include **tests**. For UI changes, consider updating visual regression tests (see [Building Zed for macOS](./docs/src/development/macos.md#visual-regression-tests)).-- If the change is visible in the UI, attach **screenshots or screen recordings**.-- Make the PR about **one thing only**, e.g. if it's a bugfix, don't add two- features and a refactoring on top of that.-- Keep AI assistance under your judgement and responsibility: it's unlikely- we'll merge a vibe-coded PR that the author doesn't understand.+## AI Policy-**A note on open pull requests:** currently we cap them at **three per author**.-We're lucky to get a lot of contributions, and the pattern we've seen is that landing-your first PR dramatically improves the odds for every PR after it. A stack of-simultaneous PRs, by contrast, tends to just sit and rot against a moving `main`-branch. It's better to start with one, see it through, then bring on the next.-It also keeps things sane when the contributions are coming in faster than we can-review them, including the occasional automated burst.+We welcome the use of LLMs for coding, but we hold a high bar for all contributions, and **we expect a human in the loop who genuinely understands the work an LLM produces** on their behalf.-## Things we will (probably) not merge+For that reason, we **don't accept contributions from autonomous agents**. Pull requests that appear to violate this may be closed without notice.-Although there are few hard and fast rules, **typically we don't merge**:+**Don't rely on LLMs to write the whole thing for you when communicating with the maintainers** (meaning replies to comments, PR descriptions, and alike). The readers are humans, and we'd like to hear from you, not from a model (we have models at home).-- Anything that can be provided by an extension. For example a new language, or theme. For adding themes or support for a new language to Zed, check out our [docs on developing extensions](https://zed.dev/docs/extensions/developing-extensions).-- Changes to the Zed Extension API submitted without prior discussion involving Zed staff.-- New file icons. Zed's default icon theme consists of icons that are hand-designed to fit together in a cohesive manner, please don't submit PRs with off-the-shelf SVGs.-- Features where (in our subjective opinion) the extra complexity isn't worth it for the number of people who will benefit.-- Giant refactorings.-- Non-trivial changes with no tests.-- Stylistic code changes that do not alter any app logic. Reducing allocations, removing `.unwrap()`s, fixing typos is great; making code "more readable" — maybe not so much.-- Anything that seems AI-generated without understanding the output.--### AI Policy--We welcome the use of LLMs for coding, but we hold a high bar for all contributions, and **we expect a human in the loop who genuinely understands the work an LLM produces** on their behalf. For that reason, we **don't accept contributions from autonomous agents**. Pull requests that appear to violate this may be closed, sometimes without notice.--**Don't rely on LLMs to write the whole thing for you when communicating with the maintainers** (meaning replies to comments, PR descriptions, and alike). The readers are humans, and we'd like to hear from you, not from a model (we have models at home). If you're a non-native English speaker using an LLM to thoroughly edit or translate your messages to the maintainers, we'd encourage you to **put the machine translation in a quote block and include the original text in your native language after it**.+If you're a non-native English speaker using an LLM to thoroughly edit or translate your messages to the maintainers, we'd encourage you to **put the machine translation in a quote block and include the original text in your native language after it**.If you think it's helpful/necessary to **share context from a chat with an LLM**, please put the **relevant part of it** in a quote block (e.g., using `>`), **disclose it as AI-generated**, and add your own commentary explaining **why it's relevant and what you take from it**.This policy was adapted from [ripgrep's AI policy](https://github.com/BurntSushi/ripgrep/blob/f0cec341ab95c25c691ad3d5754d4bd9eedde21f/AI_POLICY.md).-### Internal advice for reviewers--- If the fix/feature is obviously great, and the code is great. Hit merge.-- If the fix/feature is obviously great, and the code is nearly great. Send PR comments, or offer to pair to get things perfect.-- If the fix/feature is not obviously great, or the code needs rewriting from scratch. Close the PR with a thank you and some explanation.--### UI/UX checklist--When your changes affect UI, consult this checklist:--**Accessibility / Ergonomics**--- Do all keyboard shortcuts work as intended?-- Are shortcuts discoverable (tooltips, menus, docs)?-- Is it usable without a mouse (keyboard-only navigation)?-- Do all mouse actions work (drag, context menus, resizing, scrolling)?-- Does the feature look great in light and dark mode themes?-- Are hover states and focus indicators clear and consistent?--**Responsiveness**--- Does the UI scale gracefully on:- - Narrow panes (e.g., side-by-side split views)?- - Short panes (e.g., laptops with 13" displays)?- - High-DPI / Retina displays?-- Does resizing panes or windows keep the UI usable and attractive?-- Do dialogs or modals stay centered and within viewport bounds?--**Platform Consistency**--- Is the feature fully usable on Windows, Linux, and macOS?-- Does it respect system-level settings (fonts, scaling, input methods)?--**Performance**--- All user interactions must have instant feedback.- - If the user requests something slow (e.g. an LLM generation) there should be some indication of the work in progress.-- Does it handle large files, big projects, or heavy workloads without degrading?-- Frames must take no more than 8ms (120fps)--**Consistency**--- Does it match Zed’s design language (spacing, typography, icons)?- - Make sure to visit [the icon design guidelines](https://github.com/zed-industries/zed/blob/main/crates/icons/README.md)-- Are terminology, labels, and tone consistent with the rest of Zed?-- Are interactions consistent (e.g., how tabs close, how modals dismiss, how errors show)?+## Sending changes-**Internationalization & Text**+**Build and run Zed locally, then manually test your changes before opening a PR.** Follow the guide for [macOS](./docs/src/development/macos.md), [Linux](./docs/src/development/linux.md), [Windows](./docs/src/development/windows.md), or [FreeBSD](./docs/src/development/freebsd.md).-- Are strings concise, clear, and unambiguous?-- Do we avoid internal Zed jargon that only insiders would know?+When preparing your PR:-**User Paths & Edge Cases**+- **Review your own work**, including any AI-assisted code. Follow the [pull request template](./.github/pull_request_template.md?plain=1) for testing details and the self-review checklist.+- **For visual changes, attach screenshots or a video** and work through the [UI/UX checklist](./docs/src/development/ui-checklist.md). For non-visual improvements and changes, include benchmarks or other artifacts produced when testing.+- **Keep each PR about one thing**, leaving unrelated features and refactoring for another PR.+- **Sign the [Contributor License Agreement](https://zed.dev/cla)** so that your contribution can be merged.-- What does the happy path look like?-- What does the unhappy path look like? (errors, rejections, invalid states)-- How does it work in offline vs. online states?-- How does it work in unauthenticated vs. authenticated states?-- How does it behave if data is missing, corrupted, or delayed?-- Are error messages actionable and consistent with Zed’s voice?+**Opening a PR does not guarantee a merge.** We may decline a change that doesn't fit Zed's direction or quality standards, even after you've put work into it. Confirming interest early and following this guide give your PR the best chance.-**Discoverability & Learning**+**Pinging maintainers by username or emailing them does not raise your PR's priority**; it takes time away from review.-- Can a first-time user figure it out without docs?-- Is there an intuitive way to undo/redo actions?-- Are power features discoverable but not intrusive?-- Is there a path from beginner → expert usage (progressive disclosure)?+## Resources-## Bird's-eye view of Zed+### UI/UX checklist-We suggest you keep the [Zed glossary](docs/src/development/glossary.md) at your side when starting out. It lists and explains some of the structures and terms you will see throughout the codebase.+For UI changes, use the [UI/UX checklist](./docs/src/development/ui-checklist.md) in the development docs.-Zed is made up of several smaller crates - let's go over those you're most likely to interact with:+### Bird's-eye view of Zed-- [`gpui`](/crates/gpui) is a GPU-accelerated UI framework which provides all of the building blocks for Zed. **We recommend familiarizing yourself with the root level GPUI documentation.**-- [`editor`](/crates/editor) contains the core `Editor` type that drives both the code editor and all various input fields within Zed. It also handles a display layer for LSP features such as Inlay Hints or code completions.-- [`project`](/crates/project) manages files and navigation within the filetree. It is also Zed's side of communication with LSP.-- [`workspace`](/crates/workspace) handles local state serialization and groups projects together.-- [`vim`](/crates/vim) is a thin implementation of Vim workflow over `editor`.-- [`lsp`](/crates/lsp) handles communication with external LSP server.-- [`language`](/crates/language) drives `editor`'s understanding of language - from providing a list of symbols to the syntax map.-- [`collab`](/crates/collab) is the collaboration server itself, driving the collaboration features such as project sharing.-- [`rpc`](/crates/rpc) defines messages to be exchanged with collaboration server.-- [`theme`](/crates/theme) defines the theme system and provides a default theme.-- [`ui`](/crates/ui) is a collection of UI components and common patterns used throughout Zed.-- [`cli`](/crates/cli) is the CLI crate which invokes the Zed binary.-- [`zed`](/crates/zed) is where all things come together, and the `main` entry point for Zed.+For a tour of the main crates, see the [codebase overview](https://zed.dev/docs/development#birds-eye-view-of-zed) in the development docs.-## Packaging Zed+### Packaging ZedCheck our [notes for packaging Zed](https://zed.dev/docs/development/linux#notes-for-packaging-zed).diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.mdindex 9e8ac08058c..44c42fc3cc7 100644--- a/docs/src/SUMMARY.md+++ b/docs/src/SUMMARY.md@@ -229,6 +229,7 @@- [FreeBSD](./development/freebsd.md)- [Using Debuggers](./development/debuggers.md)- [Performance](./performance.md)+ - [UI/UX Checklist](./development/ui-checklist.md)- [Glossary](./development/glossary.md)- [Release Notes](./development/release-notes.md)- [Debugging Crashes](./development/debugging-crashes.md)diff --git a/docs/src/development.md b/docs/src/development.mdindex 73e77f2a9f8..b5d40d8b7a0 100644--- a/docs/src/development.md+++ b/docs/src/development.md@@ -11,6 +11,26 @@ See the platform-specific instructions for building Zed from source:- [Linux](./development/linux.md)- [Windows](./development/windows.md)+## Bird's-eye view of Zed {#birds-eye-view-of-zed}++Keep the [Zed glossary](./development/glossary.md) handy when starting out. It explains structures and terms you'll see throughout the codebase.++Zed is made up of several smaller crates. Here are the ones you're most likely to work with:++- [`gpui`](https://github.com/zed-industries/zed/tree/main/crates/gpui) is a GPU-accelerated UI framework which provides all of the building blocks for Zed. **We recommend familiarizing yourself with the root level GPUI documentation.**+- [`editor`](https://github.com/zed-industries/zed/tree/main/crates/editor) contains the core `Editor` type that drives both the code editor and all various input fields within Zed. It also handles a display layer for LSP features such as Inlay Hints or code completions.+- [`project`](https://github.com/zed-industries/zed/tree/main/crates/project) manages files and navigation within the filetree. It is also Zed's side of communication with LSP.+- [`workspace`](https://github.com/zed-industries/zed/tree/main/crates/workspace) handles local state serialization and groups projects together.+- [`vim`](https://github.com/zed-industries/zed/tree/main/crates/vim) is a thin implementation of Vim workflow over `editor`.+- [`lsp`](https://github.com/zed-industries/zed/tree/main/crates/lsp) handles communication with external LSP server.+- [`language`](https://github.com/zed-industries/zed/tree/main/crates/language) drives `editor`'s understanding of language - from providing a list of symbols to the syntax map.+- [`collab`](https://github.com/zed-industries/zed/tree/main/crates/collab) is the collaboration server itself, driving the collaboration features such as project sharing.+- [`rpc`](https://github.com/zed-industries/zed/tree/main/crates/rpc) defines messages to be exchanged with collaboration server.+- [`theme`](https://github.com/zed-industries/zed/tree/main/crates/theme) defines the theme system and provides a default theme.+- [`ui`](https://github.com/zed-industries/zed/tree/main/crates/ui) is a collection of UI components and common patterns used throughout Zed.+- [`cli`](https://github.com/zed-industries/zed/tree/main/crates/cli) is the CLI crate which invokes the Zed binary.+- [`zed`](https://github.com/zed-industries/zed/tree/main/crates/zed) is where all things come together, and the `main` entry point for Zed.+## Keychain accessZed stores secrets in the system keychain.diff --git a/docs/src/development/ui-checklist.md b/docs/src/development/ui-checklist.mdnew file mode 100644index 00000000000..8b03c4c2cb8--- /dev/null+++ b/docs/src/development/ui-checklist.md@@ -0,0 +1,68 @@+---+title: UI/UX Checklist+description: Review UI changes for accessibility, responsiveness, consistency, and performance.+---++# UI/UX checklist++Use this checklist when your changes affect UI.++## Accessibility / Ergonomics {#accessibility-ergonomics}++- Do all keyboard shortcuts work as intended?+- Are shortcuts discoverable (tooltips, menus, docs)?+- Is it usable without a mouse (keyboard-only navigation)?+- Do all mouse actions work (drag, context menus, resizing, scrolling)?+- Does the feature look great in light and dark mode themes?+- Are hover states and focus indicators clear and consistent?++## Responsiveness {#responsiveness}++- Does the UI scale gracefully on:+ - Narrow panes (e.g., side-by-side split views)?+ - Short panes (e.g., laptops with 13" displays)?+ - High-DPI / Retina displays?+- Does resizing panes or windows keep the UI usable and attractive?+- Do dialogs or modals stay centered and within viewport bounds?++## Platform Consistency {#platform-consistency}++- Is the feature fully usable on Windows, Linux, and macOS?+- Does it respect system-level settings (fonts, scaling, input methods)?++## Performance {#performance}++- All user interactions must have instant feedback.+ - If the user requests something slow (e.g. an LLM generation) there should be some indication of the work in progress.+- Does it handle large files, big projects, or heavy workloads without degrading?+- Frames must take no more than 8ms (120fps)++## Consistency {#consistency}++- Does it match Zed’s design language (spacing, typography, icons)?+ - Make sure to visit [the icon design guidelines](https://github.com/zed-industries/zed/blob/main/crates/icons/README.md)+- Are terminology, labels, and tone consistent with the rest of Zed?+- Are interactions consistent (e.g., how tabs close, how modals dismiss, how errors show)?++## Internationalization & Text {#internationalization-text}++- Are strings concise, clear, and unambiguous?+- Do we avoid internal Zed jargon that only insiders would know?++## User Paths & Edge Cases {#user-paths-edge-cases}++- What does the happy path look like?+- What does the unhappy path look like? (errors, rejections, invalid states)+- How does it work in offline vs. online states?+- How does it work in unauthenticated vs. authenticated states?+- How does it behave if data is missing, corrupted, or delayed?+- Are error messages actionable and consistent with Zed’s voice?++## Discoverability & Learning {#discoverability-learning}++- Can a first-time user figure it out without docs?+- Is there an intuitive way to undo/redo actions?+- Are power features discoverable but not intrusive?+- Is there a path from beginner → expert usage (progressive disclosure)?++See the [contribution guidelines](https://github.com/zed-industries/zed/blob/main/CONTRIBUTING.md) for preparing your pull request.