This is an automated email from the ASF dual-hosted git repository.
zeroshade pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-go.git
The following commit(s) were added to refs/heads/main by this push:
new d3ae21a83 docs(release): add compatibility notes for pre-v1 renames
(#2334)
d3ae21a83 is described below
commit d3ae21a83e73a31ddc309048fe8be85aae0019d4
Author: Matt Topol <[email protected]>
AuthorDate: Wed Oct 28 18:12:13 2026 +0000
docs(release): add compatibility notes for pre-v1 renames (#2334)
docs(release): add compatibility notes for pre-v1 renames and breaking
changes
Add release notes for the rename batch (#2308, #2314, #2315, #2316, #2317,
#2319, #2322, #2323) and for #2067, #2290, #2294, #2307, #2310 and #2313.
Remove stray blank lines inside the compatibility-notes list.
---
website/src/releases.md | 16 ++++++++++++++--
1 file changed, 14 insertions(+), 2 deletions(-)
diff --git a/website/src/releases.md b/website/src/releases.md
index 5e74577c3..b9c043a0b 100644
--- a/website/src/releases.md
+++ b/website/src/releases.md
@@ -42,13 +42,25 @@ Per-release notes (highlights, breaking changes,
contributors) are published on
### Unreleased compatibility notes
+- **Path-based data-file addition renamed.** Replace `Transaction.AddFiles`
with `AddDataFilesByPath`, `AddFilesOption` with `AddDataFilesByPathOption`,
and `WithAddFilesConcurrency` with `WithAddDataFilesByPathConcurrency`.
Behavior is unchanged.
+- **Manifest builder constructor renamed.** Replace
`iceberg.NewManifestFile(...)` with `iceberg.NewManifestBuilder(...)`. It still
returns a `ManifestBuilder`.
+- **Manifest sequence APIs use explicit names.** `ManifestBuilder.SequenceNum`
and `ManifestFile.SequenceNum` become `SequenceNumber`, and
`ManifestFile.MinSequenceNum` becomes `MinSequenceNumber`.
`ManifestEntryBuilder.SequenceNum` and `ManifestEntry.SequenceNum` become
`DataSequenceNumber`. `FileSequenceNum` becomes `FileSequenceNumber` for
entries and their builder. Avro and JSON field names are unchanged.
+- **View and UDF metadata builder constructors are infallible.**
`view.NewMetadataBuilder` and `udf.NewMetadataBuilder` now return only a
builder instead of `(builder, error)`; remove error handling at call sites.
+- **Table metadata getter renamed.** Replace `table.Metadata.Version()` with
`table.Metadata.FormatVersion()`, consistent with Iceberg Java and Go view/UDF
metadata. Metadata JSON is unchanged.
+- **Snapshot ref type field renamed.** Replace
`table.SnapshotRef.SnapshotRefType` with `table.SnapshotRef.Type`. The JSON
field is still `"type"`.
+- **As-of snapshot lookups now use inclusive timestamps.** Replace
`tbl.SnapshotAsOf(timestampMs, true)` with `tbl.SnapshotAsOf(timestampMs)`. The
method always selects the latest snapshot at or before the timestamp, matching
Java Iceberg's `SnapshotUtil.nullableSnapshotIdAsOfTime`. For strict-before
lookup, use `SnapshotLogEntryAsOf(tbl.Metadata().SnapshotLogs(), timestampMs,
false)`.
+- **Snapshot timestamp property key corrected.**
`PropertyCurrentSnapshotTimestamp` now uses `current-snapshot-timestamp-ms`.
The old `current-snapshot-timestamp` spelling is no longer reserved and remains
usable as a custom property.
+- **FileIO open and remove take a context.** `io.IO.Open` and `io.IO.Remove`
now take a `context.Context` first argument, so custom `io.IO` implementations
must add it. `maintenance.WithCleanupDeleteFunc` now takes
`func(context.Context, string) error`.
+- **Hadoop catalog construction takes a context.** `hadoop.NewCatalog(name,
warehouse, props)` becomes `hadoop.NewCatalog(ctx, name, warehouse, props)`.
The context bounds filesystem setup; the catalog's filesystem keeps its values
but not its cancellation.
+- **Config loading reports errors.** `config.LoadConfig` now returns `([]byte,
error)`, and `config.LoadConfigFile` is removed; call `LoadConfig` instead. A
missing default `~/.iceberg-go.yaml` still returns no data and no error.
+- **Branch transactions return initialization errors.**
`Table.NewTransactionOnBranch(branch)` now returns `(*Transaction, error)`, and
`Table.NewTransactionOnBranchWithError` is removed. Use
`NewTransactionOnBranch` and handle its error.
+- **Schema JSON constructor uses the Go initialism.** Replace
`iceberg.NewSchemaFromJsonFields` with `iceberg.NewSchemaFromJSONFields`.
+- **AWS identifiers use the Go initialism.** `glue.AwsProperties`,
`glue.WithAwsConfig` and `glue.WithAwsProperties` become `glue.AWSProperties`,
`glue.WithAWSConfig` and `glue.WithAWSProperties`; `sigv4.WithAwsConfig`
becomes `sigv4.WithAWSConfig`; `utils.WithAwsConfig` and `utils.GetAwsConfig`
become `utils.WithAWSConfig` and `utils.GetAWSConfig`; and
`config.CatalogConfig.AwsProfile` becomes `AWSProfile`. The `aws-profile` YAML
key is unchanged.
- **KMS factory registration now takes a context.** Change
`encryption.KMSFactory` implementations to accept `(context.Context,
map[string]string)` instead of only properties, and call
`encryption.LoadKeyManagementClient(ctx, props)` instead of
`LoadKeyManagementClient(props)`. The existing global `RegisterKMS`,
`UnregisterKMS`, and `GetRegisteredKMSNames` functions still use the default
registry; `RegisterKMS` still panics for invalid registrations. Use
`encryption.MustRegisterKMS` for [...]
- **Name-mapping child lookup renamed.** Replace `MappedField.GetField(name)`
with `MappedField.FindFieldByName(name)`, which returns `(*MappedField, bool)`.
The new method returns a pointer to the actual child field rather than a copy,
and reports a missing name with `false`.
- **Data file block size setter removed.**
`iceberg.DataFileBuilder.BlockSizeInBytes` is removed. New v1 manifests use the
Avro schema's 64 MiB default when the field is unset. V2/v3 omit this
deprecated field, and legacy v1 values remain readable.
- **View creation APIs take a named SQL representation.**
`view.NewVersionFromSQL`, `view.CreateView`, `view.CreateViewWithIOProperties`,
and `sql.Catalog.CreateView` now accept a `view.Representation{SQL: sql,
Dialect: dialect}` instead of positional SQL/dialect strings. The dialect is
required; Hive preserves the selected representation's dialect.
-
- **View SQL representation construction uses named fields.** Replace
`view.NewRepresentation(sql, dialect)` with
`view.NewRepresentation(view.Representation{SQL: sql, Dialect: dialect})`.
Serialized JSON is unchanged.
-
- **Reserved table properties now use a read-only API.** Replace references to
`table.ReservedProperties` with `table.ReservedProperties()`. The function
returns a fresh slice, so callers cannot change metadata validation by
modifying it.
- **Fixed and decimal constructors return errors.** `iceberg.FixedTypeOf` and
`iceberg.DecimalTypeOf` now return `(type, error)` instead of panicking for
invalid inputs. Use `MustFixedTypeOf` or `MustDecimalTypeOf` only for
known-valid values.
- **SQL UDF representations now use struct literals.** The
`udf.NewSQLRepresentation(dialect, sql)` function, available since v0.7.0, is
removed. Use `udf.SQLRepresentation{Dialect: "trino", SQL: "x + 1"}` instead.
Empty fields and duplicate dialects are checked during metadata validation;
serialized JSON is unchanged.
