Add contributors documentations

docs/contributors/database.rst

@@ -0,0 +1,69 @@
+Altering the database
+=====================
+
+Alter the model code
+--------------------
+
+First alter the model code. Simply edit ``models.py`` and modify all required model classes.
+Make sure that your changes reflect on related classes as the migration should be consistent from one structure to another.
+
+Do not commit your changes at that stage.
+
+Generate the migration script
+-----------------------------
+
+After you modify the database models, you need to generate a new schema
+migration script:
+
+.. code-block:: bash
+
+  python manage.py db migrate
+
+This will generate a new script in ``migrations/versions`` that you must review
+before adding it for commit.
+
+Because we use SQLite, make sure that you use batch operation for column changes and deletion. For instance:
+
+.. code-block:: python
+
+  def downgrade():
+      with op.batch_alter_table('fetch') as batch:
+          batch.drop_column('last_check')
+          batch.drop_column('error')
+
+or
+
+.. code-block:: python
+
+  def upgrade():
+      # spam_threshold is a X/15 based value, we're converting it to percent.
+      for user in User.query.all():
+           user.spam_threshold = int(100. * float(user.spam_threshold or 0.) / 15.)
+      db.session.commit()
+
+      # set default to 80%
+      with op.batch_alter_table('user') as batch:
+          batch.alter_column('spam_threshold', default=80.)
+
+Remove unneeded Alembic comments and add a proper description to your migration script.
+
+Upgrade your local database
+---------------------------
+
+At that point, to start working on the changed database structure, you will need to upgrade your local database. Make a backup of your database, then:
+
+.. code-block:: bash
+
+  python manage.py db upgrade
+
+If any error arises, restore the backup, fix the migration script and try again.
+
+Actually work on your feature or fix
+------------------------------------
+
+If your changes to the database are related to a view or template, you may not work on these to reflect the changes and access the proper columns/tables.
+
+Commit your work
+----------------
+
+You may finally commit your work as a whole: database changes and view/template changes. Do not forget to add the migration script.