How To Get Ready for Python Development#
This how-to will help prepare your local system to start developing on a Python-based repository that is part of the Open edX Platform.
You have Git installed
You have Python 3.8 installed
These instructions will not work in all repositories. If they do not, check the repo’s README for a Getting Started section for possible alternative instructions.
First, fork the repository, and then clone the forked repository with
git clone <git_url>. It’s best to place all of your Open edX repositories in the same parent directory as each other, as a few of them assume that they will be arranged this way. (If you’re not using devstack, this may not matter.)
After navigating to the new directory in your shell, you’ll need to set up a virtualenv and install requirements.
A virtualenv contains a copy of your repo’s Python dependencies. This avoids dependency version conflicts with your system packages and other repos.
The most basic way of creating a virtualenv is to use the builtin
venv module in Python:
python3.8 -m venv .venv
This example creates a virtualenv at
./.venv/. Each time you will be working with Python in the repo, you’ll need to activate the virtualenv for that terminal session:
Once you have done this, any calls to
pip, or other Python executables will refer to the ones managed by the virtualenv.
If you create virtualenvs inside repos, you’ll need to tell git to ignore them. The easiest way to do this is to create a file called
.gitignore-global in your home directory and add the line
.venv/. Alternatively, you can create the virtualenvs elsewhere in your filesystem.
Many developers use wrapper scripts (or write their own using shell aliases). One commonly used tool is virtualenvwrapper, which manages the virtualenv directories outside of repositories; this avoids several issues with git and other tools being able to see the virtualenv, but will require explicitly naming each virtualenv.
Working on a Repo#
Make sure you are on the default branch and have the latest version of the code:
git checkout main git pull
Some repos instead have
masteras their default branch.
Activate your virtualenv, as described above.
Install or update the Python requirements for the repo into your virtualenv:
In a few repos, this might also install NodeJS requirements, or the Makefile target might have a different name.
Optionally, ensure you can run tests:
Depending on the repository this might run not just unit tests, but also linters and other quality checks. The Makefile may also define
make qualityfor code quality checks, or even a comprehensive
Make a branch for your changes:
git switch -c <your_github_username>/<short_descriptive_label>
As you change code and add tests, you can use
make testto check if tests are still passing.
make testone more time and commit your changes with
git commit. Follow the conventional commits documentation. Make sure your commit message is informative and describes why the change is being made. While the first line of the message should be terse, the body of the message has plenty of room for details.
Push your changes to GitHub with
In GitHub, open a pull request (PR). In the PR description, include anything that could help reviewers understand and test your change.