(opendal) branch main updated: docs(core): Add upgrade to v0.51 (#5406)

[xu...@apache.org]

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 739d34fcd docs(core): Add upgrade to v0.51 (#5406)
739d34fcd is described below

commit 739d34fcd79cef4409b2ccde5fd782dca828193d
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Wed Dec 11 18:58:24 2024 +0800

    docs(core): Add upgrade to v0.51 (#5406)
---
 core/src/docs/upgrade.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 89 insertions(+), 1 deletion(-)

diff --git a/core/src/docs/upgrade.md b/core/src/docs/upgrade.md
index 86dca5cb2..5174954ab 100644
--- a/core/src/docs/upgrade.md
+++ b/core/src/docs/upgrade.md
@@ -1,3 +1,91 @@
+# Upgrade to v0.51
+
+## Public API
+
+### New VISION: One Layer, All Storage
+
+OpenDAL has refined its vision to **One Layer, All Storage**, driven by the following core principles: **Open Community**, **Solid Foundation**, **Fast Access**, **Object Storage First**, and **Extensible Architecture**.
+
+Explore the detailed vision at [OpenDAL Vision](https://opendal.apache.org/docs/vision).
+
+### RFC-5313: Remove Metakey
+
+OpenDAL v0.51 implements [RFC-5313](https://opendal.apache.org/docs/rust/opendal/docs/rfcs/rfc_5314_remove_metakey/index.html), which removes the concept of metakey.
+
+The following structs have been removed:
+
+- `Metakey`
+
+The following APIs have been removed:
+
+- `list_with(path).metakey()`
+
+Users no longer need to pass the metakey into the list. Instead, services will make their best effort to return as much metadata as possible. Users can check items like `Capability::list_has_etag` before making a call.
+
+### Remove not used capability: `write_multi_align_size`
+
+The capability `write_multi_align_size` is not utilized by any services, and we have no plans to support it in the future; therefore, we have removed it.
+
+### CapabilityCheckLayer and CorrectnessCheckLayer
+
+OpenDAL used to perform capability checks for all services, but since v0.51, it only conducts checks that impact data correctness like `write_with_if_not_exists` or `delete_with_version` by default in the `CorrectnessCheckLayer`. If users wish to verify other non-critical capabilities like `write_with_content_type` or `write_with_cache_control`, they should manually enable the `CapabilityCheckLayer`.
+
+### RFC-3911: Deleter API
+
+OpenDAL v0.51 implements [RFC-3911](https://opendal.apache.org/docs/rust/opendal/docs/rfcs/rfc_3911_deleter_api/index.html), which adds `Deleter` in OpenDAL to replace `batch` operation.
+
+The following new APIs have been added:
+
+- [`Operator::delete_iter`]
+- [`Operator::delete_try_iter`]
+- [`Operator::delete_stream`]
+- [`Operator::delete_try_stream`]
+- [`Operator::deleter`]
+- [`Deleter::delete`]
+- [`Deleter::delete_iter`]
+- [`Deleter::delete_try_iter`]
+- [`Deleter::delete_stream`]
+- [`Deleter::delete_try_stream`]
+- [`Deleter::flush`]
+- [`Deleter::close`]
+- [`Deleter::into_sink`]
+- [`DeleteInput`]
+- [`IntoDeleteInput`]
+- [`FuturesDeleteSink`]
+
+The following APIs have been deprecated and will be removed in the future releases:
+
+- `Operator::remove` (replace with [`Operator::delete_iter`])
+- `Operator::remove_via` (replace with [`Operator::delete_stream`])
+
+As a result of this change, the `limit` and `with_limit` APIs on `Operator` have also been deprecated; they are currently no-ops.
+
+## Raw API
+
+### `adapter::kv` now returns `Scanner` instead of `Vec<String>`
+
+To support returning key-value entries in a streaming manner instead of loading them all into memory, OpenDAL updated its adapter API to return a `Scanner` instead of a `Vec<String>`.
+
+```diff
+- async fn scan(&self, path: &str) -> Result<Vec<String>>
++ async fn scan(&self, path: &str) -> Result<Self::Scanner>
+```
+
+All services intending to implement `kv::Adapter` should adhere to this API change.
+
+## Align `metadata` API to `info`
+
+OpenDAL changes it's old `metadata` API to `info` to align with the new `AccessorInfo` struct.
+
+```diff
+- fn metadata(&self) -> Arc<AccessorInfo>
++ fn info(&self) -> Arc<AccessorInfo>
+```
+
+### Remove not used struct: `RangeWriter`
+
+The struct `RangeWriter` is not utilized by any services, and we have no plans to support it in the future; therefore, we have removed it.
+
 # Upgrade to v0.50
 
 ## Public API
@@ -12,7 +100,7 @@ Previously, `list("a/b")` would not return `a/b` even if it does exist. Since v0
 
 ### Refactoring of the metrics-related layer
 
-In OpenDAL v0.50.0, we did a refactor on all metrics-related layers. They are now sharing the same underlying implemenationts. `PrometheusLayer`, `PrometheusClientLayer` and `MetricsLayer` are now have similar public APIs and exactly the same metrics value.
+In OpenDAL v0.50.0, we did a refactor on all metrics-related layers. They are now sharing the same underlying implementations. `PrometheusLayer`, `PrometheusClientLayer` and `MetricsLayer` are now have similar public APIs and exactly the same metrics value.
 
 # Upgrade to v0.49