Skip to content

Commit 04eee35

Browse files
committed
AGENTS.md: make the check-the-official-clients practice a hard rule
The practice existed - go-parity.md is prefaced with it, sdk-comparison.md exists to record deviations from it, retry.rs follows the Python client's retry list, and #38/#39/#40 all ran on it - but the Hard rules section only covered protocol facts (docs + a real cluster). Behavioural decisions the protocol does not dictate (retries, routing, proxy selection, banning, refresh) had no written rule, so following the official C++/Go clients was convention rather than specification. Rule 3 now carries both halves: protocol facts against docs and cluster, behaviour against the official clients' source, disagreements between the two clients resolved out loud, and deviations recorded in sdk-comparison.md - the record that turned the heavy-proxy lifetime pin from a silent bug into issue #40 with a known fix.
1 parent 9dc6176 commit 04eee35

1 file changed

Lines changed: 12 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,18 @@ repository builds the minimal stack — a YSON codec and a job runtime.
5656
3. Protocol facts are verified against the official YTsaurus documentation and
5757
against a real cluster. If code and docs disagree, **re-read the docs first**,
5858
then change the code. Cite the doc at the point of use.
59+
**Client behaviour the protocol does not dictate — retries, routing, proxy
60+
selection, banning, refresh — is checked against the official clients'
61+
source before it is designed here**: C++ (`yt/cpp/mapreduce`) and Go
62+
(`yt/go`), and the Python wrapper where it is the reference (the retry
63+
list). Where the two disagree, say which was followed and why; where this
64+
client deviates from both, the deviation is a deliberate decision recorded
65+
in [docs/sdk-comparison.md](docs/sdk-comparison.md) — that record is what
66+
turned the heavy-proxy lifetime pin from a silent bug into #40, a filed
67+
divergence with a known fix. [docs/go-parity.md](docs/go-parity.md) is the
68+
same rule for API surface: read it before adding client API, because a
69+
feature list written by the people who built the thing is worth more than
70+
one written by the people reimplementing it.
5971
4. Every change ends with green CI: `cargo fmt --check`, `cargo clippy
6072
--all-targets -D warnings`, `cargo test`, `cargo test --doc`.
6173
5. **No scope creep.** RPC proxy, protobuf row format, dynamic tables, non-Linux

0 commit comments

Comments
 (0)