bazelbuild / bazelbuild/remote-apis

Clarify directory order in GetTree response.

Open
#375 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
Go
Stars
445
Forks
141
PR merge metrics
No merged PRs in 30d

Description

GetTree says

> The server will enumerate the `Directory` tree recursively and return every node descended from the root.

but

> The exact traversal order is unspecified and, unless retrieving subsequent
pages from an earlier request, is not guaranteed to be stable across
multiple invocations of `GetTree`.

I think it only says that directory order is not guaranteed if `dir` has `sub1` and `sub2` as sub directories, then no specific order of `sub1` and `sub2`.

Can client assume parent directory comes before child directory? e.g. `dir` comes before `sub1` and `sub2`.
Or don't assume any order? (e.g. root directory may come the last etc)

Contributor guide

Open the contributing guide

Research direction

Start with the GetTree documentation quoted in the issue and review the existing comment thread for the intended traversal guarantee. Clarify whether parents must precede descendants or whether the response may use any order, then update the wording so clients can tell exactly what ordering they may rely on.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.