mirror of
https://github.com/zed-industries/zed.git
synced 2026-11-19 06:59:22 +01:00
Improve contribution guidelines and experience (#64296)
# Objective Both our PR template and contribution guidelines are too convoluted. This results in: - contributors missing important information because the information is buried in the contributing file - worse commit descriptions post-merge due to the most important information being buried and or a lot of boilerplate present - the PR template often being neglected by staff themselves entirely - more work for reviewers/engineer on triage here since they have to repeatedly point people at the contribution gudelines ## Solution In order to take a stab at improving this, this PR goes for the following: 1. Shrink the PR template - this aims at reducing the cognitive load looking at this and filling it out whilst preserving all the important information needed for reviewers - a lot of text has been removed to make commit messages in the repo more readable - keep text still visible as opposed to having HTML comments so that reviewers spot this and can raise ## Testing Tested this by giving it a read myself and iterating with Kirill on the final wording/sorting/organization of contents and files. ## 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 <details> <summary>The new contribution guidelines</summary> <img width="1209" height="1293" alt="grafik" src="https://github.com/user-attachments/assets/6a3f5012-7f46-48b7-add2-9f2400f01c57" /> </details> <details> <summary>The PR template in action</summary> <img width="879" height="688" alt="grafik" src="https://github.com/user-attachments/assets/87e5ad65-7ade-45b8-b8a8-8818c9a49ba8" /> </details> --- Release Notes: - N/A --------- Co-authored-by: zelenenka <241371603+zelenenka@users.noreply.github.com>
This commit is contained in:
@@ -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?
|
||||
Manually test your changes; report results, mention platforms if relevant.
|
||||
How can reviewers test this easily? Include setup and steps.
|
||||
|
||||
## Self-Review Checklist:
|
||||
## Self-review
|
||||
|
||||
- [ ] 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
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
- [ ] 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:
|
||||
|
||||
|
||||
+53
-156
@@ -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
|
||||
## AI Policy
|
||||
|
||||
The Zed culture values working code and synchronous conversations over long
|
||||
discussion threads.
|
||||
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.
|
||||
|
||||
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.**
|
||||
For that reason, we **don't accept contributions from autonomous agents**. Pull requests that appear to violate this may be closed without notice.
|
||||
|
||||
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.
|
||||
**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 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.
|
||||
|
||||
**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.
|
||||
|
||||
## 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.
|
||||
- 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
|
||||
## Sending changes
|
||||
|
||||
- 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.
|
||||
**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).
|
||||
|
||||
When preparing your PR:
|
||||
|
||||
- **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.
|
||||
|
||||
**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.
|
||||
|
||||
**Pinging maintainers by username or emailing them does not raise your PR's priority**; it takes time away from review.
|
||||
|
||||
## Resources
|
||||
|
||||
### UI/UX checklist
|
||||
|
||||
When your changes affect UI, consult this checklist:
|
||||
For UI changes, use the [UI/UX checklist](./docs/src/development/ui-checklist.md) in the development docs.
|
||||
|
||||
**Accessibility / Ergonomics**
|
||||
### Bird's-eye view of Zed
|
||||
|
||||
- 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?
|
||||
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.
|
||||
|
||||
**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)?
|
||||
|
||||
**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?
|
||||
- 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**
|
||||
|
||||
- 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)?
|
||||
|
||||
## Bird's-eye view of Zed
|
||||
|
||||
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.
|
||||
|
||||
Zed is made up of several smaller crates - let's go over those you're most likely to interact with:
|
||||
|
||||
- [`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.
|
||||
|
||||
## Packaging Zed
|
||||
### Packaging Zed
|
||||
|
||||
Check our [notes for packaging Zed](https://zed.dev/docs/development/linux#notes-for-packaging-zed).
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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 access
|
||||
|
||||
Zed stores secrets in the system keychain.
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user