Upgrading

Notes on bumping versions, migrating between editions, and surviving breaking changes.

The framework is currently dev-dev only — there are no semver releases yet. This page exists so the migration story is in place when releases start.

Bumping dev-dev (current state)

In a downstream project:

# Bump just the framework family
composer update 'flyokai/*'

# Bump everything (including AMPHP, Laminas, etc.)
composer update

In a template (flyokai/<*>-edition):

# 1. Re-resolve every dependency.
composer update

# 2. Smoke-test against a throwaway install.
rm -rf vendor bin storage
vendor/bin/flyok-setup install --no-interaction --db-host=… --db-user=… --db-pass=… --db-name=… --base-url=…
php bin/flyok-console ping

# 3. If green, commit the new lock and push.
git add composer.lock
git commit -m "chore: bump flyokai/* to YYYY-MM-DD"
git push origin dev
# Merge to main when ready to advance the stable channel.

The lock policy is documented in detail in each edition's README.md.

When semver releases start

The plan is:

Branch	Composer constraint	Status
main	^1.0 (and onwards)	Stable; what tagged releases come from
dev	dev-dev	Active development; what composer create-project defaults to today

Once tagged releases exist, downstream projects should:

1. Replace every "flyokai/foo": "dev-dev" with "flyokai/foo": "^X.Y" matching the latest minor.
2. Verify the install with the new constraints; commit the resulting lock.
3. Subscribe the project to release announcements (see SECURITY.md once it exists).

Migrating between editions

You don't migrate; you compose. If you started with flyokai/webapi-edition and now want the data-service stack:

composer require \
    flyokai/data-service \
    flyokai/data-service-message \
    flyokai/amp-channel-dispatcher

amp-channel-dispatcher is already in the editions today, but explicit composer require is fine.

The reverse direction (data-service-edition → webapi-edition) is also composer require-driven — there is nothing to undo, only modules to add or skip.

Breaking-change protocol

When a flyokai/* module ships a breaking change:

1. Document the change. A CHANGELOG.md entry under ### Breaking and a ## Migration section in the module's README.
2. Deprecate first when possible. Mark the old method @deprecated for at least one release before deletion.
3. Provide a codemod when possible. A php -r one-liner that does the rename, or a shell sed snippet, alongside the docs.
4. Bump the major. The framework follows semver post-1.0.

This document will accumulate the migration recipes as breaking changes ship.

Schema migration ergonomics

flyokai/db-schema has two semantics:

• Additive changes (new column, new index, new FK): applied automatically by setup:upgrade. No migration writing required.
• Destructive changes (drop column, drop FK, change type to incompatible): collected to storage/setup/db-schema.pending-drops.php but not applied unless you set FLYOK_DB_SCHEMA_ALLOW_DESTRUCTIVE=1.

Renames are a special case — declare them with #[Column(name: 'new', renamedFrom: 'old')] so the differ emits CHANGE COLUMN instead of refusing.

Deprecating a module

If a module is being retired:

1. Tag the README with a top-of-file > **DEPRECATED:** see <replacement> block.
2. Mark the package "abandoned": "<replacement>" in composer.json.
3. Add a ## Migration section to the README.
4. Keep the package installable for at least one major.
5. Remove from edition metapackages with the next major bump.

Tracking framework releases

Until releases start, watch the dev branch on each module's GitHub mirror. After releases start, follow flyokai/flyokai's CHANGELOG.md for the rolled-up changelog.