Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 14 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ submitted. If you'd like your PR to have the best chance of being merged:
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 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 it changes the UI, attach **screenshots** or screen recordings.
Expand All @@ -70,6 +71,7 @@ the change with code in hand.
When your changes affect UI, consult this checklist:

**Accessibility / Ergonomics**

- Do all keyboard shortcuts work as intended?
- Are shortcuts discoverable (tooltips, menus, docs)?
- Do all mouse actions work (drag, context menus, resizing, scrolling)?
Expand All @@ -78,33 +80,39 @@ When your changes affect UI, consult this checklist:
- Is it usable without a mouse (keyboard-only navigation)?

**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?
- 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 Mac?
- 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.
- 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)?
- 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**

- Are strings concise, clear, and unambiguous?
- Do we avoid internal Zed jargon that only insiders would know?

**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?
Expand All @@ -113,17 +121,18 @@ When your changes affect UI, consult this checklist:
- Are error messages actionable and consistent with Zed’s voice?

**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)?


## Things we will (probably) not merge

Although there are few hard and fast rules, typically we don't merge:

- 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.
Expand Down
Loading