> So we're talking not about fixed versions, but > rather about compatibility levels, which, importantly, are mutable. So > compatibility level v1 from next year may differ from compatibility > level v1 today (if additional non-breaking features were added in > between).
Yes, but I wouldn't say the compatibility differs. You can pick up more features with later implementations of a version, but the requirements for reading that version _correctly_ don't change. > A v1 reader would be able to read all v1.x files, but it may ignore > parts of it (if "x" is newer than what it knows about). This is exactly how major versions are interpreted. A v1 reader can correctly read all v1 files. This is primarily what the vote is trying to establish. I'd also mention that there are different ways to use the minor version number. Iceberg doesn't use one. > If that's the intent, I think it would be good to capture the complete > model in a persistent form, perhaps CONTRIBUTING.md as was suggested > elsewhere, or a separate doc focusing on the versioning scheme. I think Dan's doc <https://docs.google.com/document/d/1zrbGT4kRCEdadBUludwfQR9b2CfLgH-RWn9zE84gYfg/edit?tab=t.0#heading=h.aozivdm2oj4d> is helpful and quite detailed. I am also focused on confirming a narrow decision: using major versions and not presets. There were a _lot_ of digressions in the discuss thread and I don't want to boil the ocean, so I'm trying to make incremental progress on specific items I think we can agree on presently: - Our way of bundling forward-incompatible changes will be numbered versions (3, 4, ...) that define a compatibility level - New forward-incompatible changes will go into the next version (to address concerns about shenanigans) - Major spec versions will be decided upon and released by a vote Maybe I'm wrong, but I think aligning on this small set of principles is more effective and more important than debating what a patch version number bump on parquet-format would mean. On Thu, Jul 9, 2026 at 12:05 AM Gunnar Morling < [email protected]> wrote: > On Thu, 9 Jul 2026 at 01:29, Ryan Blue <[email protected]> wrote: > > > > Forward-compatible changes are documented in the spec, just like > > forward-incompatible changes. The difference is that you don't have to > > change the compatibility level of a file by increasing the format version > > to write them. > > Gotcha, that's helpful. So we're talking not about fixed versions, but > rather about compatibility levels, which, importantly, are mutable. So > compatibility level v1 from next year may differ from compatibility > level v1 today (if additional non-breaking features were added in > between). > > One consequence is that there's a bit of ambiguity about what it means > to say "a reader is compatible with v1": while it must be able to > parse such a file, it may or may not support all of the latest v1 > features. One way to make this more explicit would be to bump the > minor version (v1.0 -> v1.1) when making backwards compatible changes. > A v1 reader would be able to read all v1.x files, but it may ignore > parts of it (if "x" is newer than what it knows about). > > If that's the intent, I think it would be good to capture the complete > model in a persistent form, perhaps CONTRIBUTING.md as was suggested > elsewhere, or a separate doc focusing on the versioning scheme. That > way, people know what they are voting on in the ongoing vote, and > there's a reference to the model in the future which is easier to find > than the ephemeral voting thread. > > Best, > > --Gunnar >
