Contributing to Elixir is a great way to learn the language and get involved in the community. You might think only rockstar developers can contribute to a language. That's the assumption I had. But my experience in contributing to Elixir proved me wrong. I learned that there are many ways to contribute and there's a place for everyone. You don't have to be a rockstar to contribute. If anything, contributing to Elixir will help you become a rockstar.

Contributing to Elixir was my first attempt at working on open source projects. I was intimidated in the beginning. However, the process turned out to be much more doable and more fun than expected. In this post, I will share everything I learned in the process as a step-by-step guide so you can start coding for Elixir in no time!

Contribute without coding

Before we dive into the details of coding for Elixir, it's worth pointing out a few ways to contribute without (much) coding:

• Try it out, tell your friends, and participate in the Elixir forum. The best way to contribute is simply to try it out and spread the word! The Elixir forum is lively. Participating in forum discussions and sharing your insights are great ways to contribute.
• Improve the documentation. As you learn and use the language, you will notice ways to improve its documentation. When you do, create a pull request! Developer experience is a big focus for Elixir. And there's no great experience without great documentation. Elixir cares about documentation so much that it's actually part of the source code. Any improvement on the documentation is a win for the community. Here are a few pull request examples:
  • Polish documentation of Kernel module
  • Add missing colon in Logger documentation
  • Correct grammar in Logger documentation
• Open issues. Help improve the language by requesting missing features or reporting bugs.
• Review open pull requests. Brow through open pull requests and help review them. You will learn about others' solutions and contribute to them at the same time. Here is an example.
• Improve existing tests. Elixir has great a test coverage. Reading its tests is a great way to pick up the language. As you read tests, you might find ways to improve them. Here's an example: Make test suite for assert_no_guard more robust.

There's no help that's too small. As someone new to the language, you come with fresh eyes that make you spot things experienced developers tend to overlook. We try to make Elixir as friendly as possible, and we need your fresh eyes. So please don't be shy. 🙂

Contribute by writing code

With that being said, let's talk about how to contribute to Elixir by fixing bugs and adding features.

1. Pick a ticket. A great way to start is to check out open issues and pick one that you are interested in. Elixir issues are well-organized. Issues labeled as Level:Starter or Level:Intermediate are good starters, but don't feel limited by them.
2. Understand the ticket. You might pick a ticket without fully understanding what it means (what's wrong, what needs to be done, etc). That's fine! That happened to me a few times. When I picked up the ticket titled: "Make mix help list aliases", I had no idea what it meant. When I picked up the ticket related to multi-clause functions, I didn't even know what a function clause was. Don't stop because you don't fully understand a ticket. You just need to figure out it out, either by Googling around or asking directly in the ticket.
   • In the first case, I googled "mix help alias" and found the documentation says: "Note aliases do not show up on mix help." That's how I realized the ticket is about making mix help to include aliases. Full disclosure, I googled a few different things ("Elixir mix help", "Elixir aliases", "Elixir mix help alias") before landing on the documentation. Because I didn't know how aliases worked, I had to skim the documentation several times before making the connection.
   • In the second case, I was confused so I asked on the ticket and José, the creator of Elixir, answered my question within 10 mins!
   • When you don't understand a ticket, don't get discouraged and think you are not ready to contribute. Most of the time you just don't have the context. Try to find out the answer either by yourself or ask for help. This is a learning opportunity! 🙂
3. Fork the repo, clone it, and compile it locally.
   • If you are not familiar with contributing repositories on Github, check out this guide.
   • Read these two sections of the documentation about how to compile Elixir locally. Basically, you compile it by running make compile in the root directory (inside /elixir). If it fails, try make clean compile. The compiled apps will be inside /elixir/bin. You might want to use the compiled apps instead of the original Elixir you installed. For example, if you want to test out your changes in iex, you will want to ues bin/iex instead of the regular iex. bin/iex should display something like Interactive Elixir (x.x.x-dev) - ..., instead of the normal Interactive Elixir (1.6.5) - .... When you want to run tests, use bin/elixir instead of elixir. Similarly, if you only make changes in a few files and want to recompile them individually (instead of recompile everything), use bin/elixirc. For example: bin/elixirc lib/elixir/lib/string.ex -o lib/elixir/ebin
4. Locate the relevant code. Locating the code related to your ticket might seem daunting, especially when you are not familiar with the structure of the code. That's totally fine. That's where the fun begins! Think of it like a treasure hunt. You start with a few clues and go from there. The more time you spend poking around, the more clues you will gather and the closer you will be to your "treasure" (the code you are looking for). The more you explore the source code, the more you learn about Elixir, both how it's written and how it can be used. So don't get discouraged if you are spending lots of time on this step. The relevant code is not the only treasure you are after. The knowledge you pick up along the way is just as valuable. After all, the whole point of doing this is to learn more about Elixir, right?? Here are some tips based off my experience:
   • Think of the process as scoping down from the whole codebase to a few functions. You start with the Elixir codebase which has six apps under the lib folder. (elixir - Contains Elixir's kernel and stdlib, eex - Template engine that allows you to embed Elixir, ex_unit - Simple test framework that ships with Elixir, iex - Elixir's interactive shell, logger - The built-in logger, and mix - Elixir's build tool.) Most likely you only care about one of them for a given ticket, and it shouldn't be hard to find out which one it's. Then you open the folder of the app, skim over the filenames to see how it's structured, and go from there.
   • If you know some phrases the relevant code prints, go ahead and search for them in the codebase.
   • After you scope down to a few relevant files, don't rush to finding the specific function. Collapse all function implementations and look at the overall structure of the files first. That will help you quickly grasp how things fit together.
   • Leverage corresponding tests. Inside each app, there's a test folder containing all the tests for the app. These tests are well-organized and very readable. You will enjoy reading them and pick up clues while doing that.
5. Play around the code. There's no better way to understand a program than modifying the code and trying it out. After you narrow the scope down to a few file and functions, you need to verify if you have found the right code. You will want to change some code, compile it, run it and see if the behavior you are after is changed. If so, congrats! You have found the right code! If not, keep poking around. There are two ways to play around with the code. You should be familiar with both of them.
   • Play around with tests. Change some code, recompile it, and rerun the corresponding test to see if it still pass. If your ticket requires changing the behavior of Elixir, you probably want to add a test for the behavior change. If you are fixing a bug, add a test that fails now but will pass after you fix the bug. If you are adding a feature, add a test that fails now but will pass once you implement the feature.
   • Play around with the debugger. Elixir uses the Erlang debugger, which is powerful but needs some time to get used to. It's helpful to use the debugger and follow the flow of the code step by step. I normally change some code, recompile them, open the recompiled iex (with bin/iex), start the debugger, drop a few breakpoints, run an example in iex and follow the flow of code execution. Here's another case when tests come handy: the examples I use are mostly from existing tests. (Tips around the Erlang debugger are too long to fit here. I will put them into a separate article. Subscribe below if you want to read about that.)
6. Make the change. If you make it this far, you have won at least half of the battle!
   • In some cases, once you understand how the code currently works, making the change is trivial. If that's your case, make the change, update the test, add new tests if needed, commit your changes and submit a pull request.
   • If the solution is not obvious, don't give up yet. I once ran into a case that appeared as a "dead-end". If you are not sure how to proceed, the best thing to do might be to take a break from it for a day or two. A break from the problem will refresh your mind which can be extremely beneficial. When you come back, play around with the code a bit more. If you still don't have any luck, share your progress and describe the challenge in the ticket. Someone might know the solution. It's also possible that the ticket requires more effort than expected and is no longer worth solving for now. Nevertheless, sharing what you find is a contribution and a win in itself!

Here you go. That's my step-by-step guide for how to contribute to Elixir! Throughout my experience, the most important thing I learned is contributing to an open source software, even a programming language, is not so much different than developing any other software. Most of the time, you will be reading code written by others (or your-past-self), jumping into the unknowns, playing around, and trying things out. You will most likely start with a question: where is the code that does that? As you dig into the code, you make progress and more questions arise: why is it doing that? how does this make any sense? Essentially, it's a process of finding answers for one question after another. Or as I like to put it, it's treasure hunting! ?

If you don't have much debugging experience, this process can be challenging. Remember, you don't have to do everything in one setting. If things get a bit overwhelming, take a break, make a cup of tea or take a walk. This is as a great opportunity to level up your debugging skill - one of the most important programming skills. Elixir's source code is very well structured and easy to read once you get used to it. Relax and enjoy!

I'm writing about how to use the Erlang debugger in Elixir. Subscribe below so you won’t miss that! ?

Related Posts

• First Impression of Elixir, from a Rubyist’s Perspective

• How to Contribute to Ruby

• Moving Millions of Dollars with Ruby While Still Able to Sleep at Night

• Ouch! That Code Hurts My Brain.

• Design Pattern: Prototype and Pizza