Migrate 0.4.0 to final 0.5.0

Version 0.5.0 keeps both public V1 formats stable while retaining exact engine identity. The files look familiar, but every runtime artifact must be regenerated with the final package.

Historical migration: this page describes the published 0.5.0 release and its exact apizit-linking==0.5.0 pin. The current stable version is 1.0.1. Continue with the 0.5-to-1.0 migration for current capabilities and installation instructions.

Install the exact final release#

Exact final pin

python -m venv .venv-050
# Activate .venv-050, then:
python -m pip install "apizit-linking[preview]==0.5.0"
apizit-linking validate .
apizit-linking preview . --port 8080

The package files are canonical on the PyPI 0.5.0 page. Use an exact pin and preserve a reproducible 0.4.0 environment only when a rollback path is required.

What remains unchanged#

• User-authored Linking manifests continue to declare version: 1.
• The closed runtime-artifact envelope continues to declare version: 1.
• The artifact remains a generated, opaque build output rather than a file users or adapters edit.
• create_app_from_runtime_artifact remains the supported FastAPI adapter entry point.
• The legacy create_app_from_runtime_routes bridge remains for this following minor under the 0.x deprecation policy.

Why recompilation is mandatory#

The artifact envelope carries an exact engine_version. The 0.5.0 runtime must reject an artifact compiled by 0.4.0 even though both artifacts declare runtime artifact version: 1. Format version 1 says the envelope has the same contract; exact engine identity says which implementation verified and serialized the callable metadata.

Re-run the compiler with the exact final engine. Never replace engine_version in JSON, copy routes between artifacts, or suppress the mismatch check.

Response scope is documentary only#

Version 0.5.0 documents a minimal 200, stable Linking 400, and generic 500 in OpenAPI. These descriptions do not introduce declarative status codes, custom response headers, response models, or streaming behavior. Return annotations are not used to validate, transform, reject, or reshape customer return values at runtime.

Project-owner migration checklist#

1. Read the 0.5.0 release notes and confirm the exact final version.
2. Install 0.5.0 from PyPI in a clean environment.
3. Run apizit-linking validate against the unchanged manifest v1.
4. Compile a new artifact with 0.5.0; keep artifact version 1.
5. Inspect /openapi.json, Swagger UI, and ReDoc in preview.
6. Run startup, success, conversion-error, and business-error tests.
7. Replace deployment outputs only after provenance and rollback checks pass.

APIZIT final promotion is verified#

APIZIT consumes Linking as a separate released framework. Its final 0.5 integration has now been merged with the exact package pin and rebuilt artifact outputs:

• build and runtime dependencies pin apizit-linking==0.5.0 exactly;
• Linking artifacts were recompiled by that exact package;
• 12 Linking integration tests and 89 backend tests passed;
• APIZIT source, the generated pre-install runtime, and its wheel passed the anti-vendoring audit;
• the merged main-branch CI is green.

Rollback must also recompile#

If an adapter rolls back to 0.4.0, it must restore the exact 0.4.0 dependency and deploy an artifact freshly compiled by 0.4.0, or a preserved immutable 0.4.0 output with proven provenance. A new artifact cannot be made compatible by editing its engine field.

Follow the canonical release signal#

Follow the published 0.5.0 release notes for observed behavior, the preceding 0.5.0rc1 evaluation history, and completed package gates. PyPI is the canonical source of final package files.