mirror of
https://github.com/milvus-io/milvus.git
synced 2026-07-21 18:25:44 +00:00
acfa147d30
Follow-up to #50221 (issue: #47420) — documentation only, no code change. ## Why The 60+ error misclassifications corrected during the #50221 review all happened **with the rules documents already in place** (`error_handling_guide.md`, `error_sentinel_convention.md`). The rules layer was sufficient; what was missing was (a) a layer of real positive/negative examples showing how the mistakes actually look in code, and (b) a mandatory entry point so coding agents and new authors read the right things before touching error handling. Linters catch *bare* errors, but they cannot catch a *wrong* code or a *wrong* classification — that needs case-level documentation. ## What - **`docs/dev/error_handling_casebook.md` (new).** The seven mistake patterns from the #50221 review, each with the actually-written wrong form (as first drafted, caught in review) and the merged fix, citing file + function: 1. "Looks like validation" is not user input (coordinator task types, plan shapes) 2. Internal component output is not user input (search-reduce, recovered panics) 3. `WrapErrXxxErr` is a relabel, not a context-adder (code masking) 4. The cause goes in the error argument, never the format string (`errors.Is` chain destruction) 5. InputError aborts `retry.Do`: scan before you mark (incl. the dual-identity boundary-stamp pattern) 6. Converting an `errors.Is` control-flow sentinel to merr widens every guard (the `errIgnored*` near-miss) 7. Boundary conversions that look wrong but are contracts (knowhere 2006, segcore wire collapse) Plus a quick-reference table for commonly confused sentinels and a minimum procedure for coding agents. - **`error_handling_guide.md`**: pre-flight scan recipe (`retry.Do` consumers) before InputError marking; `errors.Is`-widening warning before converting a sentinel to merr; casebook cross-link. - **`error_sentinel_convention.md`**: code-range partition table (which 100-range belongs to which family, what 65535 is, why segcore 2000–2099 is table-owned); "`milvusError.Is` matches by code" consequences; casebook cross-link. - **`CLAUDE.md`**: a mandatory error-handling procedure for coding agents (blame test, `merr.Wrap`-only context rule, the two pre-flight greps, code-range rule, guard tests + full test-go on contract changes). All file/function citations were verified against current master (post-#50221). --------- Signed-off-by: zhenshan.cao <zhenshan.cao@zilliz.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>