diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e7e7629825b5f4..685eaf39a2d01a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. @@ -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)? @@ -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? @@ -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.