diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 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? +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: - -
- Click to view showcase - -My super cool demos here - -
- ---- +- [ ] 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.md index 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 +## 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). diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 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.md index 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 access Zed stores secrets in the system keychain. diff --git a/docs/src/development/ui-checklist.md b/docs/src/development/ui-checklist.md new file mode 100644 index 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.