From 5b5956d86dc1131c2cfdd587dc6abf476c30bd6d Mon Sep 17 00:00:00 2001
From: 0livd <github@destras.fr>
Date: Sat, 13 Oct 2018 18:36:08 +0200
Subject: [PATCH] Document database migrations

Closes #390
---
 CHANGELOG.rst         |  1 +
 Makefile              |  5 +++++
 docs/contributing.rst | 16 +++++++++++++++-
 3 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 95f3d340..59cd0e58 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -35,6 +35,7 @@ Added
 - Improve settings documentation styling (#251)
 - Add a ihatemoney delete-project command to delete a project (#375)
 - Add nice 404 error pages (#379)
+- Document database migrations (#390)
 
 Changed
 =======
diff --git a/Makefile b/Makefile
index 8c48ed4c..1f36a846 100644
--- a/Makefile
+++ b/Makefile
@@ -61,6 +61,11 @@ create-database-revision: ## Create a new database revision
 	@read -p "Please enter a message describing this revision: " rev_message; \
 	$(PYTHON) -m ihatemoney.manage db migrate -d ihatemoney/migrations -m "$${rev_message}"
 
+.PHONY: create-empty-database-revision
+create-empty-database-revision: ## Create an empty database revision
+	@read -p "Please enter a message describing this revision: " rev_message; \
+	$(PYTHON) -m ihatemoney.manage db revision -d ihatemoney/migrations -m "$${rev_message}"
+
 .PHONY: build-requirements
 build-requirements: ## Save currently installed packages to requirements.txt
 	$(VIRTUALENV) $(TEMPDIR)
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 836dc082..b27e3f93 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -39,7 +39,6 @@ Accessing dev server
 In any case, you can point your browser at `http://localhost:5000 <http://localhost:5000>`_.
 It's as simple as that!
 
-
 Updating
 --------
 
@@ -47,6 +46,21 @@ In case you want to update to newer versions (from git), you can just run the "u
 
   make update
 
+Create database migrations
+--------------------------
+
+In case you need to modify the database schema, first update the models in ihatemoney/models.py.
+Then run the following command to create a new database revision file::
+
+  make create-database-revision
+
+If your changes are simple enough, the generated script will be populated with
+the necessary migrations steps.
+For complex migrations, it is recommended to start from an empty revision file which can be created
+with the following command::
+
+  make create-empty-database-revision
+
 Useful settings
 ----------------