Skip to content

Commit 46ebf7c

Browse files
authored
Include additional AI usage guidelines
1 parent abf9ba1 commit 46ebf7c

1 file changed

Lines changed: 52 additions & 31 deletions

File tree

CONTRIBUTING.md

Lines changed: 52 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -99,15 +99,11 @@ case you are looking for some examples:
9999
Once a pull request is sent, the Elixir team will review your changes.
100100
We outline our process below to clarify the roles of everyone involved.
101101

102-
All pull requests must be approved by two committers before being merged into
103-
the repository. If changes are necessary, the team will leave appropriate
104-
comments requesting changes to the code. Unfortunately, we cannot guarantee a
105-
pull request will be merged, even when modifications are requested, as the Elixir
106-
team will re-evaluate the contribution as it changes.
107-
108-
Committers may also push style changes directly to your branch. If you would
109-
rather manage all changes yourself, you can disable the "Allow edits from maintainers"
110-
feature when submitting your pull request.
102+
All pull requests must be reviewed before being merged into the repository.
103+
If changes are necessary, the team will leave appropriate comments requesting
104+
changes to the code. Unfortunately, we cannot guarantee a pull request will
105+
be merged, even when modifications are requested, as the Elixir team will
106+
re-evaluate the contribution as it changes.
111107

112108
The Elixir team may optionally assign someone to review a pull request.
113109
If someone is assigned, they must explicitly approve the code before
@@ -118,6 +114,29 @@ into the repository. If you have carefully organized your commits and
118114
believe they should be merged without squashing, please mention it in
119115
a comment.
120116

117+
## Building documentation
118+
119+
Building the documentation requires that [ExDoc](https://github.com/elixir-lang/ex_doc)
120+
is installed and built alongside Elixir.
121+
122+
After cloning and compiling Elixir, run:
123+
124+
```sh
125+
elixir_dir=$(pwd)
126+
cd .. && git clone https://github.com/elixir-lang/ex_doc.git
127+
cd ex_doc && "${elixir_dir}/bin/elixir" "${elixir_dir}/bin/mix" do deps.get + compile
128+
129+
# Now we will go back to Elixir's root directory,
130+
cd "${elixir_dir}"
131+
132+
# and generate HTML and EPUB documents:
133+
make docs
134+
```
135+
136+
This will produce documentation sets for `elixir`, `eex`, `ex_unit`, `iex`, `logger`,
137+
and `mix` under the `doc` directory. If you are planning to contribute documentation,
138+
[please check our best practices for writing documentation](https://hexdocs.pm/elixir/writing-documentation.html).
139+
121140
## Licensing and Compliance Requirements
122141

123142
Please review our [Open Source Policy](OPEN_SOURCE_POLICY.md) for complete
@@ -181,30 +200,37 @@ affecting **all external contributors**:
181200
See <https://developercertificate.org/> for a copy of the Developer Certificate
182201
of Origin license.
183202

184-
## Building documentation
203+
## Using AI and coding agents
185204

186-
Building the documentation requires that [ExDoc](https://github.com/elixir-lang/ex_doc)
187-
is installed and built alongside Elixir.
205+
While we allow the use of AI on contributions and discussions, please be mindful
206+
when doing so. Generally speaking, Elixir maintainers already have access to AI
207+
(like many other developers). Therefore, if we need the feedback or help of a
208+
coding agent, we can request so ourselves. For this reason, we often find
209+
the point of view of the human behind the agent more valuable.
188210

189-
After cloning and compiling Elixir, run:
211+
That said, here are examples of how one might (or might not) use AI and coding
212+
agents in Elixir spaces:
190213

191-
```sh
192-
elixir_dir=$(pwd)
193-
cd .. && git clone https://github.com/elixir-lang/ex_doc.git
194-
cd ex_doc && "${elixir_dir}/bin/elixir" "${elixir_dir}/bin/mix" do deps.get + compile
214+
* When it comes to discussions, using AI to help express yourself is welcome,
215+
but avoid directly copy and pasting AI generated content. If there is a language
216+
barrier, use AI to translate or review your text, but do not use AI to respond
217+
on your behalf.
195218

196-
# Now we will go back to Elixir's root directory,
197-
cd "${elixir_dir}"
219+
* Do not use coding agents to tackle existing issues unless they have the
220+
"Contributions Welcome" label.
198221

199-
# and generate HTML and EPUB documents:
200-
make docs
201-
```
222+
* If you request a feature on the mailing list and it is accepted, you may
223+
use coding agents to implement it, as long as it follows the AI Contributions
224+
guidelines below.
202225

203-
This will produce documentation sets for `elixir`, `eex`, `ex_unit`, `iex`, `logger`,
204-
and `mix` under the `doc` directory. If you are planning to contribute documentation,
205-
[please check our best practices for writing documentation](https://hexdocs.pm/elixir/writing-documentation.html).
226+
* When automating AI usage on the Elixir codebase for performance improvements
227+
or security fixes, pair it with a separate set of agents whose job is to argue
228+
against and try to invalidate any proposed change. And treat their approval as
229+
advisory: a human must still validate it before opening issues or pull requests.
206230

207-
## AI contributions
231+
If any code is written by AI, then you must follow the guidelines below.
232+
233+
### AI contributions
208234

209235
AI agents MUST NOT add Signed-off-by tags. Only humans can legally certify the Developer
210236
Certificate of Origin (DCO). The human submitter is responsible for:
@@ -220,8 +246,3 @@ AI in the development process. Contributions should include an Assisted-by tag i
220246
following format:
221247

222248
Assisted-by: AGENT_NAME:MODEL_VERSION
223-
224-
When it comes to discussions, please be mindful about the use of AI. Using AI to help
225-
express yourself is welcome but avoid simply copy and pasting large AI generated content.
226-
Elixir maintainers also have access to coding agents and, if they need feedback from an
227-
agentic systems, they can request such themselves.

0 commit comments

Comments
 (0)