Contributing to Open edX

This is a guide to help you get started in contributing code to the Open edX open source project. It’s for people who are interested in contributing to Open edX, but don’t know what contributions would be most valuable.

Start Here!

Before we can merge your contribution, you’ll need to sign a Contributor Agreement. We suggest starting that process sooner rather than later.

  • If you are contributing as an individual, go ahead and sign the Individual Contributor Agreement.
  • If your work will be contributed as part of a company or institution, email legal@edx.org.

Should I sign the individual contributor agreement or contribute as part of an larger organization?

If you will be working on your contribution during school or work time or are using a GitHub or email account administered by that organization, you likely fall under our larger organization agreements. You may also be under contractual obligation from your employer that all code you write is their property or may be their property if written on a machine that they purchased. If you have any questions about whether you should sign the individual contributor agreement or contribute as part of an organization, email your situation to legal@edx.org and they will help find the right agreement for you.

Finding Something To Work On

We manage our project work in Jira, so you will need to create a Jira account to interact with Open edX tickets.

We recommend starting with tickets in the Jira INCR project because these are tickets that are extremely contained in their scope. You don’t need to understand the entire codebase to make a contribution. The success criteria for completing these tickets are very clear. These are great for anyone new to the edX platform because the barrier to entry is low.

  1. Find an INCR ticket to work on from the INCR Epics section of the INCR project dashboard. The INCR tickets are grouped together into JIRA epic tickets.
  2. Select an epic from the dashboard and navigate to Stories in this epic to see all of the tasks associated with it. The “Python 3 in edx-platform” epic has its own Kanban board.
  3. Each ticket should be self-documenting as to what steps to take to complete it.
  4. When you find a ticket that you want to try, comment on it that you are starting it, so that other developers are less likely to duplicate your work.
  5. Click Start watching this issue to get email about any future updates to the ticket.

Get to Work!

Get started with the Open edX Devstack environment. Please note:

  • If you are at an event with experienced Open edX contributors present, they may have a snapshot of Devstack which can be installed from a USB flash drive; this can save a lot of time and network bandwidth.
  • Pay careful attention to the system requirements. If you have an unsupported operating system, insufficient memory, or insufficient disk space, please ask for help selecting a ticket which does not require Devstack.
  • If on macOS, don’t forget to adjust your Docker settings as instructed (especially memory and CPUs) before trying to install Devstack.

Once you have a development environment, follow the information in the ticket you selected to complete it. Remember to fork the repository you’re working on so you can push changes to GitHub. You can update your local clone if necessary via:

git remote set-url origin <URL from "Clone or download" button of your fork>

Getting Support

Join the #incr Slack channel on Open edX Slack to ask questions and get support. There may also be other channels to get technical support mentioned in your specific ticket.

If you get stuck on a particular ticket, leave a comment on the ticket where you got stuck.

We do our best to make these tickets clear and well-contained. But sometimes the fix uncovers larger issues. It’s always okay to stop working on a ticket, as long as you make it clear that that is what you are doing and try picking up a different ticket.

Making Your First Pull Request

When you are ready, create a Pull Request. (Don’t forget to sign the Contributor Agreement.)

  1. Be sure to reference in the title which INCR ticket your code is resolving.
  2. Mention @edx/incr-reviewers in the PR
  3. Communicate with the reviewer about the code and respond to feedback.
  4. Once your PR is approved, it will be merged by the reviewer.
  5. Celebrate 🎉

Giving Feedback

We are always looking to improve this process and make it easier for people to contribute to the platform. Your feedback is a very important part of that process.

Submit that feedback with this feedback form.