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:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@spark.apache.org
For additional commands, e-mail: commits-h...@spark.apache.org
