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:

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, branch 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 with 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, which 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 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:

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 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:

master branch
named 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:
- Of a feature that is not likely to be deprecated before the release of the next named release:
  - First, make the change in the master branch. This will ensure that the change is propagated to the next named release.
  - Then backport the change to the current named release master branch
- Of a feature that is needed in the current named release, is worth the effort without waiting for the new release, but will be deprecated in the next named release or the feature will change so significantly that the bug would have no effect in the future:
  - Make the change in the master branch of the named release only.
- Hotfixes, including critical security patches:
  - Make the change first in the named release master branch, so that it can be deployed in production as soon as possible
  - Backport it to the master branch so it persists in the next releases.
Other changes to the core code must be made only in the master branch, and never in the named release master branch.
- New features
- Deprecations
- Improvement to existing features
Documentation changes
- Documentation follows the same guidelines as code changes, with the exception that unit or integration tests are not needed. Instead, the community experts should review documentation contributions for accuracy, relevance, and style.

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:

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 to 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 the issue type “Feature Proposal”
If you know what you want, and tried in your local development environment, you can open a pull request

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.