mirror of
https://github.com/zulip/zulip.git
synced 2026-07-12 21:04:41 +08:00
contributor docs: Add an AI use policy.
This commit is contained in:
parent
cf7a76383d
commit
2be6c72cbb
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user