These instructions are under development

Upgrade paths

Kolibri can be automatically upgraded forwards. For instance, you can upgrade from 0.1->0.2 and 0.1->0.7. For changes in the database schema we use Django database migrations to manage these changes and make updates on upgrade. When changes are made to model schema during development, then these migrations can be generated by executing kolibri manage makemigrations.

This will trigger the Django management command that will inspect the current model schema, the current migrations, and generate new migrations to cover any discrepancies. For some migrations, manual editing will be required to ensure compatibility with Python 2 and 3 - this normally happens for Django Model fields that take a choices keyword argument, where the choices are strings. The strings should have no prefix (u or b) and the migration should contain from __future__ import unicode_literals as an import.

For any migrations involving Foreign keys to the FacilityUser model, the migration will automatically be generated by Django to use a swappable dependency on settings.AUTH_USER_MODEL. This should be updated by removing the swappable dependency, setting a fixed migration dependency and replacing the reference to settings.AUTH_USER_MODEL with “kolibriauth.FacilityUser” instead. For an example of this, see this previous pull request: https://github.com/learningequality/kolibri/pull/11984 .

We also use the upgrade functionality triggered during the CLI initialization to copy in new copies of static files that are used in the frontend app. These upgrades are only triggered for a subset of our CLI commands - start, services, manage, shell. Ones that ultimately start Django processes. In examining cli.py - those commands that are instantiated using the cls=KolibriDjangoCommand keyword argument will trigger this update behaviour.

As well as database migrations, there are also sometimes additional fixes that are put into Kolibri in order to facilitate moving between versions. This may be for bug fixing or efficiency purposes. These are sometimes carried out outside of migrations in order to leverage the full Kolibri code base, which can be restricted inside the contexts of Django data migrations.

In order to implement these upgrades, a decorator is available in kolibri.core.upgrade, version_upgrade. An toy example is shown below.

import logging
from kolibri.core.upgrade import version_upgrade

logger = logging.getLogger(__name__)

@version_upgrade(old_version="<0.6.4", new_version=">=1.0.0")
def big_leap_upgrade():
    logger.warning("You've just upgraded from a very old version to a very new version!")

If placed into a file named upgrade.py either in a core app that is part of the INSTALLED_APPS Django setting, or is in an activated Kolibri plugin, this upgrade will be picked up and run any time an upgrade happens from a Kolibri version older than 0.6.4 to a Kolibri version equal to or newer than 1.0.0.