@@ -62,10 +62,16 @@ Minimum Vortex Rust crate version: `0.85.0`.
6262
6363## Draft editions
6464
65- Draft editions have no recorded minimum version of their origin project's code, and each new format
66- or revision requires a new draft edition. Vortex-maintained draft formats are expected to remain
67- compatible unless a defect blocks promotion into ` core ` , while independent plugin projects state
68- their own policy.
65+ Draft editions have no recorded minimum version of their origin project's code. Until a draft
66+ freezes, its members can change or be removed. Except for ` UNSTABLE ` , Vortex-maintained draft
67+ formats are expected to remain compatible unless a defect blocks promotion into ` core ` , while
68+ independent plugin projects state their own policy.
69+
70+ ### ` unstable `
71+
72+ ` UNSTABLE ` is a draft edition that never freezes. It holds formats whose contracts are still
73+ changing, so its members and their wire contracts can change under the same IDs. Plugins can add
74+ members through ordinary edition inclusions.
6975
7076### ` preview2026.08.0 `
7177
@@ -113,22 +119,30 @@ For example, `core2026.08.0` declares `min`, `max`, `bounded_min`, `bounded_max`
113119statistics, however, do store sums, in a fixed legacy field governed by the enclosing format's
114120contract.
115121
122+ Aggregate serialization support alone does not permit an aggregate in persisted zone maps. Its ID
123+ must belong to a selected edition, including ` UNSTABLE ` for experimental formats. The ` all_* `
124+ aggregates are in-memory pruning predicates and do not need entries. Legacy file statistics also
125+ do not need entries.
126+
116127## Format testing and promotion
117128
118- A format intended for ` core ` starts in a dedicated edition family. Its first edition is a draft,
119- with no recorded ` min_library_version ` and no frozen compatibility guarantee. Even at this draft
120- stage, the format is expected to be complete. If testing reveals a defect whose correction changes
121- what readers must understand, the correction needs a new wire ID and a later edition.
129+ A format with a changing contract belongs in ` UNSTABLE ` . Its inclusion can be added, changed, or
130+ removed without a new edition or wire ID. Applications writing these formats need readers with
131+ matching implementations.
132+
133+ Once the contract is settled, move its inclusion from ` UNSTABLE ` to another edition. A format
134+ intended for ` core ` enters ` preview ` for broader opt-in use, then a later ` core ` edition for default
135+ use. Optional modules use their own families. The format can keep its ID, but earlier experimental
136+ files acquire no compatibility guarantee.
122137
123- After initial testing, the format can enter a new ` preview ` edition for broader opt-in use, then a
124- later ` core ` edition for default use. Promotion changes which editions permit the format while
125- preserving its contract and wire ID. The current ` preview ` edition is empty, so its first component
126- must go into a new edition.
138+ A frozen contract cannot change. A reader-visible correction to a frozen format requires a new wire
139+ ID and a later edition.
127140
128141## Freezing an edition
129142
130- A stable edition can freeze when its origin publishes the code that first supports all its members.
131- For ` core ` , this is a Vortex Rust crate release. Independent plugins use their own versions.
143+ A draft edition other than ` UNSTABLE ` can freeze when its origin publishes the code that first
144+ supports all its members. For ` core ` , this is a Vortex Rust crate release. Independent plugins use
145+ their own versions.
132146
133147Until the release version is known, the declaration uses ` min_library_version: None ` . Once it is
134148known, the field records the first release that supports all members, usually while the next release
@@ -144,10 +158,10 @@ Default declarations live in `vortex-edition/src/declarations/`. Optional module
144158with their implementation code. The exported TOML records are under ` vortex/editions/ ` , grouped by
145159family.
146160
147- 1 . For a new component, declare its own family and draft edition. For a revision, add a later
148- edition to the family that owns the earlier ID.
149- 2 . To promote a tested format, add it to new ` preview ` and ` core ` editions without changing its ID
150- or contract .
161+ 1 . Register a changing format in ` UNSTABLE ` . Third-party plugins use ordinary edition inclusions.
162+ 2 . Once its contract is settled, move its inclusion from ` UNSTABLE ` to a draft edition. Formats
163+ intended for ` core ` pass through ` preview ` ; optional modules use their own families. Revisions
164+ to frozen members require a new ID and a later edition .
1511653 . When an edition freezes, record the first release of its origin that supports every permitted
152166 component, including inherited members.
1531674 . Regenerate the records:
@@ -158,4 +172,5 @@ family.
158172
159173CI's ` check-editions ` command rejects changes to frozen records, including renames, unfreezing, and
160174deletion, so changes to permitted wire formats require a later edition. The command also rejects a
161- new edition that does not follow its family's chronology.
175+ new edition that does not follow its family's chronology. Draft records, including ` UNSTABLE ` , can
176+ change or be deleted.
0 commit comments