66 lines
2.9 KiB
Markdown
66 lines
2.9 KiB
Markdown
# 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`](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`](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`.
|