Getting started

Firstly, thank you for your interest in contributing to KA Lite! The project was founded by volunteers dedicated to helping make educational materials more accessible to those in need, and every contribution makes a difference. The instructions below should get you up and running with the code in no time!

Setting up KA Lite for development

First of all, make sure you've forked the main KA Lite repository (sign up and configure a GitHub account first, if needed).

If you would like to learn more about using Git, try this tutorial!

Before proceeding, make sure you register your SSH keys on GitHub.

There are a couple of ways to put a local copy of your fork into your local machine for development

Manually setting up KA Lite

It's generally good practice to use virtualenv for Python development so it will isolate your project/s and allow you to install different packages even with different versions.

0. Make sure you have git and python available in your system. Installation varies by distribution. Consult Google for that.
1. Fork learningequality/ka-lite
2. In your console, type in git clone [email protected]:$USERNAME/ka-lite.git where $USERNAME is your github username.
3. Once the cloning is done, run cd ka-lite.
4. Add the upstream remote so you can pull in the most recent changes: git remote add upstream [email protected]:learningequality/ka-lite.git
5. Run git checkout develop to get you into the latest changes in KA Lite. See the note below on which branch to work on.
6. To ensure you have the required packages:
   • install pip if you don't have it already.
   • Install the dependencies listed in requirements.txt: pip install -r requirements.txt and pip install -r requirements_dev.txt
   • install node if you don't have it already.
   • Install the dependencies listed in packages.json: npm install
7. Run bin/kalite manage setup --username=admin --password=pass --noinput
8. Run bin/kalite manage retrievecontentpack download en.
9. Run node build.js --debug.
   • Mac OSX users may run into an error message similar to the following:
     Error: EMFILE, open '/Users/.../package.json'.
     A current workaround is to add this line of code to your ~/.bash_profile file:
     ulimit -n 2560
     Then, re-run the command node build.js --debug.
   • If you get a missing module error, make sure you have the latest npm:
     Run sudo npm install npm -g (update for Windows users ).
     Then re-run npm install and node build.js --debug.

You should be all set and ready to go! To check, run bin/kalite start (python.exe bin/kalite start on Windows), wait for the output to stop scrolling, and then visit 127.0.0.1:8008 in your browser.

To run in development mode, run bin/kalite manage runserver --settings=kalite.project.settings.dev. On Windows, you must specify a python interpreter: C:\path\to\your\python.exe bin/kalite manage runserver --settings=kalite.project.settings.dev

In case you want to access your development server from another IP in the network, you need to add an additional argument: bin/kalite manage runserver 0.0.0.0:8008 --settings=kalite.project.settings.dev

Which branch should I work on?

The develop branch is reserved for active development. It's very unstable and may not be usable at any given point in time -- if you encounter an issue running it, please check with the development team to see if it's a known issue before reporting it.

When we get close to releasing a new stable version of KA Lite, we generally fork the develop branch into a new branch (like 0.16.x). If you're working on an issue tagged for example with the 0.16.0 milestone, then you should target changes to the 0.16.x branch. Changes to such branches will later be pulled into develop again. If you're not sure which branch to target, ask the dev team!

Putting some sample user data into KA Lite

To generate sample Learner and Facility data to help you test KA Lite features, run the generaterealdata management command from the command line:

bin/kalite manage generaterealdata

Adding content packs

• If you skipped the step for adding content packs during install, run the following command (beware it can take a while, zip size is over 500Mb):

bin/kalite manage retrievecontentpack download en

• You can alternatively download the zip file from http://pantry.learningequality.org/downloads/ka-lite/0.16/content/contentpacks/en.zip and unpack it locally by running bin/kalite manage retrievecontentpack local en <path to zip>

Getting your changes back into KA Lite

See the guide for opening pull requests.

---

Next steps

• Once you've toyed around with things, check out our [style & structure guide](Coding guidelines and conventions) to understand more about the conventions we use.
• Now that you're up to speed on conventions, you're probably itching to make some contributions! Head over to the GitHub issues page and take a look at the current project priorities. Try filtering by milestone. If you find a bug in your testing, please [submit your own issue](Report Bugs by Creating Issues)!
• Once you've identified an issue and you're ready to start hacking on a solution, read through our instructions for [submitting pull requests](Submitting pull requests) so that you know you can cover all your bases when submitting your fix! You might wanna look at [some common Git commands](Helpful Git Commands) to get you up and running.