contributor docs: Add an AI use policy.

This commit is contained in:
Alya Abbott 2025-11-04 13:11:45 -08:00 committed by Tim Abbott
parent cf7a76383d
commit 2be6c72cbb

View File

@ -36,7 +36,8 @@ excited to:
a request for time and attention from Zulips maintainers. Successful
contributors put in the reasoning and writing effort required to
[communicate][how we communicate] clearly and succinctly, and dont waste the
communitys time with AI slop.
communitys 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