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 f1ce8d086 docs: Add upgrade guide for opendal's 0.54 release (#6382)
f1ce8d086 is described below
commit f1ce8d08680ea602a8a6b28ba27204c19967d37b
Author: Xuanwo <git...@xuanwo.io>
AuthorDate: Fri Jul 11 19:44:53 2025 +0800
docs: Add upgrade guide for opendal's 0.54 release (#6382)
---
bindings/java/upgrade.md | 47 +++++++++++++++++++++
bindings/python/upgrade.md | 48 ++++++++++++++++++++++
core/src/docs/upgrade.md | 100 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 195 insertions(+)
diff --git a/bindings/java/upgrade.md b/bindings/java/upgrade.md
index 1a281a503..6b5031fe0 100644
--- a/bindings/java/upgrade.md
+++ b/bindings/java/upgrade.md
@@ -1,3 +1,50 @@
+# Upgrade to v0.49
+
+## Breaking changes
+
+### Removed services
+
+The following services have been removed:
+
+- **Chainsafe** service has been removed
([PR-5744](https://github.com/apache/opendal/pull/5744/)) - The service has
been sunset.
+- **libsql** service has been removed
([PR-5616](https://github.com/apache/opendal/pull/5616/)) - Dead service
removal.
+
+### Batch operations removed
+
+[PR-5393](https://github.com/apache/opendal/pull/5393/) removes the batch
concept from OpenDAL. All batch-related operations and capabilities have been
removed.
+
+### Capability changes
+
+- `write_multi_align_size` capability has been removed
([PR-5322](https://github.com/apache/opendal/pull/5322/))
+- Added new `shared` capability
([PR-5328](https://github.com/apache/opendal/pull/5328/))
+
+### Options-based API
+
+New options classes have been introduced for structured operation
configuration:
+
+- `ReadOptions` - for read operations
+- `WriteOptions` - for write operations
+- `ListOptions` - for list operations
+- `StatOptions` - for stat operations
+
+Example usage:
+
+```java
+// Read with options
+ReadOptions options = ReadOptions.builder()
+ .range(0, 1024)
+ .ifMatch("etag")
+ .build();
+byte[] data = operator.read("path/to/file", options);
+
+// Write with options
+WriteOptions options = WriteOptions.builder()
+ .contentType("text/plain")
+ .cacheControl("max-age=3600")
+ .build();
+operator.write("path/to/file", data, options);
+```
+
# Upgrade to v0.48
## Breaking change
diff --git a/bindings/python/upgrade.md b/bindings/python/upgrade.md
index c959143a7..d059e7339 100644
--- a/bindings/python/upgrade.md
+++ b/bindings/python/upgrade.md
@@ -1,3 +1,27 @@
+# Upgrade to v0.46
+
+## Breaking change: Native blocking API removed
+
+OpenDAL has removed the native blocking API in the core. The Python binding's
blocking API now uses an async runtime internally. This is a transparent change
and should not affect most users, but:
+
+- The blocking API now requires an async runtime to be available
+- Performance characteristics may be slightly different
+- All blocking operations are now implemented as async operations running in a
tokio runtime
+
+## Breaking change: Removed services
+
+The following services have been removed due to lack of maintainers and users:
+
+- `atomicserver` - This service is no longer supported
+- `icloud` - This service is no longer supported
+- `nebula_graph` - This service is no longer supported
+
+If you were using any of these services, you'll need to migrate to an
alternative storage backend.
+
+## Breaking change: Chainsafe service removed
+
+The Chainsafe service has been sunset and is no longer available.
+
# Upgrade to v0.44
## Breaking change
@@ -25,6 +49,10 @@ Open a file for reading in blocking way:
```python
with op.open(filename, "rb") as r:
content = r.read()
+
+# With read options
+with op.open(filename, "rb", offset=1024, size=2048) as r:
+ content = r.read()
```
Open a file for reading in async way:
@@ -32,6 +60,26 @@ Open a file for reading in async way:
```python
async with await op.open(filename, "rb") as r:
content = await r.read()
+
+# With read options
+async with await op.open(filename, "rb", offset=1024, size=2048) as r:
+ content = await r.read()
+```
+
+Open a file for writing:
+
+```python
+# Blocking write
+with op.open(filename, "wb") as w:
+ w.write(b"hello world")
+
+# With write options
+with op.open(filename, "wb", content_type="text/plain", if_not_exists=True) as
w:
+ w.write(b"hello world")
+
+# Async write
+async with await op.open(filename, "wb") as w:
+ await w.write(b"hello world")
```
## Breaking change for Errors
diff --git a/core/src/docs/upgrade.md b/core/src/docs/upgrade.md
index 8c184a9c7..0c6897411 100644
--- a/core/src/docs/upgrade.md
+++ b/core/src/docs/upgrade.md
@@ -1,3 +1,103 @@
+# Upgrade to v0.54
+
+## Public API
+
+### RFC-6189: Remove Native Blocking Support
+
+OpenDAL v0.54 implements
[RFC-6189](https://opendal.apache.org/docs/rust/opendal/docs/rfcs/rfc_6189_remove_native_blocking/index.html),
which removes all native blocking support in favor of using `block_on` from
async runtimes.
+
+The following breaking changes have been made:
+
+- `blocking::Operator` can no longer be used within async contexts
+- Using blocking APIs now requires an async runtime
+- All `Blocking*` types have been moved to the `opendal::blocking` module
+
+To migrate:
+
+```diff
+- use opendal::BlockingOperator;
++ use opendal::blocking::Operator;
+```
+
+### RFC-6213: Options Based API
+
+OpenDAL v0.54 implements
[RFC-6213](https://opendal.apache.org/docs/rust/opendal/docs/rfcs/rfc_6213_options_api/index.html),
which introduces options-based APIs for more structured and extensible
operation configuration.
+
+New APIs added:
+
+- `read_options(path, ReadOptions)`
+- `write_options(path, data, WriteOptions)`
+- `list_options(path, ListOptions)`
+- `stat_options(path, StatOptions)`
+- `delete_options(path, DeleteOptions)`
+
+Example usage:
+
+```rust
+// Read with options
+let options = ReadOptions::new()
+ .range(0..1024)
+ .if_match("etag");
+let data = op.read_options("path/to/file", options).await?;
+
+// Write with options
+let options = WriteOptions::new()
+ .content_type("text/plain")
+ .cache_control("max-age=3600");
+op.write_options("path/to/file", data, options).await?;
+```
+
+### Remove `stat_has_xxx` and `list_has_xxx` APIs
+
+All `stat_has_*` and `list_has_*` capability check APIs have been removed.
Instead, check capabilities directly on the `Capability` struct:
+
+```diff
+- if op.info().full_capability().stat_has_content_length() {
++ if op.info().full_capability().stat.content_length {
+ // ...
+}
+```
+
+### Fix `with_user_metadata` signature
+
+The signature of `with_user_metadata` has been changed. Please update your
code accordingly if you use this method.
+
+### Services removed due to lack of maintainer
+
+The following services have been removed due to lack of maintainers:
+
+- `atomicserver`
+- `icloud`
+- `nebula_graph`
+
+If you need these services, please consider maintaining them or use
alternative services.
+
+### HttpClientLayer replaces `update_http_client`
+
+The `Operator::update_http_client()` method has been replaced by
`HttpClientLayer`:
+
+```diff
+- op.update_http_client(client);
++ op = op.layer(HttpClientLayer::new(client));
+```
+
+### Expose `presign_xxx_options` API
+
+New options-based presign APIs have been exposed:
+
+```rust
+let options = PresignOptions::new()
+ .expire(Duration::from_secs(3600));
+
+let url = op.presign_read_options("path/to/file", options).await?;
+```
+
+## Raw API
+
+### Remove native blocking support
+
+All native blocking implementations have been removed from the raw API.
Services and layers no longer need to implement blocking-specific methods.
+
# Upgrade to v0.53
## Public API
