Upgrade

Back up the database and uploaded Media before changing code. Review CHANGELOG.md, install locked dependencies, run migrations, compile the module manifest, run release checks and execute the full test suite.

Alpha contracts may change between releases. Keep the previous code, database and Media state available as a rollback point. Do not assume every migration is automatically reversible. The canonical distribution, compatibility, supported-line and rollback rules are in the distribution, compatibility and support contract.

Composer package compatibility

Zoosper 0.3 first-party packages use one synchronised release train and bounded ^0.3.1@alpha internal compatibility. Deploy from the root project with the committed composer.lock; do not replace first-party constraints with a floating development branch. Run Composer through PHP 8.5, then compile and verify the module manifest after dependency installation.

Upgrade rehearsal

migrate is a write command and deliberately has no dry-run option. Rehearse upgrades with a disposable database and isolated Git worktree before changing a production installation. Run schema:foreign-keys:status --format=json separately for read-only foreign-key inspection. Require globally unique migration basenames because the current migration history stores basenames.

The current latest-release proof must start from the latest immutable source release v0.3.2-alpha.4. Historical BR-2 evidence for v0.3.1-alpha.1 remains recorded separately. Direct upgrade proof from v0.3.0-alpha.5 is a separate compatibility gate. Preserve representative Admin, Site, Page, Menu, Media, permission, audit, and Grid data across the rehearsal, run migration twice for idempotency, then require zero foreign-key additions, mismatches, and SQLite rebuild requirements.

Latest-release preservation proof

Run php8.5 tools/verify-release-upgrade.php v0.3.2-alpha.4 as vagrant to rehearse the immutable release against current source. The tool uses detached temporary worktrees, a private SQLite database and Media root, verifies a connected Admin/Site/Page/Menu/Media fixture graph, runs current migration twice, checks foreign-key integrity, and removes all temporary state. Composer installs are isolated to the temporary worktrees.

Disposable MySQL upgrade database

BR-2D never rehearses against the configured application database. Supply dedicated administrative credentials through BR2D_MYSQL_HOST, BR2D_MYSQL_PORT, BR2D_MYSQL_USERNAME, and BR2D_MYSQL_PASSWORD, then run php8.5 tools/verify-mysql-upgrade-capability.php. The account must be restricted to creating and dropping the uniquely named rehearsal database. Credential values are never printed.

The MySQL capability result reports database_created: true and database_dropped: true. Success is emitted only after INFORMATION_SCHEMA.SCHEMATA confirms that the generated rehearsal database no longer exists.

MySQL immutable-release preservation proof

Run php8.5 tools/verify-mysql-release-upgrade.php v0.3.2-alpha.4 with the four explicit BR2D_MYSQL_* variables. The tool uses detached release and current worktrees, a random disposable MySQL database, a connected Admin/Site/Media/Page/Menu fixture, guarded foreign-key reconciliation, orphan checks, repeat migration, and explicit post-drop absence verification. The accepted latest-release run advanced from 20 migration records before upgrade to 24 after upgrade, found 45 live MySQL foreign keys, found zero orphaned references, proved repeat-migration idempotency, and explicitly proved that the disposable database was dropped. Historical BR-2D evidence from v0.3.1-alpha.1 retained 19 migrations before and after.

API Grid integrations

Treat request and response mapper interfaces, transport failure categories, capability declarations, pagination modes and cursor token meaning as upgrade-sensitive contracts. Before upgrading, keep deployment-owned endpoint and credential configuration outside Grid query state, confirm the target release's migration notes, update the root lock file, and run the integration's fixture tests plus complete repository verification. New optional helpers are additive; changed required configuration, signatures, failure categories, pagination semantics or security defaults require an explicit migration note on a new minor release line.