From 7281f272e99d755898f1c85279d6dd6d4be1d273 Mon Sep 17 00:00:00 2001
From: Olivier Leger <olivierleger@gmail.com>
Date: Wed, 18 Dec 2024 16:57:13 -0500
Subject: [PATCH] Update README and add an example

---
 kobo/apps/long_running_migrations/README.md   | 47 +++++++++++++++----
 .../jobs/0001_sample.py                       |  8 ++++
 2 files changed, 46 insertions(+), 9 deletions(-)
 create mode 100644 kobo/apps/long_running_migrations/jobs/0001_sample.py

diff --git a/kobo/apps/long_running_migrations/README.md b/kobo/apps/long_running_migrations/README.md
index bd81d8bfa4..b3da45f254 100644
--- a/kobo/apps/long_running_migrations/README.md
+++ b/kobo/apps/long_running_migrations/README.md
@@ -4,22 +4,51 @@ This feature allows you to execute long-running migrations using Celery. Each mi
 
 ## How to Use
 
-1. **Create your migration**  
+1. **Create your migration**
    Define your migrations in the `jobs` folder. Each migration should have a unique name, following Django's migration naming convention (e.g., `0001_description`). The migration file must contain a function called `run()`.
 
-2. **Register the migration**  
-   Create a `LongRunningMigration` entry by running:  
-   
+2. **Register the migration**
+   Create a `LongRunningMigration` entry by running:
+
    ```python
-   LongRunningMigration.objects.create(name='0001_fix_transfer')
+   LongRunningMigration.objects.create(name='0001_sample')
    ```
+
+   You can automate this step by adding it to a Django migration with `RunPython`.
    
-   You can automate this step by adding it to a Django migration with `RunPython` 
-   
-   
+   ```python
+    from django.db import migrations
+    
+    
+    def add_long_running_migration(apps, schema_editor):
+        LongRunningMigration = apps.get_model('long_running_migrations', 'LongRunningMigration')  # noqa
+        LongRunningMigration.objects.create(
+            name='0001_sample'
+        )
+    
+    
+    def noop(*args, **kwargs):
+        pass
+    
+    
+    class Migration(migrations.Migration):
+    
+        dependencies = [
+            ('long_running_migrations', '0001_initial'),
+        ]
+    
+        operations = [
+            migrations.RunPython(add_long_running_migration, noop),
+        ]
+    
+    
+    ```
+
+
+
 3. **Execute the migration**
     Wait for the periodic task `execute_long_running_migrations` to run automatically or trigger it manually (beware of the lock, it can only run one at a time).
-    
+
 
 ## Writing a good long-running migration
 
diff --git a/kobo/apps/long_running_migrations/jobs/0001_sample.py b/kobo/apps/long_running_migrations/jobs/0001_sample.py
new file mode 100644
index 0000000000..085cbb8389
--- /dev/null
+++ b/kobo/apps/long_running_migrations/jobs/0001_sample.py
@@ -0,0 +1,8 @@
+# Generated on 2024-12-18
+
+def run():
+    """
+    Describe your long-running migration
+    """
+
+    pass