diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c0b1e363ed0f04ff33c070a4a84815cece78545..0603c1c92a96e5a93a9295228dd55636a1dca0bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,67 +1,69 @@ # Contributing to Zed -Thanks for your interest in contributing to Zed, the collaborative platform that is also a code editor! +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. +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. ## Contribution ideas -If you're looking for ideas about what to work on, check out: +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!) -- Our [public roadmap](https://zed.dev/roadmap) contains a rough outline of our near-term priorities for Zed. -- Our [top-ranking issues](https://github.com/zed-industries/zed/issues/5393) based on votes by the community. - -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). - -## Proposing changes - -The best way to propose a change is to [start a discussion on our GitHub repository](https://github.com/zed-industries/zed/discussions). - -First, write a short **problem statement**, which _clearly_ and _briefly_ describes the problem you want to solve independently from any specific solution. It doesn't need to be long or formal, but it's difficult to consider a solution in absence of a clear understanding of the problem. - -Next, write a short **solution proposal**. How can the problem (or set of problems) you have stated above be addressed? What are the pros and cons of your approach? Again, keep it brief and informal. This isn't a specification, but rather a starting point for a conversation. +In particular we love PRs that are: -By effectively engaging with the Zed team and community early in your process, we're better positioned to give you feedback and understand your pull request once you open it. If the first thing we see from you is a big changeset, we're much less likely to respond to it in a timely manner. +* Fixes to existing bugs and issues. +* Small enhancements to existing features, particularly to make them work for more people. +* Small extra features, like keybindings or actions you miss from other editors or extensions. +* Work towards shipping larger features on our roadmap. -## Pair programming +If you're looking for concrete ideas: -We plan to set aside time each week to pair program with contributors on promising pull requests in Zed. This will be an experiment. We tend to prefer pairing over async code review on our team, and we'd like to see how well it works in an open source setting. If we're finding it difficult to get on the same page with async review, we may ask you to pair with us if you're open to it. The closer a contribution is to the goals outlined in our roadmap, the more likely we'll be to spend time pairing on it. - -## Mandatory PR contents - -Please ensure the PR contains - -- Before & after screenshots, if there are visual adjustments introduced. - -Examples of visual adjustments: tree-sitter query updates, UI changes, etc. +- Our [top-ranking issues](https://github.com/zed-industries/zed/issues/5393) based on votes by the community. +- Our [public roadmap](https://zed.dev/roadmap) contains a rough outline of our near-term priorities for Zed. -- A disclosure of the AI assistance usage, if any was used. +## Sending changes -Any kind of AI assistance must be disclosed in the PR, along with the extent to which AI assistance was used (e.g. docs only vs. code generation). +The Zed culture values working code and synchronous conversations over long +discussion threads. -If the PR responses are being generated by an AI, disclose that as well. +The best way to get us to take a look at a proposed change is to send a pull +request. We will get back to you (though this sometimes takes longer than we'd +like, sorry). -As a small exception, trivial tab-completion doesn't need to be disclosed, as long as it's limited to single keywords or short phrases. +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: -## Tips to improve the chances of your PR getting reviewed and merged +* Include a clear description of what you're solving, and why it's important to you. +* Include tests. +* If it changes the UI, attach screenshots or screen recordings. -- Discuss your plans ahead of time with the team -- Small, focused, incremental pull requests are much easier to review -- Spend time explaining your changes in the pull request body -- Add test coverage and documentation -- Choose tasks that align with our roadmap -- Pair with us and watch us code to learn the codebase -- Low effort PRs, such as those that just re-arrange syntax, won't be merged without a compelling justification +The internal advice for reviewers is as follows: +* 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. -## File icons +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. -Zed's default icon theme consists of icons that are hand-designed to fit together in a cohesive manner. +If you are making a larger change, or need advice on how to finish the change +you're making, please open the PR early. We would love to help you get +things right, and it's often easier to see how to solve a problem before the +diff gets too big. -We do not accept PRs for file icons that are just an off-the-shelf SVG taken from somewhere else. +## Things we will (probably) not merge -### Adding new icons to the Zed icon theme +Although there are few hard and fast rules, typically we don't merge: -If you would like to add a new icon to the Zed icon theme, [open a Discussion](https://github.com/zed-industries/zed/discussions/new?category=ux-and-design) and we can work with you on getting an icon designed and added to Zed. +* 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). +* 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. +* Giant refactorings. +* Non-trivial changes with no tests. +* Features where (in our subjective opinion) the extra complexity isn't worth it for the number of people who will benefit. +* Anything that seems completely AI generated. ## Bird's-eye view of Zed