This is an automated email from the ASF dual-hosted git repository.
tustvold pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/main by this push:
new 3b31ff6028 add guidelines for choosing panics or error results (#6958)
3b31ff6028 is described below
commit 3b31ff60284658303a938ebfdb9be519add9dc94
Author: Jinpeng <[email protected]>
AuthorDate: Mon Jan 13 13:12:05 2025 -0500
add guidelines for choosing panics or error results (#6958)
* add guidelines for choosing panics or error results
* add note to clarify that checking invalidity of user input is the key
point
* apply reviewer suggestions
Co-authored-by: Andrew Lamb <[email protected]>
* remove redundant word
* fix markdown format
---------
Co-authored-by: jp0317 <[email protected]>
Co-authored-by: Andrew Lamb <[email protected]>
---
README.md | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/README.md b/README.md
index ed42f63051..7a3dc1dd24 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,16 @@ Planned Release Schedule
| Dec 2024 | `0.11.2` | Minor, NO breaking API changes |
| Feb 2025 | `0.12.0` | Major, potentially breaking API changes |
+### Guidelines for `panic` vs `Result`
+
+In general, use panics for bad states that are unreachable, unrecoverable or
harmful.
+For those caused by invalid user input, however, we prefer to report that
invalidity
+gracefully as an error result instead of panicking. In general, invalid input
should result
+in an `Error` as soon as possible. It _is_ ok for code paths after validation
to assume
+validation has already occurred and panic if not. See [this ticket] for more
nuances.
+
+[this ticket]: https://github.com/apache/arrow-rs/issues/6737
+
### Deprecation Guidelines
Minor releases may deprecate, but not remove APIs. Deprecating APIs allows
