<aside> ⚠️ THIS IS NOT FOR PRODUCTION USE!

Unless you are developing Review Board itself, close this page now.

You cannot safely make custom changes to a production Review Board database!

Custom changes will break upgrades. To resolve this, you will need to contact [email protected] and request a Premium Support contract in order for us to begin database repair.

</aside>

Django Evolution works by processing "evolution files," which are little bits of Python code that lives in reviewboard/<app_dir>/evolutions/. These are processed at upgrade time. When making a change to the database, you'll generate an evolution (one per app directory per project), which will then run on the end user's system.

This guide will walk you through working with Django Evolution.

Writing an Evolution

Prior to writing an evolution, or even making any database changes, you should make a copy of your database! We cannot stress this enough. We recommend using SQLite for development, since it’s very easy to make multiple copies.

Writing and applying an evolution is very simple:

Make the changes to the models.py files. You may be adding a column, removing one, or whatever. There may be several changes all happening at once
Output a sample evolution file for your change by doing:
```
$ ./reviewboard/manage.py evolve --hint
```
Note that if you are using a third party model field (such as one supplied by Djblets), you will need to fix the import and field’s class name to point to the right class.
Save the sample evolution to reviewboard/<app_dir>/evolutions/<filename>.py.

You should pick a descriptive name for your file that clearly describes the nature of the change. If this affects only a single model, include the model name. If it affects a single field, include the field name.
Edit (or create) reviewboard/<app_dir>/evolutions/__init__.py and place the name of the evolution filename (minus the .py) in the SEQUENCE list. This should look like:
```
SEQUENCE = [
    'my_evolution',
]
```
Test that the evolution is valid by running:
```
$ ./reviewboard/manage.py evolve
```
This won't apply the evolution. It will just say if it passed.
Apply the evolution to your database by running:
```
$ ./reviewboard/manage.py upgrade
```
Remember to have a backup of your database first, in case you decide you want to make other changes as part of your project!
Place your code up for review!