Hermeticum/slovo
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b241a8a812
slovo/docs/language/MIGRATION_POLICY.md

2.9 KiB
Raw Blame History

Slovo Migration Policy

Slovo changes must preserve the support rule: a feature is supported only when Slovo documentation and Glagol behavior agree across syntax, typed meaning, lowering, formatter behavior, diagnostics, tests, and examples.

Compatibility Baselines

The v0 compatibility fixtures live under examples/compat/v0/.

  • examples/compat/v0/supported/ freezes the v0 supported program fixtures.
  • examples/compat/v0/formatter/ freezes the v0 formatter fixtures.

These files are compatibility baselines. Do not edit them for ordinary v1 feature promotion. Add new promoted examples under examples/supported/ and examples/formatter/ instead.

Allowed Change Classes

Additive changes may add new supported forms when SPEC-v1.md, examples, formatter fixtures, diagnostics, Glagol implementation, and tests are updated together.

Clarifying changes may improve wording without changing accepted syntax, observable behavior, diagnostic codes, or canonical formatting.

Migration changes alter accepted syntax, diagnostic shape, canonical formatting, or runtime behavior for an existing supported fixture. They require an explicit migration note before implementation is treated as supported.

Migration Requirements

A migration change must:

  • name the affected release baseline and fixtures
  • explain the old behavior and the new behavior
  • update SPEC-v1.md or the next release spec before compiler promotion
  • update RELEASE_NOTES.md
  • keep v0 compatibility fixtures intact unless the release explicitly retires them
  • add or update Glagol diagnostics so unsupported old forms fail clearly
  • update formatter fixtures when canonical layout changes
  • update promotion gates or checklist items when the verification path changes

Slovo must not silently repurpose an old supported form with new meaning.

Diagnostic And Tooling Changes

docs/language/DIAGNOSTICS.md is the beta policy for slovo.diagnostic version 1. Human-readable diagnostic prose remains beta-flexible, but machine fields, schema/version markers, diagnostic codes, source/span/range semantics, JSON-line discipline, related-span shape, and artifact-manifest diagnostic metadata are compatibility-sensitive.

Diagnostic code or machine-shape changes require the compatibility class defined in docs/language/DIAGNOSTICS.md, a documented schema or catalog migration when the change is migration-level, and matching Glagol snapshot updates. Formatter changes require before/after fixture coverage so agents can see whether the change is additive, clarifying, or migration-level.

Native executable output, package layout, stable ABI/layout promises, stable standard-runtime printing APIs, and raw-memory/FFI contracts remain outside the current compatibility promise until a future release spec defines them. The promoted v1 slovo.artifact-manifest schema is governed by SPEC-v1.md.