diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3288444b73..b3e7fa645f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,7 +36,8 @@ excited to: a request for time and attention from Zulip’s maintainers. Successful contributors put in the reasoning and writing effort required to [communicate][how we communicate] clearly and succinctly, and don’t waste the - community’s time with AI slop. + community’s time with AI slop. See our [AI use policy and + guidelines](#ai-use-policy-and-guidelines). - **Communicate in the open.** Technical and product decisions are discussed openly in the [Zulip development community](https://zulip.com/development-community/) and [on @@ -64,12 +65,13 @@ your first pull request, diving into [Zulip's subsystems](https://zulip.readthedocs.io/en/latest/subsystems/index.html), and much more. We hope you'll find this process to be a great learning experience. -This page will guide you through the following steps: +This page will guide you through the following topics: 1. [Getting started](#getting-started) 1. [Finding an issue to work on](#finding-an-issue-to-work-on) 1. [Getting help](#getting-help) as you work on your first pull request 1. Learning [best practices](#best-practices) +1. [AI use policy and guidelines](#ai-use-policy-and-guidelines) 1. [Submitting a pull request](#submitting-a-pull-request) 1. [Going beyond the first issue](#beyond-the-first-issue) @@ -336,6 +338,82 @@ to keep in mind. [great-questions]: https://zulip.readthedocs.io/en/latest/contributing/asking-great-questions.html +## AI use policy and guidelines + +Our goal in the Zulip project is to develop an excellent software +system. This requires careful attention to detail in every change we +integrate. Maintainer time and attention is very limited, so it's +important that changes that contributors ask us to review represent +that contributor's best work. + +Contributors are encouraged to use tools that help them write good +code, including AI tools. However, as noted above, you always need to +understand and explain the changes you're proposing to make, whether +or not you used an LLM as part of your process to produce them. The +answer to “Why did you make change X?” should never be “I'm not sure. +The AI did it.” + +**Do not submit an AI-generated PR you haven't personally understood and +tested**, as this wastes maintainers' time. PRs that appear to violate this +guideline will be closed without review. + +### Using AI as a coding assistant + +1. Don't skip **becoming familiar with the part of the codebase** + you're working on. This will let you write better prompts and + validate their output if you use an LLM. Code assistants can be a + useful search engine/discovery tool in this process, but don't + trust claims they make about how Zulip works. LLMs are often wrong, + even about details that are clearly answered in the Zulip + documentation. +1. Don't submit a bunch of LLM-proposed changes that easily reviewed + together as a single commit. Split up your changes into **[coherent + commits](https://zulip.readthedocs.io/en/latest/contributing/commit-discipline.html)**. +1. Don't simply ask an LLM to add **code comments**, as it will likely + produce a bunch of text that unnecessarily explains what's already + clear from the code. If using an LLM to generate comments, be + really specific in your request, demand succinctness, and carefully + edit the result. + +### Using AI for communication + +As noted above, Zulip's contributors are expected to communicate with +intention, to avoid wasting maintainer time with long, sloppy +writing. We strongly prefer clear and concise communication about +points that actually require discussion over long AI-generated +comments. + +When you use an LLM to write a message for you, it remains **your +responsibility** to read through the whole thing and make sure it +makes sense to you and it represents your ideas concisely. A good rule +of thumb is that if you can't make yourself carefully read a given LLM +output that you generated, nobody else wants to read it either. + +Here are some concrete guidelines for using LLMs as part of your communication +workflows. + +1. When writing a pull request description, **do not include anything that's + obvious** from looking at your changes directly (e.g., files changed, functions + updated, etc.). Instead, focus on the _why_ behind your changes. Don't ask an + LLM to generate a PR description on your behalf based on your code changes, + as it will simply regurgitate the information that's already there. +1. Similarly, when responding to a pull request comment, **explain _your_ + reasoning**. Don't prompt an LLM to re-describe what can already be seen from + the code. +1. Complete all parts of the **PR description template**, including screenshots + and the self-review checklist. Don't simply overwrite the template with LLM + output. +1. **Clarity and succinctness** are much more important than perfect grammar, so + you shouldn't feel obliged to pass your writing through an LLM. If you do ask + an LLM to clean up your writing style, be sure it does _not_ make it longer + in the process. Demand succinctness in your prompt. +1. Quoting an LLM answer is usually less helpful than linking to + **relevant primary sources**, like source code, reference + documentation or web standards. If you do need to quote an LLM + answer in a Zulip conversation, put the answer in a [Zulip quote + block](https://zulip.com/help/format-a-quote), to distinguish LLM + output from your own thoughts. + ## Submitting a pull request See the [guide on submitting a pull