(iceberg-rust) branch main updated: docs: improve ancestors_between docs to make behaviour more clear (#2796)

[sc...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

CTTY pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-rust.git


The following commit(s) were added to refs/heads/main by this push:
     new 85c365f5b docs: improve ancestors_between docs to make behaviour more clear (#2796)
85c365f5b is described below

commit 85c365f5b06905dd72053accc23c9d2fb2fddfd9
Author: Xander <za...@googlemail.com>
AuthorDate: Mon Jul 13 23:16:21 2026 +0100

    docs: improve ancestors_between docs to make behaviour more clear (#2796)
    
    ## Which issue does this PR close?
    
    <!--
    We generally require a GitHub issue to be filed for all bug fixes and
    enhancements and this helps us generate change logs for our releases.
    You can link an issue to this PR using the GitHub syntax. For example
    `Closes #123` indicates that this PR will close issue #123.
    -->
    
    - Closes #.
    
    Test here
    https://github.com/apache/iceberg-rust/blob/3253d1c02e1bba5c562a9044addc6eb507e7a387/crates/iceberg/src/util/snapshot.rs#L173-L180
    shows that if `oldest_snapshot_id` is not an ancestor of
    `latest_snapshot_id` then the whole chain is returned but this isn't
    clear to the caller without reading the implementation or the tests.
    
    ## What changes are included in this PR?
    
    Docs changes
    <!--
    Provide a summary of the modifications in this PR. List the main changes
    such as new features, bug fixes, refactoring, or any other updates.
    -->
    
    ## Are these changes tested?
    
    <!--
    Specify what test covers (unit test, integration test, etc.).
    
    If tests are not included in your PR, please explain why (for example,
    are they covered by existing tests)?
    -->
---
 crates/iceberg/src/util/snapshot.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/crates/iceberg/src/util/snapshot.rs b/crates/iceberg/src/util/snapshot.rs
index 98997ae81..a96fd9783 100644
--- a/crates/iceberg/src/util/snapshot.rs
+++ b/crates/iceberg/src/util/snapshot.rs
@@ -48,6 +48,11 @@ pub fn ancestors_of(
 }
 
 /// Iterate starting from `latest_snapshot_id` (inclusive) to `oldest_snapshot_id` (exclusive).
+///
+/// Note: if `oldest_snapshot_id` is `Some(id)` but `id` is not actually an
+/// ancestor of `latest_snapshot_id`, the walk is never stopped and this yields
+/// *all* ancestors of `latest_snapshot_id` down to the root. Callers that treat
+/// `oldest_snapshot_id` as a lower bound must validate the lineage themselves.
 pub fn ancestors_between(
     table_metadata: &TableMetadataRef,
     latest_snapshot_id: i64,