You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spark.apache.org by GitBox <gi...@apache.org> on 2021/04/16 00:19:23 UTC
[GitHub] [spark-website] karenfeng opened a new pull request #332: Add error message guidelines
karenfeng opened a new pull request #332:
URL: https://github.com/apache/spark-website/pull/332
Adds error message guidelines to the contributing guidelines, as [discussed in the developers list](http://apache-spark-developers-list.1001551.n3.nabble.com/DISCUSS-Build-error-message-guideline-td31076.html).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] karenfeng commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
karenfeng commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r616091849
##########
File path: contributing.md
##########
@@ -186,6 +186,29 @@ that maintainability, consistency, and code quality come first. New algorithms s
- Come with a reasonable expectation of developer support.
- Have `@Since` annotation on public classes, methods, and variables.
+<h3>Error Message Guidelines</h3>
+
+Exceptions thrown in Spark should be associated with standardized and actionable
+error messages.
+
+Error messages should answer the following questions:
+
+- **What** was the problem?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+When writing error messages, you should:
+
+- Use active voice
+- Avoid time-based statements, such as promises of future support
+- Use the present tense to describe the error and provide suggestions
+- Provide concrete examples
+- Avoid sounding accusatory, judgmental, or insulting
Review comment:
"Must" sounds more like a command, so it may put users off - we don't want them to feel like they did something wrong. Luckily, we don't have many good examples of more accusatory/judgmental/insulting error messages.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615336175
##########
File path: error-message-guidelines.md
##########
@@ -0,0 +1,383 @@
+---
+layout: global
+title: Error message guidelines
+type: "page singular"
+navigation:
+ weight: 5
+ show: true
+---
+
+## Error Message Guidelines
+
+This guide is a reference for composing standardized and actionable
+error messages in Apache Spark.
+
+### Include What, Why, and How
+
+Exceptions thrown from Spark should answer the Five W's and How:
+
+- **Who** encountered the problem?
+- **What** was the problem?
+- **When** did the problem happen?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+The context provided by exceptions can help answer **who** (usually the
+user), **when** (usually included in the log via <code>log4j</code>), and **where**
+(usually included in the stack trace). However, these answers alone are
+often insufficient for the user to solve the problem. An error message
+that answers the remaining questions
+--- **what**, **why**, and **how** --- minimizes user frustration.
+
+#### Explicitly answer What, Why and How
+
+In many cases, the error message should explicitly answer **what**,
+**why**, and **how**.
+
+##### Example 1
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/569fb133d09e24e4ed56ed7efff641512d98b01b/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L160">
+ Unable to generate an encoder for inner class {} without access to the
+ scope that this class was defined in. Try moving this class out of its
+ parent class.
+ </a>
+</code>
+
+- **What:** Unable to generate encoder inner class.
+- **Why:** Did not have access to the scope that the class was defined
+ in.
+- **How:** Try moving this class out of its parent class.
+
+##### Example 2
+
+If the proposed fix (**how**) feels arbitrary, providing an explanation
+for **why** the error occurred can reduce user frustration.
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/03dd33cc982ebb3de4354274ac49da31521b8195/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L498">
+ <span style="background-color: #ffcccc">Unsupported</span> function name {}.
+ </a>
+</code>
+
+- **What:** Unsupported function name.
+- **Why:** Unclear.
+- **How:** Unclear.
+
+**After**
+
+*Function name {} <span style="background-color: #ccffcc">is invalid. Temporary functions cannot belong to a
+catalog. Specify a function name with one or two parts.</span>*
+
+- **What:** Invalid function name.
+- **Why:** Temporary functions cannot belong to a catalog.
+- **How:** Specify a function name with one or two parts.
+
+#### Implicitly answer How
+
+Not all error messages should be this verbose. Sometimes, explicitly
+explaining **how** to resolve the problem would be redundant.
Review comment:
In this context, `redundant` -> `sufficient`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] karenfeng commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
karenfeng commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r616078035
##########
File path: contributing.md
##########
@@ -186,6 +186,29 @@ that maintainability, consistency, and code quality come first. New algorithms s
- Come with a reasonable expectation of developer support.
- Have `@Since` annotation on public classes, methods, and variables.
+<h3>Error Message Guidelines</h3>
+
+Exceptions thrown in Spark should be associated with standardized and actionable
+error messages.
+
+Error messages should answer the following questions:
+
+- **What** was the problem?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+When writing error messages, you should:
+
+- Use active voice
+- Avoid time-based statements, such as promises of future support
+- Use the present tense to describe the error and provide suggestions
+- Provide concrete examples
Review comment:
To avoid making error messages unnecessarily verbose, we should likely only encourage developers to add examples in the case that the fix is unclear otherwise. I can clarify the wording here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615337573
##########
File path: contributing.md
##########
@@ -186,6 +186,29 @@ that maintainability, consistency, and code quality come first. New algorithms s
- Come with a reasonable expectation of developer support.
- Have `@Since` annotation on public classes, methods, and variables.
+<h3>Error Message Guidelines</h3>
+
+Exceptions thrown in Spark should be associated with standardized and actionable
+error messages.
+
+Error messages should answer the following questions:
+
+- **What** was the problem?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+When writing error messages, you should:
+
+- Use active voice
+- Avoid time-based statements, such as promises of future support
+- Use the present tense to describe the error and provide suggestions
+- Provide concrete examples
Review comment:
Oh, are we enforcing to have `For example, ...` clause always?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615338243
##########
File path: contributing.md
##########
@@ -186,6 +186,29 @@ that maintainability, consistency, and code quality come first. New algorithms s
- Come with a reasonable expectation of developer support.
- Have `@Since` annotation on public classes, methods, and variables.
+<h3>Error Message Guidelines</h3>
+
+Exceptions thrown in Spark should be associated with standardized and actionable
+error messages.
+
+Error messages should answer the following questions:
+
+- **What** was the problem?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+When writing error messages, you should:
+
+- Use active voice
+- Avoid time-based statements, such as promises of future support
+- Use the present tense to describe the error and provide suggestions
+- Provide concrete examples
+- Avoid sounding accusatory, judgmental, or insulting
+- Be direct
+- Use human-readable text for user-facing errors
Review comment:
Although I understand the meaning, I'd like to recommend to revise this guideline.
Given the example, this guideline aims to discourage `!=` and to recommend a natural sentence. Technically, both are human-readable text, aren't they?
```
- RENAME TABLE source and destination databases do not match: '{}' != '{}'
- RENAME TABLE source and destination databases do not match. The source database is {}, but the destination database is {}.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615338379
##########
File path: error-message-guidelines.md
##########
@@ -0,0 +1,383 @@
+---
+layout: global
+title: Error message guidelines
+type: "page singular"
+navigation:
+ weight: 5
+ show: true
+---
+
+## Error Message Guidelines
+
+This guide is a reference for composing standardized and actionable
+error messages in Apache Spark.
+
+### Include What, Why, and How
+
+Exceptions thrown from Spark should answer the Five W's and How:
Review comment:
Although we know `where` means the stack trace, please add `**Where**` in the following list. Currently, we say `the Five W's` in this sentence and show only four Ws in the following list. So, this mismatch unnecessarily confuse readers.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615337391
##########
File path: contributing.md
##########
@@ -186,6 +186,29 @@ that maintainability, consistency, and code quality come first. New algorithms s
- Come with a reasonable expectation of developer support.
- Have `@Since` annotation on public classes, methods, and variables.
+<h3>Error Message Guidelines</h3>
+
+Exceptions thrown in Spark should be associated with standardized and actionable
+error messages.
+
+Error messages should answer the following questions:
+
+- **What** was the problem?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+When writing error messages, you should:
+
+- Use active voice
+- Avoid time-based statements, such as promises of future support
+- Use the present tense to describe the error and provide suggestions
+- Provide concrete examples
+- Avoid sounding accusatory, judgmental, or insulting
Review comment:
Did we have the error message in this category before?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] HyukjinKwon commented on pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
HyukjinKwon commented on pull request #332:
URL: https://github.com/apache/spark-website/pull/332#issuecomment-820825849
I think it's fine.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] wangyum commented on pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
wangyum commented on pull request #332:
URL: https://github.com/apache/spark-website/pull/332#issuecomment-821106595
cc @cloud-fan @gatorsmile @dongjoon-hyun
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615338379
##########
File path: error-message-guidelines.md
##########
@@ -0,0 +1,383 @@
+---
+layout: global
+title: Error message guidelines
+type: "page singular"
+navigation:
+ weight: 5
+ show: true
+---
+
+## Error Message Guidelines
+
+This guide is a reference for composing standardized and actionable
+error messages in Apache Spark.
+
+### Include What, Why, and How
+
+Exceptions thrown from Spark should answer the Five W's and How:
Review comment:
Although we know `where` means the stack trace, please add `**Where**` in the following list. Currently, we say `the Five W's` and show only four Ws in the list. So, this mismatch unnecessarily confuse readers.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] karenfeng commented on pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
karenfeng commented on pull request #332:
URL: https://github.com/apache/spark-website/pull/332#issuecomment-820820957
Right now, the error message guidelines page is not accessible via the main navigation bar, and is only accessible via a link from the [Contributing to Spark](https://spark.apache.org/contributing.html) page. Is there a precedent for semi-orphan pages?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] gatorsmile commented on pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
gatorsmile commented on pull request #332:
URL: https://github.com/apache/spark-website/pull/332#issuecomment-821255484
@karenfeng Could you post the screen shot in the PR description?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615337391
##########
File path: contributing.md
##########
@@ -186,6 +186,29 @@ that maintainability, consistency, and code quality come first. New algorithms s
- Come with a reasonable expectation of developer support.
- Have `@Since` annotation on public classes, methods, and variables.
+<h3>Error Message Guidelines</h3>
+
+Exceptions thrown in Spark should be associated with standardized and actionable
+error messages.
+
+Error messages should answer the following questions:
+
+- **What** was the problem?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+When writing error messages, you should:
+
+- Use active voice
+- Avoid time-based statements, such as promises of future support
+- Use the present tense to describe the error and provide suggestions
+- Provide concrete examples
+- Avoid sounding accusatory, judgmental, or insulting
Review comment:
Just a question. Did we have the error message in this category before?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] karenfeng commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
karenfeng commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r616092808
##########
File path: contributing.md
##########
@@ -186,6 +186,29 @@ that maintainability, consistency, and code quality come first. New algorithms s
- Come with a reasonable expectation of developer support.
- Have `@Since` annotation on public classes, methods, and variables.
+<h3>Error Message Guidelines</h3>
+
+Exceptions thrown in Spark should be associated with standardized and actionable
+error messages.
+
+Error messages should answer the following questions:
+
+- **What** was the problem?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+When writing error messages, you should:
+
+- Use active voice
+- Avoid time-based statements, such as promises of future support
+- Use the present tense to describe the error and provide suggestions
+- Provide concrete examples
+- Avoid sounding accusatory, judgmental, or insulting
+- Be direct
+- Use human-readable text for user-facing errors
Review comment:
You're right, human-readable is likely the wrong phrase in this case. A less expansive suggestion could be: "Do not use programming jargon in user-facing errors"
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] karenfeng commented on pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
karenfeng commented on pull request #332:
URL: https://github.com/apache/spark-website/pull/332#issuecomment-821300143
Good idea, @gatorsmile! Posted the screenshots for both the contributing page (the condensed error message guidelines are in the middle) and the full error message guidelines page.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] karenfeng commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
karenfeng commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r616076060
##########
File path: error-message-guidelines.md
##########
@@ -0,0 +1,383 @@
+---
+layout: global
+title: Error message guidelines
+type: "page singular"
+navigation:
+ weight: 5
+ show: true
+---
+
+## Error Message Guidelines
+
+This guide is a reference for composing standardized and actionable
+error messages in Apache Spark.
+
+### Include What, Why, and How
+
+Exceptions thrown from Spark should answer the Five W's and How:
+
+- **Who** encountered the problem?
+- **What** was the problem?
+- **When** did the problem happen?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+The context provided by exceptions can help answer **who** (usually the
+user), **when** (usually included in the log via <code>log4j</code>), and **where**
+(usually included in the stack trace). However, these answers alone are
+often insufficient for the user to solve the problem. An error message
+that answers the remaining questions
+--- **what**, **why**, and **how** --- minimizes user frustration.
+
+#### Explicitly answer What, Why and How
+
+In many cases, the error message should explicitly answer **what**,
+**why**, and **how**.
+
+##### Example 1
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/569fb133d09e24e4ed56ed7efff641512d98b01b/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L160">
+ Unable to generate an encoder for inner class {} without access to the
+ scope that this class was defined in. Try moving this class out of its
+ parent class.
+ </a>
+</code>
+
+- **What:** Unable to generate encoder inner class.
+- **Why:** Did not have access to the scope that the class was defined
+ in.
+- **How:** Try moving this class out of its parent class.
+
+##### Example 2
+
+If the proposed fix (**how**) feels arbitrary, providing an explanation
+for **why** the error occurred can reduce user frustration.
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/03dd33cc982ebb3de4354274ac49da31521b8195/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L498">
+ <span style="background-color: #ffcccc">Unsupported</span> function name {}.
+ </a>
+</code>
+
+- **What:** Unsupported function name.
+- **Why:** Unclear.
+- **How:** Unclear.
+
+**After**
Review comment:
Good catch, thanks!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615336105
##########
File path: error-message-guidelines.md
##########
@@ -0,0 +1,383 @@
+---
+layout: global
+title: Error message guidelines
+type: "page singular"
+navigation:
+ weight: 5
+ show: true
+---
+
+## Error Message Guidelines
+
+This guide is a reference for composing standardized and actionable
+error messages in Apache Spark.
+
+### Include What, Why, and How
+
+Exceptions thrown from Spark should answer the Five W's and How:
+
+- **Who** encountered the problem?
+- **What** was the problem?
+- **When** did the problem happen?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+The context provided by exceptions can help answer **who** (usually the
+user), **when** (usually included in the log via <code>log4j</code>), and **where**
+(usually included in the stack trace). However, these answers alone are
+often insufficient for the user to solve the problem. An error message
+that answers the remaining questions
+--- **what**, **why**, and **how** --- minimizes user frustration.
+
+#### Explicitly answer What, Why and How
+
+In many cases, the error message should explicitly answer **what**,
+**why**, and **how**.
+
+##### Example 1
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/569fb133d09e24e4ed56ed7efff641512d98b01b/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L160">
+ Unable to generate an encoder for inner class {} without access to the
+ scope that this class was defined in. Try moving this class out of its
+ parent class.
+ </a>
+</code>
+
+- **What:** Unable to generate encoder inner class.
+- **Why:** Did not have access to the scope that the class was defined
+ in.
+- **How:** Try moving this class out of its parent class.
+
+##### Example 2
+
+If the proposed fix (**how**) feels arbitrary, providing an explanation
+for **why** the error occurred can reduce user frustration.
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/03dd33cc982ebb3de4354274ac49da31521b8195/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L498">
+ <span style="background-color: #ffcccc">Unsupported</span> function name {}.
+ </a>
+</code>
+
+- **What:** Unsupported function name.
+- **Why:** Unclear.
+- **How:** Unclear.
+
+**After**
Review comment:
It seems that we need to add a matching `**Before**`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] karenfeng commented on pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
karenfeng commented on pull request #332:
URL: https://github.com/apache/spark-website/pull/332#issuecomment-822724594
Thanks for the review @dongjoon-hyun! Let me know if I missed any comments, or if you have any further improvements to suggest.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun merged pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun merged pull request #332:
URL: https://github.com/apache/spark-website/pull/332
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615336365
##########
File path: error-message-guidelines.md
##########
@@ -0,0 +1,383 @@
+---
+layout: global
+title: Error message guidelines
+type: "page singular"
+navigation:
+ weight: 5
+ show: true
+---
+
+## Error Message Guidelines
+
+This guide is a reference for composing standardized and actionable
+error messages in Apache Spark.
+
+### Include What, Why, and How
+
+Exceptions thrown from Spark should answer the Five W's and How:
+
+- **Who** encountered the problem?
+- **What** was the problem?
+- **When** did the problem happen?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+The context provided by exceptions can help answer **who** (usually the
+user), **when** (usually included in the log via <code>log4j</code>), and **where**
+(usually included in the stack trace). However, these answers alone are
+often insufficient for the user to solve the problem. An error message
+that answers the remaining questions
+--- **what**, **why**, and **how** --- minimizes user frustration.
+
+#### Explicitly answer What, Why and How
+
+In many cases, the error message should explicitly answer **what**,
+**why**, and **how**.
+
+##### Example 1
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/569fb133d09e24e4ed56ed7efff641512d98b01b/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L160">
+ Unable to generate an encoder for inner class {} without access to the
+ scope that this class was defined in. Try moving this class out of its
+ parent class.
+ </a>
+</code>
+
+- **What:** Unable to generate encoder inner class.
+- **Why:** Did not have access to the scope that the class was defined
+ in.
+- **How:** Try moving this class out of its parent class.
+
+##### Example 2
+
+If the proposed fix (**how**) feels arbitrary, providing an explanation
+for **why** the error occurred can reduce user frustration.
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/03dd33cc982ebb3de4354274ac49da31521b8195/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L498">
+ <span style="background-color: #ffcccc">Unsupported</span> function name {}.
+ </a>
+</code>
+
+- **What:** Unsupported function name.
+- **Why:** Unclear.
+- **How:** Unclear.
+
+**After**
+
+*Function name {} <span style="background-color: #ccffcc">is invalid. Temporary functions cannot belong to a
+catalog. Specify a function name with one or two parts.</span>*
+
+- **What:** Invalid function name.
+- **Why:** Temporary functions cannot belong to a catalog.
+- **How:** Specify a function name with one or two parts.
+
+#### Implicitly answer How
+
+Not all error messages should be this verbose. Sometimes, explicitly
+explaining **how** to resolve the problem would be redundant.
+
+##### Example 1
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/e5d972e84e973d9a2e62312dc471df30c35269bc/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L63">
+ Invalid pivot column {}. Pivot columns must be comparable.
+ </a>
+</code>
+
+- **What:** Invalid pivot column.
+- **Why:** Pivot columns must be comparable.
+- **How (*****implied by Why*****):** Use comparable pivot columns.
+
+##### Example 2
+
+**Before**
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/9809a2f1c5187205c81542dbdc84b71db535f6e1/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryCompilationErrors.scala#L325">
+ Cannot specify window frame for {} function
+ </a>
+</code>
+
+- **What:** Cannot specify window frame for the function.
+- **Why**: Unclear.
+- **How:** Unclear.
+
+**After**
+
+<code style="white-space:normal">
+ Cannot specify frame for window expression {}. <span style="background-color: #ccffcc">Window expression
+ contains mismatch between function frame {} and specification frame {}.</span>
+</code>
+
+- **What:** Cannot specify the frame for the window expression.
+- **Why:** Window expression contains mismatch between function frame
+ and specification frame.
+- **How (*****implied by Why*****):** Match the function frame and
+ specification frame.
+
+##### Example 3
+
+**Before**
+
+<code style="white-space:normal">
+ <a href="https://github.com/apache/spark/blob/aff6c0febb40d9713895ba00d8c77ba00f04bd16/sql/catalyst/src/main/scala/org/apache/spark/sql/errors/QueryExecutionErrors.scala#L93">
+ Cannot parse any decimal.
+ </a>
+</code>
+
+- **What:** Cannot parse decimal.
+- **Why**: Unclear.
+- **How:** Unclear.
+
+**After**
+
+<code style="white-space:normal">
+ Invalid decimal {}; <span style="background-color: #ccffcc">encountered error while parsing at position {}.</span>
+</code>
+
+- **What:** Invalid decimal.
+- **Why**: The decimal parser encountered an error at the specified
+ position.
Review comment:
Like line 143, shall we move this `position` to line 141?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] karenfeng commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
karenfeng commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r616080585
##########
File path: error-message-guidelines.md
##########
@@ -0,0 +1,383 @@
+---
+layout: global
+title: Error message guidelines
+type: "page singular"
+navigation:
+ weight: 5
+ show: true
+---
+
+## Error Message Guidelines
+
+This guide is a reference for composing standardized and actionable
+error messages in Apache Spark.
+
+### Include What, Why, and How
+
+Exceptions thrown from Spark should answer the Five W's and How:
Review comment:
Whoops, good catch. Thanks!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615337391
##########
File path: contributing.md
##########
@@ -186,6 +186,29 @@ that maintainability, consistency, and code quality come first. New algorithms s
- Come with a reasonable expectation of developer support.
- Have `@Since` annotation on public classes, methods, and variables.
+<h3>Error Message Guidelines</h3>
+
+Exceptions thrown in Spark should be associated with standardized and actionable
+error messages.
+
+Error messages should answer the following questions:
+
+- **What** was the problem?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+When writing error messages, you should:
+
+- Use active voice
+- Avoid time-based statements, such as promises of future support
+- Use the present tense to describe the error and provide suggestions
+- Provide concrete examples
+- Avoid sounding accusatory, judgmental, or insulting
Review comment:
Just a question. Did we have the error message in this category before? I'm wondering why `You must` is categorized into this category.
> You must specify an amount for {}
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615337391
##########
File path: contributing.md
##########
@@ -186,6 +186,29 @@ that maintainability, consistency, and code quality come first. New algorithms s
- Come with a reasonable expectation of developer support.
- Have `@Since` annotation on public classes, methods, and variables.
+<h3>Error Message Guidelines</h3>
+
+Exceptions thrown in Spark should be associated with standardized and actionable
+error messages.
+
+Error messages should answer the following questions:
+
+- **What** was the problem?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+When writing error messages, you should:
+
+- Use active voice
+- Avoid time-based statements, such as promises of future support
+- Use the present tense to describe the error and provide suggestions
+- Provide concrete examples
+- Avoid sounding accusatory, judgmental, or insulting
Review comment:
Just a question. Did we have the error message in this category before? I'm wondering why `You must` is categorized this.
> You must specify an amount for {}
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org
[GitHub] [spark-website] dongjoon-hyun commented on a change in pull request #332: Add error message guidelines
Posted by GitBox <gi...@apache.org>.
dongjoon-hyun commented on a change in pull request #332:
URL: https://github.com/apache/spark-website/pull/332#discussion_r615338243
##########
File path: contributing.md
##########
@@ -186,6 +186,29 @@ that maintainability, consistency, and code quality come first. New algorithms s
- Come with a reasonable expectation of developer support.
- Have `@Since` annotation on public classes, methods, and variables.
+<h3>Error Message Guidelines</h3>
+
+Exceptions thrown in Spark should be associated with standardized and actionable
+error messages.
+
+Error messages should answer the following questions:
+
+- **What** was the problem?
+- **Why** did the problem happen?
+- **How** can the problem be solved?
+
+When writing error messages, you should:
+
+- Use active voice
+- Avoid time-based statements, such as promises of future support
+- Use the present tense to describe the error and provide suggestions
+- Provide concrete examples
+- Avoid sounding accusatory, judgmental, or insulting
+- Be direct
+- Use human-readable text for user-facing errors
Review comment:
Although I understand the meaning, I'd like to recommend to revise this guideline.
Given the example, this guideline aims to discourage `!=` and to recommend a natural sentence. Technically, both are human-readable text, aren't they?
```
- RENAME TABLE source and destination databases do not match: '{}' !=</span> '{}
- RENAME TABLE source and destination databases do not match. The source database is {}, but the destination database is {}.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@spark.apache.org
For additional commands, e-mail: commits-help@spark.apache.org