Merge pull request #361 from haskellfoundation/stack

Add the first documented Stack message

Author: david-christiansen

.fend.yaml

@@ -5,6 +5,9 @@ skip:
     - message-index/js/highlight.min.js
     - message-index/js/tablefilter.js
 
+    # This one's empty and thus can't end with a newline
+    - message-index/messages/S-6602/empty/before/empty.yaml
+
   extension:
     - .hi
     - .o

.github/workflows/deploy.yml

@@ -13,8 +13,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Select GHC 9.2.4
-      run: ghcup set 9.2.4
+    - name: Install GHC 9.2.5
+      run: ghcup install ghc 9.2.5
+
+    - name: Select GHC 9.2.5
+      run: ghcup set ghc 9.2.5
 
     - name: Check out repo
       uses: actions/checkout@v3

.github/workflows/pullrequest-ci.yml

@@ -11,8 +11,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Select GHC 9.2.4
-      run: ghcup set 9.2.4
+    - name: Install GHC 9.2.5
+      run: ghcup install ghc 9.2.5
+
+    - name: Select GHC 9.2.5
+      run: ghcup set ghc 9.2.5
 
     - name: Check out repo
       uses: actions/checkout@v3

CONTRIBUTING.md

@@ -48,14 +48,23 @@ 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. An unreleased version
+of Stack can be obtained with Stack by using the command
+`stack upgrade --source-only --git`. However, if you used GHCup to
+install Stack, you should also use GHCup to upgrade Stack.
+
 ## Contributing New Messages
 
 The Haskell Message Index is generated from a collection of files on
@@ -64,8 +73,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 +96,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 +142,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,20 @@
+---
+title: Stack does not accept empty YAML files
+---
+
+When run with an empty YAML file, Stack fails to parse it. For example, `stack --stack-yaml empty.yaml build` results in the error:
+```
+Error: [S-6602]
+       Stack could not load and parse /PATH/TO/empty.yaml as a YAML
+       configuraton file.
+       
+       While loading and parsing, Stack encountered the following exception:
+       
+       Aeson exception:
+       Error in $: parsing ProjectAndConfigMonoid failed, expected Object, but encountered Null
+       
+       For help about the content of Stack's YAML configuration files, see (for the most recent release of
+       Stack) http://docs.haskellstack.org/en/stable/yaml_configuration/.
+```
+
+This error in a [project-level `stack.yaml` file](https://docs.haskellstack.org/en/stable/yaml_configuration/#project-specific-configuration) 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.9.3
+---
+
+This error occurs when Stack is unable to parse a YAML configuration file, which could be a project-level `stack.yaml` file or a global `config.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 formats are 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 @@
+]