This page of out-of-date, but the information it contains may still be useful.

Contributors: If you have time, update this page!

Introduction

Hi! If you are new to contributing to the Open edX platform, this is the place for you! This document will guide you 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:

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

Tools

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

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 build and test 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.

Release lifecycle

TODO: Reviewer, please check!

In Open edX, codebase development is organized in two main branches:

The Master branch is where all the new developments occur. Every six months, a new named release master branch is created from the master branch.

Named releases are explained in detail in the developer documentation. All production deployments must be done from the master branch of the named releases, and never from the master branch. Names of the named releases are inspired from tree names, and are ordered alphabetically (e.g. ficus, ginkgo, hawthorn, ironwood, juniper, koa, etc.).

One month after a new named release is created, the previously named release master branch ends its support life. If you need to fix a bug after that date, you’d better migrate to the new named release.

The following diagram depicts more or less the life cycle of a named release branch:

Depending on what kind of change you want to make into the platform, you may need to commit to a named release branch or to the master branch:

Bug fixes and feature improvement opportunities can be reported in the Community Reported Issues project. However, if it is something simple and you think you have a fix, you can directly create a pull request and follow the discussion there. Once you create a pull request, a new issue in the Open Source Pull Requests project.

New features normally are complex endeavors. You can submit your proposals to the Open edX roadmap. Submissions are reviewed and prioritized periodically. If you feel you can help here, don’t hesitate to participate.

Many features often get obsolete. We often review unneeded code and start new issues in the Deprecation and Removal project. This is another place you can work on. Ask one of the project managers to assign you a task from here to start working on it.

Documentation is an important part of any project. Your help in keeping accurate, clear, and updated is very valuable.

How to start

There are three main start points for your contributions:

The first 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 on your computer.

TODO: Reviewer, please check!

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

  • If you will be working on the 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

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