Add the first documented Stack message

Author: david-christiansen

CONTRIBUTING.md

@@ -48,14 +48,20 @@ To document a new error code, the following workflow can be convenient.
 
 ### Task Lists
 
-We keep track of which errors are being worked on, and which still require documentation,
+We keep track of which GHC errors are being worked on, and which still require documentation,
 using a bunch of issues:
 
 - [All error codes that still need documenting are collected here](https://github.com/haskellfoundation/error-message-index/issues/162). This issue contains links to individual issues for every error, allowing the list to be updated as PRs are merged. These individual issues for every error may also contain helpful links to test cases, suggestions on examples, and useful metadata to a contributor.
 - There is also an (incomplete) list of issues tagged `good first issue`; these are errors which are especially good for newer contributors to document (no incredibly esoteric type-level errors that are hard to understand, let alone describe!): https://github.com/haskellfoundation/error-message-index/labels/good%20first%20issue
 - Issues related to improving the site, the workflow for contributing, or other information are tagged `error-message-index-site`: https://github.com/haskellfoundation/error-message-index/labels/error-message-index-site
 - Issues related to improving, clarifying, or extending existing documentation are tagged `error-message-index-improvements`: https://github.com/haskellfoundation/error-message-index/labels/error-message-index-improvements
 
+## Building Stack with Error Codes
+
+The next release of Stack will also include error codes. Until it is
+released, building a Git version (which just requires an existing
+install of Stack) is sufficient to get the codes.
+
 ## Contributing New Messages
 
 The Haskell Message Index is generated from a collection of files on
@@ -64,8 +70,8 @@ disk using Hakyll. Inside the top-level of the site source, there is a
 a message whose name is the message code. This subdirectory contains a
 file `index.md` that describes the message. Additionally,
 subdirectories of the message directory may represent examples - each
-example contains a file `index.md` as well as a number of Haskell
-files that represent the example.
+example contains a file `index.md` as well as a number of Haskell,
+Cabal, or YAML files that represent the example.
 
 A message with ID `GHC-123` and two examples might have the following structure:
 
@@ -87,10 +93,10 @@ named as specified here, while the other components may vary.
 You can also use the `makeFolder.sh` templating script. Usage is as follows:
 
 ```bash
-./makeFolder.sh <NUMERIC-ERROR-CODE> <HaskellModuleName>
+./makeFolder.sh <NAMESPACE>-<NUMERIC_ERROR_CODE> <HaskellModuleName>
 ```
 
-This will generate a folder called `GHC-NUMERIC_ERROR_CODE` containing an empty `index.md` file, a subfolder called `example1` with a corresponding `index.md`, and two blank `before`/`after` Haskell source files.
+This will generate a folder called `NAMESPACE-NUMERIC_ERROR_CODE` containing an empty `index.md` file, a subfolder called `example1` with a corresponding `index.md`, and two blank `before`/`after` Haskell source files. Use `GHC` as `NAMESPACE` to document GHC error messages, and `S` as `NAMESPACE` to document Stack errors.
 
 ### Message Descriptions
 
@@ -133,7 +139,6 @@ field. All `.hs` files are shown in the list of files for the
 example. The `index.md` file should explain how the files illustrate
 the message.
 
-
 ## Contributing to the Site
 
 The site is generated using [Hakyll](https://jaspervdj.be/hakyll/).

message-index/messages/S-6602/empty/after/empty.yaml

@@ -0,0 +1 @@
+resolver: lts-19.17

message-index/messages/S-6602/empty/before/empty.yaml

@@ -0,0 +1,14 @@
+---
+title: Stack does not accept empty YAML files
+---
+
+When run with an empty YAML file, Stack fails to parse it. In particular, `stack --stack-yaml empty.yaml build` results in the error:
+```
+Error: [S-6602]
+Could not parse '/PATH/TO/empty.yaml':
+Aeson exception:
+Error in $: parsing ProjectAndConfigMonoid failed, expected Object, but encountered Null
+See http://docs.haskellstack.org/en/stable/yaml_configuration/
+```
+
+This can be fixed by specifying a resolver, which is the minimal `stack.yaml` configuration.

message-index/messages/S-6602/empty/index.md

@@ -0,0 +1,14 @@
+---
+title: Could not parse YAML configuration file
+summary: Test summary
+severity: error
+introduced: 2.10.0
+---
+
+This error occurs when Stack is unable to parse a `stack.yaml` file. The error covers the following situations:
+
+ * The specified configuration file does not exist
+ * The configuration file is not well-formed YAML
+ * The file is well-formed YAML but does not match the expected data schema
+ 
+The expected file format is described in [the Stack documentation](https://docs.haskellstack.org/en/stable/yaml_configuration/).

message-index/messages/S-6602/index.md

@@ -0,0 +1 @@
+resolver: lts-19.17

message-index/messages/S-6602/not-yaml/after/not.yaml

@@ -0,0 +1 @@
+]

message-index/messages/S-6602/not-yaml/before/not.yaml

@@ -0,0 +1,13 @@
+---
+title: Not a YAML file
+---
+
+This `stack.yaml` file is not syntactically valid YAML. The error that results from `stack --stack-yaml not.yaml build` is:
+```text
+Error: [S-6602]
+Could not parse '/PATH/TO/not.yaml':
+YAML parse exception at line 0, column 0,
+while parsing a block node:
+did not find expected node content
+See http://docs.haskellstack.org/en/stable/yaml_configuration/
+```

message-index/messages/S-6602/not-yaml/index.md

@@ -8,8 +8,11 @@ import qualified Data.Aeson as JSON
 import qualified Data.Aeson.KeyMap as KM
 import Data.Binary (Binary)
 import Data.Data (Typeable)
+import Data.Foldable (for_)
 import Data.Functor ((<&>))
 import Data.List (find, lookup, nub, sort)
+import Data.List.NonEmpty (NonEmpty (..))
+import qualified Data.List.NonEmpty as NE
 import qualified Data.Map.Strict as Map
 import Data.Maybe (fromMaybe, listToMaybe, mapMaybe)
 import Data.Monoid (mappend)
@@ -40,14 +43,15 @@ main = hakyll $ do
     route idRoute
     compile copyFileCompiler
 
-  match "messages/*/*/**.hs" $
-    version "raw" $ do
-      route idRoute
-      compile getResourceBody
+  for_ exampleExtensions $ \ext -> do
+    match (fromGlob $ "messages/*/*/**." <> ext) $
+      version "raw" $ do
+        route idRoute
+        compile getResourceBody
 
-  match "messages/*/*/**.hs" $ do
-    route idRoute
-    compile copyFileCompiler
+    match (fromGlob $ "messages/*/*/**." <> ext) $ do
+      route idRoute
+      compile copyFileCompiler
 
   match "messages/*/*/index.md" $
     version "nav" $ do
@@ -131,12 +135,16 @@ main = hakyll $ do
 
   -- Needed for flagInfo below
   match "warning-sets/warning-sets-9.5.txt" $ do
-    compile $ getResourceBody
+    compile getResourceBody
 
   match "templates/*" $ compile templateBodyCompiler
 
 --------------------------------------------------------------------------------
 
+-- | The file extensions to be shown in example lists
+exampleExtensions :: NonEmpty String
+exampleExtensions = "hs" :| ["yaml", "cabal"]
+
 breadcrumbField :: [Identifier] -> Compiler (Context String)
 breadcrumbField idents =
   (messageTitleField <>) . breadcrumbCtx <$> traverse (load @String . setVersion (Just "nav")) idents
@@ -185,8 +193,13 @@ getExampleFiles = do
     ["messages", id, exampleName, _mdFile] -> pure (id, exampleName)
     _ -> fail "Not processing an example"
 
-  before <- loadAll (fromGlob ("messages/" <> id <> "/" <> exampleName <> "/before/*.hs") .&&. hasVersion "raw")
-  after <- loadAll (fromGlob ("messages/" <> id <> "/" <> exampleName <> "/after/*.hs") .&&. hasVersion "raw")
+  let beforePattern = foldl1 (.||.) $ exampleExtensions <&> \ext ->
+        fromGlob ("messages/" <> id <> "/" <> exampleName <> "/before/*." <> ext)
+      afterPattern = foldl1 (.||.) $ exampleExtensions <&> \ext ->
+        fromGlob ("messages/" <> id <> "/" <> exampleName <> "/after/*." <> ext)
+
+  before <- loadAll (beforePattern .&&. hasVersion "raw")
+  after <- loadAll (afterPattern .&&. hasVersion "raw")
   let allNames = sort $ nub $ map (takeFileName . toFilePath . itemIdentifier) $ before ++ after
   pure $
     [ Item