...
Hi! If you are new to contributing in 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.
...
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, branch commits, push and pull requests. The hello world guide at Github can help you with the first steps.
...
AWS: If you plan to bring Open edX to the real world (outside your local development environment), you should be familiar on 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, that 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 in on your computer. You can find a guide in 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.
...
CI/CD are the basic software engineering processes that builds build and tests test the code (Continuous Delivery) so that it integrates consistently with the rest of the platform (Continuous Integration).
...
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 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.
...
| Note |
|---|
TODO: Reviewer, please check! |
In Open edX, code base 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 is 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 previous 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.
...
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.
Hot fixesHotfixes, 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 crate create a pull request, a new issue in the Open Source Pull Requests project.
...
Documentation is an important part of any project. Your help in keeping accurate, clear, and updated is very valuable.
...
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 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 fist 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.
...
Follow this guide to have devstack installed in on your computer.
| Note |
|---|
TODO: Reviewer, please check! |
...
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
Checkout 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.
| Info |
|---|
|
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 workworks.
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
...
Push your commits to your fork.
Go to your fork in on 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 commiterscommitters. They may ask you to make some changes. Visit this page frequently to check for updates.
...