Introduction

Hi! If you are new to contributing in Open edX, this is the place for you! This document will guide from scratch to become an active contributor to the Open edX platform.

Although contribution can take many forms (documentation, marketing, architecture, etc.), we will focus here on how to improve the base code that runs Open edX instances.

There is a complete guide for developers in Open edX. If you need to know more about the process, please read this guide. This page is just a brief summary for beginners that will guide you in the first steps.

Minimum knowledge

The absolute minimum things you must know before you start contributing are:

Python: Most of the code that runs Open edX is written in Python. There are many guides on the web to learn Python, even some in many languages other than English.
Django: This is the framework for Python to make web applications. The official site has a very comprehensive guide to learn everything you need to know.
HTML, CSS, JavaScript: Of course, for the front end.
Git: All the Open edX code is hosted in Github, which implements the git version control system. At least, you must be familiar with the concepts of local and remote repositories, branches, commits, push and pull requests. The hello world guide at Github can help you with the first steps.

Additional knowledge that would be valuable in specific aspects of Open edX development are:

AWS: If you plan to bring Open edX to the real world (outside your local development environment), you should be familiar on how to set up Amazon Web Services basic infrastructure
NodeJs: Some parts of the front end use server side JS
React: The front end is migrating to the concept of micro front ends, that relies on this framework
MySQL and MongoDB: These are the databases on which Open edX persists data

Tools

In order to start contributing to Open edX, you should have a devstack installation in your computer. You can find a guide in the official site explaining how to do that, including the minimum system requirements. Basically you will need:

A MacOS or Linux computer (unfortunately running devstack on Windows is not currently supported)
Although you can live without one, a Python IDE will be very helpful. There is a list of Python IDEs at the official site, many of which are free or have free versions.

Now that you know the basics and have the minimum tools, let’s get started!

CI/CD process

CI/CD are the basic software engineering processes that builds and tests the code (Continuous Delivery) so that it integrates consistently with the rest of the platform (Continuous Integration).

There are several roles defined in the CI/CD process adopted by Open edX. If you are reading here, probably you are a contributor, the starting point of the process. Before you start you should complete the contributor agreement so that the Open edX agreement can recognize you as part of the team.

Another important role is the core committer. Core committers are in charge of reviewing all proposed changes and merge into the deployable branches once they are ready.

In Open edX we use a fork and pull model for code delivery. This means that contributors cannot commit changes directly to the edx repositories. As a contributor, you can fork the source repositories into your own github account, commit changes in it, and submit pull requests automatically from there. When you do this, both branches at the source and the fork repositories remain linked, therefore when you make additional commits in your fork’s branch, it will update the original pull request until it is completed.

How to start

There are three main start points for your contributions:

If you have a very vague idea about an improvement of the platform, you can open a discussion in the Open edX Development forum. Probably the Development category is the place to go.
If you have an idea of what you want to add or change in the platform, but you are not very sure about how to make it, you should open a Jira ticket describing your idea. Create a new issue in the “Community Reported Issues” project with issue type “Feature Proposal”
If you know what you want, and tried in your local development environment, you can open a pull request

The fist two options (forum discussions and Jira issues) are simple and straightforward. We will focus now on how to make a pull request to submit your code change proposal.

Creating your first pull request

Follow this guide to have devstack installed in your computer.

TODO: Reviewer, please check!

In order to successfully submit a pull request, you should follow these steps:

Fork the Open edX project you want to contribute from the official Open edX Github repository to your Github account
Clone (if it is the first time, pull if you already have a local copy) the project from your fork of the repo
1. Checkout your local devstack installation to the master branch. You should only make PRs on the master release for -at least- three reasons:
  Branches based on old commits may not get merged in the next release
  Your change may have already been implemented
  The files that you want to change may have disappeared, been moved or modified
Run the unit tests for the app your want to change to make sure that the installation is clean. Do this before any change. Undo or discard any change to the pulled branch.

If you will be working on edx-platform, you can run all tests with paver test, or specific test with pytest <test_file>. For other applications, please refer to the appropriate test method in the app documentation

Create a Jira issue explaining your change. If it is a bug fix or an improvement, you can use the Community Reported Issues project.
Create a local branch with the name of the Jira issue and check it out. This way, your changes can be easily identified. Create the branch in the remote repo also.
Make your changes. Try them until you are sure they work as you want, and everything else still work.
Write or update unit and integration test procedures. There is a great guide about how testing in Open edX works here. You can also learn from the Django testing documentation.
Run again the tests for your applications. Pay special attention to your new code.
Commit your changes to your newly created branch. Be as clear as possible in the commit message

In your commit message, explain why you made the change. You can see tips for writing good commit messages in this article

Push your commits to your fork.
Go to your fork in the Github website. Click on the “Compare & pull request” button.
In the Open a pull request page, fill the form with the description of the contribution. Then click on “Open pull request”.
You will be notified of any comments made by the core commiters. They may ask you to make some changes. Visit this page frequently to check for updates.