ORA2 Developer Guide#
Contents
Where is the code#
ORA is broken into two separate repositories:
Using ORA with docker devstack#
Note - “from inside the lms”, means you’ve run make lms-shell
from the devstack directory and are on a command prompt inside the lms container.
Clone edx-ora2 repo into ../src/ directory (relative to your ‘devstack’ repo location).
From the src directory, run the following command to install ora2 in the lms’s and studio’s virtual environments:
make install-local-ora
Alternatively, one can log into either lms (make lms-shell
) or studio (make studio-shell
) and execute the following commands to uninstall ora2 and reinstall your local copy:
pip uninstall ora2 -y; pip install -e /edx/src/edx-ora2/
3. Now, get your edx-ora2 development environment set up: (the virtual environment MUST be named edx-ora2) This must be done from inside either lms or studio docker container.
cd /edx/src/edx-ora2
virtualenv edx-ora2
source edx-ora2/bin/activate
make install
ensure that your virtual environment is named edx-ora2. Using a different name will cause errors when trying to generate translations.
Now, in the devstack directory on your host, run:
make lms-restart lms-logs
5. That’s it, you’re good to go! See Makefile for all the available commands, most are fairly self-explanatory In order to simulate a given tox environment (django18, django111, quality, js), run tox -e <env> for the env in question (after re-activating your edx-ora2 virtual environment). Usually, you can just run the underlying make commands for quicker tests, as requirements aren’t re-installed.
Working with submission dependencies#
ORA code also depends on edx-submissions. As a result, anytime a new version of edx-submissions is released, ORA code must be updated as follows.
For devstack:
make lms-shell
# get into docker containercd /edx/src/edx-ora2
# goto into ora2 foldersource edx-ora2/bin/activate
# activate ora2 virtual environmentpip install -U edx-submissions
# installs latest version of submissions from pypipip install -e /edx/src/edx-submissions
# installs latest local version of submissions
Available make commands#
make install-local-ora
- installs your local ORA2 code into the LMS and Studio python virtualenvsmake static
- builds static JS/SASS files for LMS and Studiomake quality
- run the JSHint quality testsmake test
- run all the testsmake test
- acceptance - run the acceptance testsmake test-a11y
- run the accessibility testsmake test-js
- run the JavaScript testsmake test-js-debug
- run the JavaScript tests in debug mode in Chromemake test-python
- run the Python testsmake test-sandbox
- run all the sandbox tests (currently acceptance and a11y)
Making Translations#
If any changes are made to the .html files, it is necessary to re-do the translations:
be inside the shell
cd /edx/src/edx-ora2
source edx-ora2/bin/activate
make check_translations_up_to_date
The above command will generate translations files which will have to be checked into git.
Building Static Files#
This is required if there were any JS/SCSS changes:
from local directory (not in lms shell)
npm run build
Hot Reload Frontend Changes#
This is required if there were any JS/SCSS changes:
from local directory (not in lms shell)
npm run start
to start dev server - If there is port conflict, change PORT in.env.development
from devstack directory (not in lms shell)
make lms-restart studio-restart
- NOTE: cms does not support hot reload at the moment
Running Unit Tests#
ORA2 supports pytest. In order to run unit tests, do the following:
be inside the shell
cd /edx/src/edx-ora2
source edx-ora2/bin/activate
pytest <relative path to the unit test file>
Debugging with PDB#
The simplest way to debug ORA2 code is with PDB - Python’s built in debugger. One caveat: Since ORA2 has code that executes either in studio or lms context, one must be attached to the corret shell in order for the breakpoints to be hit.
Debugging JavaScript#
For debugging JS in Devstack, first follow the instructions for “Hot Reload JS”. This enables source maps and allows for placing breakpoints in source-mapped files from the browser dev tools.
Locate code by browsing to
webpack:///./openassessment/xblock/static/js/src/
. - NOTE The path should be withiniframe
forlms
. - TIP UseCTRL + P
orCommand + P
to find the file through chrome dev tools.breakpoints should toggle with hot-reloading.