saleor-django-migration — Автоматизация миграций схемы данных Saleor

--- name: saleor-django-migration description: Generate Django schema migrations for the Saleor codebase using manage.py makemigrations. Use when (1) a new Django model is created, (2) model fields are added/altered/removed, (3) user explicitly asks to create a migration. This skill covers ONLY synchronous schema migrations (CreateModel, AddField, AlterField, RemoveField, etc.) — NOT data migrations with RunPython or RunSQL. If unsure whether the migration is schema-only, ask the user. --- # Saleor Django Schema Migration ## Scope This skill handles **schema-only** migrations: CreateModel, AddField, AlterField, RemoveField, AddIndex, AddConstraint, etc. It does NOT cover: - Data migrations (RunPython, RunSQL with data changes) - Async/background migrations (celery tasks, post_migrate signals) If the change requires data transformation, stop and ask the user. ## Critical Rules 1. **NEVER write migration files by hand.** Always let Django generate them. 2. **ALWAYS use `./manage.py makemigrations`** to generate migrations. 3. **Activate the virtual environment first** — run `. .venv/bin/activate` before any manage.py command. 4. **If database connection fails**, stop and ask the user to start the database. ## Workflow ### Step 1: Make model changes Edit the Django model file(s) as needed. Do not touch any migration files. ### Step 2: Generate migration ```bash . .venv/bin/activate && python manage.py makemigrations ``` If Django asks interactive questions (e.g. "Did you rename field X to Y?"), answer based on the model changes you made. ### Step 3: Read and analyze the generated migration Read every generated migration file. Verify: - It contains only schema operations (CreateModel, AddField, AlterField, RemoveField, AddIndex, etc.) - Dependencies look correct - No unexpected operations ### Step 4: Apply separation rules Apply these rules to the generated migration(s): **Rule A — One model per migration for new models:** If the migration creates MORE THAN ONE new model (multiple `CreateModel` operations), split them. Generate each separately: ```bash python manage.py makemigrations <app> ``` If Django generates them together, delete the combined migration, then create models one at a time (add one model to models.py, run makemigrations, repeat). **Rule B — One field change per migration:** If the migration alters MORE THAN ONE field within a single model (e.g. two `AddField` or two `AlterField` operations on the same model), split into separate migrations — one per field. Delete the combined migration, make one field change at a time, and run makemigrations after each. **Exceptions (do NOT split):** - A `CreateModel` with all its fields is one operation — do not split the fields of a new model - Cross-model dependencies where Django requires them together (e.g. ForeignKey + related model creation) - Field + its index/constraint in the same migration is acceptable when auto-generated together ### Step 5: Verify Run the check command to confirm no pending migrations remain: ```bash python manage.py makemigrations --check --dry-run ``` Expected output: `No changes detected` — meaning all model changes are captured in migrations. ## Error Handling | Error | Action | |-------|--------| | `django.db.utils.OperationalError: could not connect` | Ask user to start the database | | `Conflicting migrations detected` | Stop and let user decide | | `ModuleNotFoundError` | Virtual environment not activated — run `. .venv/bin/activate` | ## Tips - Rely on autogenerated migrations for correct timestamps, sequential numbers, dependencies, and field definitions. If you must hand-edit (e.g. to split), regenerate rather than edit — delete the migration, adjust models.py, and re-run makemigrations. - When splitting, let Django figure out dependencies between the new smaller migrations. - Check the newest existing migration in the app (`ls saleor/<app>/migrations/ | tail -5`) before generating, so you can confirm the new migration number is sequential.