# Release migrations

One-time scripts that ship inside a release package and are run by the manage
client right after it deploys the files — before `app/after-update.php`, and
only once per installation. This is the place for a change that the code cannot
make lazily: renaming a field every gallery file already has, deleting a file a
release dropped, rewriting `data/site.json` into a new shape.

Not the same thing as the per-gallery data migration in `app/migrate.php`, which
the operator runs from **Admin → Data migration**. That one is idempotent
housekeeping the application does not depend on; these run automatically as part
of the update and must therefore be safe.

## Writing one

File name: `YYYY-MM-DD-NN-short-description.php`. They run in filename order,
and the name without `.php` is the id recorded in `data/manage/migrations.json`.
Renaming a file that already ran makes it run again.

```php
<?php

return function (array $context): void {
    $file = $context['app_root'] . '/data/site.json';
    $data = json_decode((string)file_get_contents($file), true) ?: [];

    if (!array_key_exists('new_field', $data)) {   // idempotent: check first
        $data['new_field'] = null;
        file_put_contents($file, json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE));
    }
};
```

`$context` carries `app_root`, `instance`, `from_version`, `to_version`,
`backup_dir`, `run_id` and `migration_id`. There is no `pdo` — this project has
no database.

Rules that matter, because a failed migration stops the run and leaves the new
files deployed:

- **Idempotent.** A migration that fails halfway is not recorded as applied and
  runs again from the start.
- **Not destructive.** Normalise and repair; never delete images or S3 objects.
- **Use the same locking as the app** where you touch gallery files:
  `json_update()` from `app/storage.php` if you bootstrap the application, so a
  concurrent upload cannot lose its write.

## Running them by hand

```bash
php manage-client/bin/manage-client.php migrate --dry-run   # what is pending
php manage-client/bin/manage-client.php migrate             # catch up
```

Also available in the backoffice under **Maintenance**. Full reference:
[the client documentation](https://manage.med0.de/client-docs/),
07_POST_UPDATE_HOOKS.