How to handle package version migrations?

[Roman (Roemer)]

If I have created a package version 1.0.0 with a skill that creates files and now I updated this package to 2.0.0 that updates the naming scheme of the generated files, how could I add an "auto-migration" that migrates existing files to the new schema for 2.0.0 (a determistic action)?

[Yusuke Hayashi (yhay81)]

There is a lifecycle hook you can use, but there is an important scope/security distinction:

• APM has pre-update and post-update command hooks.
• The CLI discovers them from the consumer project's root apm.yml, the user's ~/.apm/apm.yml, or admin policy. It does not discover and auto-execute a lifecycle block from every dependency package.
• Project hooks are skipped until the consumer explicitly runs apm lifecycle trust; changing the lifecycle block revokes that trust.

So a package's v2 release cannot currently silently run a migration against files that its v1 skill previously generated. That is a useful security boundary.

For a project you control, the supported shape is an idempotent root-project hook, for example:

# consuming project's apm.yml
lifecycle:
  post-update:
    - type: command
      description: "Migrate my-skill output from schema v1 to v2"
      command: "python tools/migrate_my_skill_v2.py"
      timeoutSec: 60

Then validate and explicitly enable it:

apm lifecycle validate
apm lifecycle trust
apm update

The migration should be deterministic and idempotent: detect a v1 marker/filename, write the v2 form atomically, preserve or back up ambiguous input, and record a schema-version marker so a second apm update is a no-op. Do not rely only on post-update meaning “1.x -> 2.x”; the event payload lists package name/reference but does not provide a general from-version/to-version migration transaction.

Also note that lifecycle failures are deliberately non-fatal, so post-update cannot provide an atomic “package update fails if migration fails” guarantee. For a reusable published package, the safer current design is therefore:

1. ship an explicit migrate-v1-to-v2 skill/command (or have the v2 skill detect legacy files and offer the deterministic conversion);
2. document it in the v2 upgrade notes;
3. keep compatibility/read support long enough to avoid destructive renames;
4. reserve a root-project post-update hook for consumers who consciously opt into automation.

The current lifecycle documentation and implementation describe the events, discovery locations, trust gate, and non-fatal behavior:
https://github.com/microsoft/apm/blob/main/docs/src/content/docs/enterprise/lifecycle-scripts.md
https://github.com/microsoft/apm/blob/main/src/apm_cli/core/lifecycle_scripts.py

If the desired feature is specifically “a dependency package can declare a version-scoped migration that APM runs once,” that would need a new package-level migration contract (including trust, from/to version matching, ownership, rollback, and failure semantics); it is not the current root-project lifecycle mechanism.