Index: docs/language/informal/README.md |
diff --git a/docs/language/informal/README.md b/docs/language/informal/README.md |
new file mode 100644 |
index 0000000000000000000000000000000000000000..5774998a3e2007c3aea9078d4bcc8f27cdaad687 |
--- /dev/null |
+++ b/docs/language/informal/README.md |
@@ -0,0 +1,17 @@ |
+This directory contains "informal specifications". |
+ |
+In order to move faster and get better feedback, we implement and iterate on |
+language changes before the full official specification has been written. Still, |
+the implementers need *something* to go on. |
+ |
+For that, the language team writes "informal specifications". These are |
+intended to be precise enough for a good faith implementer to correctly |
+understand the syntax and semantics of the language, but without all of the |
+laborious detail of the complete specification. |
+ |
+Once the feature has been implemented, tested, and we are confident in it, the |
+language team will write the real text in the language specification and the |
+document here becomes deprecated and no longer canonical. |
+ |
+Until then, while the feature is in progress, a live pull request for the |
+informal spec is the source of truth for the feature. |