Contributing to Elixir

We invite contributions to Elixir. To contribute, there are a few things you need to know about the code. First, Elixir code is divided by each application inside the lib folder:

• elixir - Elixir's kernel and standard library

• eex - EEx is the template engine that allows you to embed Elixir

• ex_unit - ExUnit is a simple test framework that ships with Elixir

• iex - IEx stands for Interactive Elixir: Elixir's interactive shell

• logger - Logger is the built-in logger

• mix - Mix is Elixir's build tool

You can run all tests in the root directory with make test. You can also run tests for a specific framework with make test_#{APPLICATION}, for example, make test_ex_unit. If you just changed something in Elixir's standard library, you can run only that portion through make test_stdlib.

If you are only changing one file, you can choose to compile and run tests for that specific file for faster development cycles. For example, if you are changing the String module, you can compile it and run its tests as:

bin/elixirc lib/elixir/lib/string.ex -o lib/elixir/ebin
bin/elixir lib/elixir/test/elixir/string_test.exs

Some test files need their test_helper.exs to be explicitly required before, such as:

bin/elixir -r lib/logger/test/test_helper.exs lib/logger/test/logger_test.exs

You can also use the LINE env var to run a single test:

LINE=123 bin/elixir lib/elixir/test/elixir/string_test.exs

To recompile all (including Erlang modules):

make compile

After your changes are done, please remember to run make format to guarantee all files are properly formatted, then run the full suite with make test.

If your contribution fails during the bootstrapping of the language, you can rebuild the language from scratch with:

make clean_elixir compile

Similarly, if you can not get Elixir to compile or the tests to pass after updating an existing checkout, run make clean compile. You can check the official build status. More tasks can be found by reading the Makefile.

We encourage contributors to write tests that capture both existing and newly introduced behavior, especially for bug fixes and major changes:

• Bug Fixes: If you are fixing a bug, please try to include a test that fails before your change and passes afterward. This makes it easier to confirm that the fix addresses the underlying issue and helps prevent regressions in the future.

• New Features or Major Changes: If you are adding a new feature or making major changes to existing functionality, please add tests that cover the major parts of that functionality. Aim to have the best code coverage possible.

With tests running and passing, you are ready to contribute to Elixir and send a pull request. We have saved some excellent pull requests we have received in the past in case you are looking for some examples:

• Implement Enum.member? - Pull request

• Add String.valid? - Pull request

• Implement capture_io for ExUnit - Pull request

Reviewing changes

Once a pull request is sent, the Elixir team will review your changes. We outline our process below to clarify the roles of everyone involved.

All pull requests must be reviewed before being merged into the repository. If changes are necessary, the team will leave appropriate comments requesting changes to the code. Unfortunately, we cannot guarantee a pull request will be merged, even when modifications are requested, as the Elixir team will re-evaluate the contribution as it changes.

The Elixir team may optionally assign someone to review a pull request. If someone is assigned, they must explicitly approve the code before another team member can merge it.

When the review finishes, your pull request will be squashed and merged into the repository. If you have carefully organized your commits and believe they should be merged without squashing, please mention it in a comment.

Building documentation

Building the documentation requires that ExDoc is installed and built alongside Elixir.

After cloning and compiling Elixir, run:

elixir_dir=$(pwd)
cd .. && git clone https://github.com/elixir-lang/ex_doc.git
cd ex_doc && "${elixir_dir}/bin/elixir" "${elixir_dir}/bin/mix" do deps.get + compile

# Now we will go back to Elixir's root directory,
cd "${elixir_dir}"

# and generate HTML and EPUB documents:
make docs

This will produce documentation sets for elixir, eex, ex_unit, iex, logger, and mix under the doc directory. If you are planning to contribute documentation, please check our best practices for writing documentation.

Licensing and Compliance Requirements

Please review our Open Source Policy for complete guidelines on licensing and compliance. Below is a summary of the key points affecting all external contributors:

• Accepted Licenses: Any code contributed must be licensed under the Apache-2.0 license.

• SPDX License Headers: With the exception of approved test fixture files, all new or modified files in a pull request must include correct SPDX headers. If you are creating a new file under the Apache-2.0 license, for instance, please use:

  # SPDX-License-Identifier: Apache-2.0
  # SPDX-FileCopyrightText: 2021 The Elixir Team
  

• No Executable Binaries: Contributions must not include any executable binary files. If you require an exception (for example, certain test artifacts), please see the policy on how to request approval and document exceptions.

• Preserving Copyright and License Info: If you copy code from elsewhere, ensure that all original copyright and license notices remain intact. If they are missing or incomplete, you must add them.

• Failure to Comply: Pull requests that do not meet these licensing and compliance standards will be rejected or require modifications before merging.

• Developer Certificate of Origin: All contributions are subject to the Developer Certificate of Origin.

  By making a contribution to this project, I certify that:
  
  (a) The contribution was created in whole or in part by me and I
      have the right to submit it under the open source license
      indicated in the file; or
  
  (b) The contribution is based upon previous work that, to the 
      best of my knowledge, is covered under an appropriate open 
      source license and I have the right under that license to   
      submit that work with modifications, whether created in whole
      or in part by me, under the same open source license (unless
      I am permitted to submit under a different license), as 
      Indicated in the file; or
  
  (c) The contribution was provided directly to me by some other
      person who certified (a), (b) or (c) and I have not modified
      it.
  
  (d) I understand and agree that this project and the contribution
      are public and that a record of the contribution (including 
      all personal information I submit with it, including my
      sign-off) is maintained indefinitely and may be redistributed
      consistent with this project or the open source license(s)
      involved.
  

  See https://developercertificate.org/ for a copy of the Developer Certificate of Origin license.

Using AI and coding agents

While we allow the use of AI on contributions and discussions, please be mindful when doing so. Generally speaking, Elixir maintainers already have access to AI (like many other developers). Therefore, if we need the feedback or help of a coding agent, we can request so ourselves. For this reason, we often find the point of view of the human behind the agent more valuable.

That said, here are examples of how one might (or might not) use AI and coding agents in Elixir spaces:

• When it comes to discussions, using AI to help express yourself is welcome, but avoid directly copy and pasting AI generated content. If there is a language barrier, use AI to translate, review, and improve your text, but do not use AI to respond on your behalf.

• Do not use coding agents to tackle existing issues unless they have the "Contributions Welcome" label.

• If you request a feature on the mailing list and it is accepted, you may use coding agents to implement it, as long as it follows the AI Contributions guidelines below.

• When automating AI usage on the Elixir codebase for performance improvements or security fixes, pair it with a separate set of agents whose job is to argue against and try to invalidate any proposed change. And treat their approval as advisory: a human must still validate it before opening issues or pull requests.

If any code is written by AI, then you must follow the guidelines below.

AI contributions

AI agents MUST NOT add Signed-off-by tags. Only humans can legally certify the Developer Certificate of Origin (DCO). The human submitter is responsible for:

• Reviewing all AI-generated code
• Ensuring compliance with licensing requirements
• Adding their own Signed-off-by tag to certify the DCO
• Taking full responsibility for the contribution
• Disclosing use of AI for comments and code contributions

When AI tools contribute to Elixir, proper attribution helps track the evolving role of AI in the development process. Contributions should include an Assisted-by tag in the following format:

Assisted-by: AGENT_NAME:MODEL_VERSION