This is an automated email from the ASF dual-hosted git repository.
Xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal.git
The following commit(s) were added to refs/heads/main by this push:
new 1e0fc7319 docs: update v0.57.0 release notes (#7628)
1e0fc7319 is described below
commit 1e0fc73190afb7e221c7badda7ef43fe40592940
Author: Xuanwo <[email protected]>
AuthorDate: Thu May 28 17:10:54 2026 +0800
docs: update v0.57.0 release notes (#7628)
---
CHANGELOG.md | 9 ++++++++-
bindings/java/upgrade.md | 13 +++++++++++++
bindings/python/upgrade.md | 11 +++++++++++
core/core/src/docs/upgrade.md | 35 +++++++++++++++++++++++++++++++++++
4 files changed, 67 insertions(+), 1 deletion(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 362ba0317..d32d2b5f9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,13 +7,15 @@ and this project adheres to [Semantic
Versioning](https://semver.org/).
<!-- Release notes generated with: gh release create v_draft --generate-notes
--draft -->
-## [v0.57.0] - 2026-05-25
+## [v0.57.0] - 2026-05-28
### Breaking Changes
* core: `Operator::copy`, `copy_options`, `copy_with`, and blocking copy APIs
now return `Metadata` instead of `()`. Custom raw copy implementations must
implement the new copier flow and return server-side completion metadata from
`oio::Copy::close`.
+* core: `RpRead` now carries optional `Metadata` observed while opening a read
operation. Out-of-tree raw services that previously populated `RpRead` size or
range fields must return `RpRead::new(metadata)` when read metadata is
available, or `RpRead::default()` otherwise.
* core: `RetryInterceptor::intercept` now takes a single `RetryEvent<'_>`
argument instead of `(&Error, Duration)`. Update custom retry interceptors to
read retry error, delay, operation, and attempt data from the event.
* observability: HTTP metrics now include the `service_operation` label for
service-specific request names. Update Prometheus, OpenTelemetry, fastmetrics,
or custom metrics consumers that assume the previous HTTP metric label set.
* services: S3-compatible services now use `skip_signature` for unsigned
requests. S3, OSS, and GCS keep `allow_anonymous` as a deprecated alias; TOS
users must migrate to `skip_signature` because `allow_anonymous` has been
removed. GCS `skip_signature` now unconditionally bypasses signing instead of
falling back on credential errors.
+* services/hf: `repo_type` is now required for the Hugging Face service. Set
`repo_type` explicitly, for example `model`, `dataset`, `space`, or `bucket`,
instead of relying on the previous implicit `model` default.
* services/tos: `TosBuilder::enable_versioning` and
`TosConfig::enable_versioning` have been removed. TOS now declares versioned
stat/read/delete capabilities natively.
* bindings/java: generated `ServiceConfig` now uses canonical service names.
Replace `ServiceConfig.Huggingface` with `ServiceConfig.Hf`; generated
`scheme()` values for services such as Aliyun Drive, Cloudflare KV, HDFS
Native, Vercel Artifacts, Vercel Blob, and Yandex Disk now return hyphenated
canonical schemes instead of underscore variants.
@@ -72,6 +74,10 @@ and this project adheres to [Semantic
Versioning](https://semver.org/).
* feat(copy): add conditional destination copy by @dentiny in
https://github.com/apache/opendal/pull/7600
* feat(s3): validate multipart copy part number by @dentiny in
https://github.com/apache/opendal/pull/7585
* feat(core): return metadata from copy by @Xuanwo in
https://github.com/apache/opendal/pull/7606
+* feat: C/Go bindings support layers by @yuchanns in
https://github.com/apache/opendal/pull/7611
+* feat(core): return metadata from read by @Xuanwo in
https://github.com/apache/opendal/pull/7624
+* feat(core): complete copy_with_if_match implementation by @YuangGao in
https://github.com/apache/opendal/pull/7627
+* feat(services/hf): add download_mode option and require explicit repo_type
by @kszucs in https://github.com/apache/opendal/pull/7625
### Changed
* refactor(services/s3): complete capability override migration by @Xuanwo in
https://github.com/apache/opendal/pull/7546
* refactor(services/oss): complete capability override migration by @Xuanwo in
https://github.com/apache/opendal/pull/7549
@@ -122,6 +128,7 @@ and this project adheres to [Semantic
Versioning](https://semver.org/).
* docs: reshape README around action cards by @Xuanwo in
https://github.com/apache/opendal/pull/7578
* docs: tune service logo presentation by @Xuanwo in
https://github.com/apache/opendal/pull/7581
* docs(services/tos): add service docs by @ddupg in
https://github.com/apache/opendal/pull/7587
+* docs: update read returns metadata RFC by @Xuanwo in
https://github.com/apache/opendal/pull/7623
### CI
* ci(bindings/dotnet): drive releases via workflow_dispatch with previe… by
@Fatorin in https://github.com/apache/opendal/pull/7422
* ci: drop skipStagingRepositoryClose for smoother staging by @tisonkun in
https://github.com/apache/opendal/pull/7436
diff --git a/bindings/java/upgrade.md b/bindings/java/upgrade.md
index 661f3765c..d83057bb9 100644
--- a/bindings/java/upgrade.md
+++ b/bindings/java/upgrade.md
@@ -2,6 +2,19 @@
## Breaking changes
+### Hugging Face config requires `repoType`
+
+`ServiceConfig.Hf` no longer relies on the backend's implicit `model` default.
Set `repoType` explicitly when creating Hugging Face operators:
+
+```diff
+ ServiceConfig.Hf config = ServiceConfig.Hf.builder()
++ .repoType("model")
+ .repoId("username/repo")
+ .build();
+```
+
+Use the appropriate value for the repository: `model`, `dataset`, `space`, or
`bucket`.
+
### Generated service configs use canonical service names
Generated `ServiceConfig` entries now use canonical OpenDAL service names.
diff --git a/bindings/python/upgrade.md b/bindings/python/upgrade.md
index d365283c4..bf15c936e 100644
--- a/bindings/python/upgrade.md
+++ b/bindings/python/upgrade.md
@@ -1,5 +1,16 @@
# Upgrade to v0.47
+## Breaking change: Hugging Face config requires `repo_type`
+
+The `hf` service no longer relies on the backend's implicit `model` default.
Set `repo_type` explicitly when creating Hugging Face operators:
+
+```diff
+-op = opendal.Operator("hf", repo_id="username/repo")
++op = opendal.Operator("hf", repo_type="model", repo_id="username/repo")
+```
+
+Use the appropriate value for the repository: `model`, `dataset`, `space`, or
`bucket`.
+
## Breaking change: Module exports are explicit
`opendal.__init__` now only re-exports the `capability`, `exceptions`, `file`,
`layers`, `services`, `types`, `Operator`, and `AsyncOperator` symbols. Imports
such as:
diff --git a/core/core/src/docs/upgrade.md b/core/core/src/docs/upgrade.md
index d0a495e6a..881153ec9 100644
--- a/core/core/src/docs/upgrade.md
+++ b/core/core/src/docs/upgrade.md
@@ -2,6 +2,12 @@
## Public API
+### Read response metadata
+
+Read operations can now expose metadata returned by the underlying service
while opening the read response. `Reader::metadata()` returns the complete
object metadata already observed by this reader, and `BufferStream::metadata()`
can open the read response and return metadata before the response body is
consumed.
+
+`Operator::read`, `read_with`, and `read_options` still return `Buffer`.
+
### Copy APIs return `Metadata`
`Operator::copy`, `copy_options`, `copy_with`, and their blocking equivalents
now return `Metadata` instead of `()`, matching write completion behavior.
@@ -20,6 +26,21 @@ Out-of-tree raw services and layers that implement copy must
migrate to the new
HTTP metrics emitted by the metrics layers now include a `service_operation`
label for backend-specific request names such as `GetObject` or `UploadPart`.
Metrics consumers and dashboards that assume the previous HTTP metric label set
must be updated.
+## Raw API
+
+### `RpRead` carries optional `Metadata`
+
+`RpRead` now carries optional complete object `Metadata` observed while
opening a read operation. The old size/range fields have been removed.
+
+Out-of-tree services should return:
+
+- `RpRead::new(metadata)` when the read response natively provides metadata.
+- `RpRead::default()` when the service does not provide read metadata.
+
+The `metadata.content_length()` value must describe the full object size, even
for range reads.
+
+## Services
+
### `allow_anonymous` renamed to `skip_signature`
S3-compatible services now use `skip_signature` to describe requests that
bypass credential loading and request signing:
@@ -28,6 +49,20 @@ S3-compatible services now use `skip_signature` to describe
requests that bypass
- For TOS, migrate from `allow_anonymous(true)` / `allow_anonymous = true` to
`skip_signature()` / `skip_signature = true`.
- For GCS, the behavior changed from fallback-on-credential-error to an
unconditional signing bypass. If requests should be signed, do not set either
`skip_signature` or the deprecated `allow_anonymous` alias.
+### Hugging Face `repo_type` is required
+
+The Hugging Face service no longer defaults `repo_type` to `model`. Set it
explicitly when constructing the service:
+
+```diff
+ let builder = opendal_service_hf::Hf::default()
++ .repo_type("model")
+ .repo_id("username/repo");
+```
+
+For config maps and environment-driven setup, add `repo_type = "model"` or the
correct repository type: `model`, `dataset`, `space`, or `bucket`.
+
+The service also adds a `download_mode` option. The default is `xet`; set
`download_mode = "http"` to force plain HTTP downloads.
+
### TOS versioning option removed
`TosBuilder::enable_versioning` and `TosConfig::enable_versioning` have been
removed. TOS now declares versioned stat/read/delete capabilities natively.
