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.
The absolute minimum things you must know before you start contributing are:
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.
Git: All the Open edX code is hosted in Github, which implements the gitversion 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
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!
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.
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:
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.
Improvement to existing features
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.
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.
TODO: Reviewer, please check!
In order to successfully submit a pull request, you should follow these steps:
Clone (if it is the first time, pull if you already have a local copy) the project from your fork of the repo
Check out 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 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