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:

  1. edx-enterprise must be installed in edxapp env.

  2. edx-enterprise must be added to INSTALLED_APPS.

  3. 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