Files
zed/CONTRIBUTING.md
Finn Evers e52ab15eac 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>
2026-09-25 15:42:49 +00:00

84 lines
6.3 KiB
Markdown

# Contributing to Zed
Thank you for helping us make Zed better!
## Before you start
- **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.
All activity in Zed forums is subject to our [Code of Conduct](https://zed.dev/code-of-conduct).
### Things we will (probably) not merge
There are few hard-and-fast rules, but we typically don't merge:
- **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.**
### We love PRs that...
- **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).
## 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 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 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).
## Sending changes
**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
For UI changes, use the [UI/UX checklist](./docs/src/development/ui-checklist.md) in the development docs.
### Bird's-eye view of 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
Check our [notes for packaging Zed](https://zed.dev/docs/development/linux#notes-for-packaging-zed).