docs: Add a guide for writing diagnostic messages
Change-Id: I552a062931a3ce7a51189559b05c9275f7b205cf
Reviewed-on: https://dawn-review.googlesource.com/c/tint/+/51785
Reviewed-by: David Neto <dneto@google.com>
Kokoro: Kokoro <noreply+kokoro@google.com>
Commit-Queue: Ben Clayton <bclayton@google.com>
diff --git a/docs/diagnostics_guide.md b/docs/diagnostics_guide.md
new file mode 100644
index 0000000..00cdf41
--- /dev/null
+++ b/docs/diagnostics_guide.md
@@ -0,0 +1,125 @@
+# Tint diagnostic style guide
+
+This guide provides a set of best practices when writing code that emits
+diagnostic messages in Tint. These diagnostics are messages presented to the
+user in case of error or warning.
+
+The goal of this document is to have our diagnostic messages be clear and
+understandable to our users, so that problems are easy to fix, and to try and
+keep a consistent style.
+
+## Message style
+
+* Start diagnostic messages with a lower-case letter
+* Try to keep the message to a single sentence, if possible
+* Do not end the message with punctuation (full stop, exclamation mark, etc)
+
+**Don't:**
+
+```
+shader.wgsl:7:1 error: Cannot take the address of expression.
+```
+
+**Do:**
+
+```
+shader.wgsl:7:1 error: cannot take the address of expression
+```
+
+**Justification:**
+
+Succinct messages are more important than grammatical correctness. \
+This style matches the style found in most other compilers.
+
+## Prefer to use a `Source` location instead of quoting the code in the message
+
+**Don't:**
+
+```
+shader.wgsl:5:7 error: structure 'UBO' requires block decoration
+
+struct UBO {
+ ^^^
+```
+
+**Do:**
+
+```
+shader.wgsl:5:7 error: structure requires block decoration
+
+struct UBO {
+ ^^^
+```
+
+**Justification:**
+
+The highlighted line provides even more contextual information than the quoted
+source, and duplicating this information doesn't provide any more help to the
+developer.
+
+## Use `note` diagnostics for providing additional links to relevant code
+
+**Don't:**
+
+```
+shader.wgsl:5:11 error: type cannot be used in storage class 'storage' as it is non-host-shareable
+
+ cond : bool;
+ ^^^^
+```
+
+**Do:**
+
+```
+shader.wgsl:5:11 error: type cannot be used in storage class 'storage' as it is non-host-shareable
+
+ cond : bool;
+ ^^^^
+
+shader.wgsl:8:4 note: while instantiating variable 'StorageBuffer'
+
+var<storage> sb : StorageBuffer;
+ ^^
+```
+
+**Justification:**
+
+To properly understand some diagnostics requires looking at more than a single
+line. \
+Multi-source links can greatly reduce the time it takes to properly
+understand a diagnostic message. \
+This is especially important for diagnostics raised from complex whole-program
+analysis, but can also greatly aid simple diagnostics like symbol collision errors.
+
+## Use simple terminology
+
+**Don't:**
+
+```
+shader.wgsl:7:1 error: the originating variable of the left-hand side must not have an access(read) access attribute.
+```
+
+**Do:**
+
+```
+shader.wgsl:7:1 error: cannot assign to variable with [[access(read)]] decoration
+
+x = 1;
+^
+
+shader.wgsl:2:8 note: [[access(read)]] declared here
+
+var x : [[access(read)]] i32;
+ ^^^^^^^^^^^^^^^^
+```
+
+**Justification:**
+
+Diagnostics will be read by Web developers who may not be native English
+speakers and are unlikely to be familiar with WGSL specification terminology.
+Too much technical jargon can be intimidating and confusing. \
+Diagnostics should give enough information to explain what's wrong, and most
+importantly, give enough information so that a fix actionable.
+
+**Caution:** Be careful to not over simplify. Use the specification terminology
+if there's potential ambiguity by not including it.
