From 7b7f51b2bffd961a49dbbd9caf1ed4ff217d755c Mon Sep 17 00:00:00 2001 From: jp0317 Date: Thu, 9 Jan 2025 06:48:31 +0000 Subject: [PATCH 1/5] add guidelines for choosing panics or error results --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index ed42f630514b..754934b042b5 100644 --- a/README.md +++ b/README.md @@ -90,6 +90,12 @@ 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. + ### Deprecation Guidelines Minor releases may deprecate, but not remove APIs. Deprecating APIs allows From d423b01d5f1e33f670ddaead9d710c493631839a Mon Sep 17 00:00:00 2001 From: jp0317 Date: Thu, 9 Jan 2025 18:13:18 +0000 Subject: [PATCH 2/5] add note to clarify that checking invalidity of user input is the key point --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 754934b042b5..333c496a7ae8 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,9 @@ Planned Release Schedule 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. +gracefully as an error result instead of panicking. Note that it still makes sense +to have some panic/assert statements, given that the invalidity of user input is +examined and reported as errors first. ### Deprecation Guidelines From 907a43d2b4144962070e81b531c669636cd1aecc Mon Sep 17 00:00:00 2001 From: Jinpeng Date: Fri, 10 Jan 2025 18:09:13 -0500 Subject: [PATCH 3/5] apply reviewer suggestions Co-authored-by: Andrew Lamb --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 333c496a7ae8..97359fda0c68 100644 --- a/README.md +++ b/README.md @@ -94,9 +94,11 @@ Planned Release Schedule 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. Note that it still makes sense -to have some panic/assert statements, given that the invalidity of user input is -examined and reported as errors first. +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 and panic if not. See [this ticket] for more nuances. + +[this ticket]: https://github.com/apache/arrow-rs/issues/6737 ### Deprecation Guidelines From 974c4e57bbff68cbe8056aafceaf4cdf3206dd7a Mon Sep 17 00:00:00 2001 From: Jinpeng Date: Fri, 10 Jan 2025 18:10:02 -0500 Subject: [PATCH 4/5] remove redundant word --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 97359fda0c68..cc0678930c00 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,7 @@ In general, use panics for bad states that are unreachable, unrecoverable or har 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 and panic if not. See [this ticket] for more nuances. +already occurred and panic if not. See [this ticket] for more nuances. [this ticket]: https://github.com/apache/arrow-rs/issues/6737 From 12a9bea66133a5cb121a33a7c05dcf9f9be4e21f Mon Sep 17 00:00:00 2001 From: Jinpeng Date: Fri, 10 Jan 2025 18:13:06 -0500 Subject: [PATCH 5/5] fix markdown format --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cc0678930c00..7a3dc1dd2458 100644 --- a/README.md +++ b/README.md @@ -95,8 +95,8 @@ Planned Release Schedule 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. +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