From fd55f15ac1c12b47a50433e4a18577716d06f158 Mon Sep 17 00:00:00 2001
From: Jeffrey Vervoort <jeffrey.vervoort@knmi.nl>
Date: Wed, 13 Dec 2023 13:00:07 +0100
Subject: [PATCH] Add information about the implementation of the migrations to
 the readme.

---
 migrate/README.md | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/migrate/README.md b/migrate/README.md
index d539f59..7e4353e 100644
--- a/migrate/README.md
+++ b/migrate/README.md
@@ -1,8 +1,28 @@
 # Migration Framework
-To have reproducible environments, support rollbacks and make sure that every change is only executed once we use [Golang Migrate](https://github.com/golang-migrate/migrate/tree/master) as migration framework.
+To have reproducible environments, support rollbacks and that every change is only executed once, we use [Golang Migrate](https://github.com/golang-migrate/migrate/tree/master) as a migration framework.
 
-Installation instructions and basic commands can be found here:
+See the following URL for installation instructions and basic commands:
 https://github.com/golang-migrate/migrate/tree/master/cmd/migrate
 
-Migration file format instructions can be found here:
+See the following URL for the migration file format instructions:
 https://github.com/golang-migrate/migrate/blob/master/MIGRATIONS.md
+
+## Practicalities
+### Initialisation
+The migration framework initialises the database. Therefore, no database tables exist before running the migrate step in the docker compose.
+
+### File name format
+The migration file name format follows the suggestion in [MIGRATIONS.md](https://github.com/golang-migrate/migrate/blob/master/MIGRATIONS.md) to use a timestamp as version.
+
+```
+{version}_{title}.up.{extension}
+{version}_{title}.down.{extension}
+```
+
+On Linux, you can retrieve the current timestamp by running: `date +%s`.
+
+
+### Migration Path
+The path `./migrate/data/migrations` is mounted on the migrate container. Thus, the docker container only executes the migrations in this path.
+
+The other path: `./migrate/data/not_supported_yet`, contains an example migration based on code comments about unfinished work from the initialise script. As the path is not mounted, the docker container does not execute migrations in that path. To try out the migrations move the files to `./migrate/data/migrations`.