Development documentation#
High-level Architecture Overview#
Edx-enterprise
is a pluggable Django application designed to be run within edx-platform. It is shipped with any
edx-platform install, but can be disabled or even removed from a particular Open edX instance.
General direction is to decouple edx-enterprise
from the rest of the edx-platform as much as possible, since
the overall goal is to eventually make it an independent application or a plugin for a separate admin site, and not be
part of the edx-platform LMS.
In order to maintain the separation of edx-enterprise from the edx-platform, follow these practices:
When integrating with existing
edx-platform features
, use REST APIs rather than Python APIs.In cases where the API in question only exists as a Python API, it should be encapsulated into a module or class on the
edx-enterprise
side, to simplify future migration to a REST API.Both REST API and Python API clients must be covered with extensive unit tests.
Other noteworthy points:
edx-enterprise
does not interact with Studio.edx-enterprise
supports multiple python versions:Python 2.7 and python 3.5.
High test coverage is expected - all new python code must have 100% diff coverage. JS test were only recently introduced, so it’s not as strict so far, but aim for 100% diff coverage as well.
High code quality standards are expected - both on python and JS sides. Multiple static analyzers are used to enforce it (
pycodestyle
,pylint
,isort
,jshint
, etc.).
Local setup#
Although edx-enterprise
can’t be used outside edx-platform, some development process steps are intended to be
performed in a standalone virtual environment.
If you have not already done so, create/activate a virtualenv. Unless otherwise stated, assume all terminal code below is executed within the virtualenv.
Alternatively, docker can be used to provide a containerized shell to run the commands below inside.
$ make test-shell
Install dependencies#
Dependencies can be installed via the command below.
$ make requirements
Run tests#
This application uses tox to run tests under multiple Python and Django version. In addition, the following test utilities are used:
pytest framework and test runner to run test
pytest-cov plugin for collecting test coverage
diff-cover for analyzing changeset coverage
The edx-enterprise Makefile provides multiple shortcuts to running tests. The most noteable are:
$ make test # run all tests in current virtualenv
$ make diff_cover # run all tests in current virtualenv and report diff coverage
# run quality checks, all tests in every supported env (Python and Django versions) and jasmine JS tests
$ make test-all
More info about running tests is available in Testing section.
Check quality#
A whole bunch of static analyzers are used to ensure code quality. Most notable are pycodestyle
(formerly pep8
),
pylint
and jshint
.
$ tox -e quality # runs all python and docs quality check
$ make jshint # runs jshint on files in enterprise folder
Build (these) docs#
This documentation is generated by Sphinx. Essentially, there are two parts of documentation - manually written
(located in docs
folder) and generated from docstrings.
$ tox -e docs # performs docs quality check and generates docs in HTML
$ make docs # same, but also opens browser at the index page
Update translations#
See Internationalization chapter for details.
Upgrading local setup from older versions#
If you’re migrating from an older version (i.e. pre Nov 2016) of edx-platform, you might need to ensure edx-enterprise is installed correctly. Three things need to happen:
edx-enterprise
must be installed in edxapp env.edx-enterprise
must be added toINSTALLED_APPS
.Migrations need to be run.
All three should happen automatically if you use paver commands to upgrade your setup, but just in case something goes wrong with the setup, here are instructions to manually perform the upgrade.
First, install edx-enterprise
into virtualenv. In edxapp
virtualenv ($current_release
is 4.16.4)[1]
$ cd /edx/app/edxapp/edx-platform
$ pip install edx-enterprise==$current_release
Than, make sure edx-enterprise
is included in INSTALLED_APPS
or OPTIONAL_APPS
(see lms/env/common.py
as an example) and run migrations:
$ make migrate
# Or use a more down-to-the-root command (replace aws with your version of config)
$ ./manage.py lms migrate --settings=devstack
Footnotes