You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The message index is in the directory `message-index`.
9
9
10
-
## Using a Recent-Enough GHC
10
+
###Using a Recent-Enough Tool
11
11
12
-
Starting with version 9.6, GHC emits a unique error code with each error message.
13
-
If you want to contribute to the error message index, make sure that the version of GHC you have installed on your system is 9.6 or newer.
12
+
If you want to contribute to the error message index, make sure that the version of the tool you have installed on your system is new enough. See the [README](README.md) for a table of supported versions.
14
13
15
-
You can test which version of GHC you are using on the command line:
14
+
You can manage multiple versions of tools on your system using [GHCup](https://www.haskell.org/ghcup/).
16
15
17
-
```console
18
-
> ghc --version
19
-
The Glorious Glasgow Haskell Compilation System, version 9.6.1
20
-
```
16
+
## If You Know Which Message You Want to Document
17
+
18
+
Let's say you ran across `GHC-00000` in the wild, but it wasn't yet documented
19
+
in the Haskell Message Index. You know a little about it and would like to help
20
+
out. Here's how you can document it, using a command-line tool found in this
21
+
repository.
22
+
23
+
*(If you aren't familiar with git, you can simply [create a new
24
+
issue][new-issue] and someone will help you out.)*
21
25
22
-
You can manage multiple versions of GHC on your system using [GHCup](https://www.haskell.org/ghcup/).
2. Execute `runghc create-message-template.hs` and answer the questions.
30
+
3. Optionally commit the new files and create a draft pull request right away.
24
31
32
+
The files created by the tool will need further editing, but it's never too
33
+
early to get feedback by opening an issue or pull request.
25
34
26
-
## How to Document a GHC Error Code
35
+
Here is a collection of other tips:
27
36
28
-
To document a new error code, the following workflow can be convenient.
29
-
1. Choose a code that you'd like to document, say `GHC-123`
30
-
2. One of the following modules in the `compiler` directory of the GHC source tree will have a method called `diagnosticCode` in the instance of `Diagnostic`:
3. Once the code has been found, identify the error datatype constructor that produces it.
36
-
4. The documentation for the constructor will be in one of the following modules. Read the Haddock for an explanation of the error's meaning:
37
-
*`GHC.Tc.Errors.Types`
38
-
*`GHC.Driver.Errors.Types`
39
-
*`GHC.Parser.Errors.Types`
40
-
*`GHC.HsToCore.Errors.Types`
41
-
5. Find the pretty-printer for the error constructor in the `X.Ppr` module. This will give an idea of how the message looks when rendered.
42
-
6. Grep the `testsuite` directory for the error text to find examples that trigger the error.
43
-
7. Follow the instructions below to create a page with an explanation and examples.
37
+
- To explore the full range of documentation possibilities, see [The Anatomy of
38
+
a Message][anatomy] below. It explains each of the fields in the header above,
39
+
and includes another example document for reference.
40
+
- Remember to search the tool's source code for the error number to learn more about
41
+
it! Your error may already have code documentation or examples in the test suite.
42
+
- You can also look at other messages in the Index to get a feel for the
43
+
documentation style used in this project.
44
44
45
-
### Task Lists
45
+
[anatomy]: #reference-the-anatomy-of-a-message
46
46
47
-
We keep track of which GHC errors are being worked on, and which still require documentation,
48
-
using a bunch of issues:
47
+
## If You *Don't* Know Which Message You Want to Document
49
48
50
-
-[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.
49
+
Interested in helping out, but not sure where to start?
50
+
51
+
We keep track of which GHC errors are being worked on and which still require documentation.
52
+
53
+
-[All error codes that still need documenting are collected here](https://github.com/haskellfoundation/error-message-index/issues/307). 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.
51
54
- 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
52
-
- 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
53
55
- 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
54
56
55
-
## Stack and Error Codes
57
+
Once you've identified an issue you'd like to work on, refer to the previous section for how to get started.
58
+
59
+
## Helping With the Site Itself
56
60
57
-
Since version 2.9.3, Stack has supported error codes in the `S-` namespace.
61
+
There's more to the Message Index than messages!
62
+
63
+
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
64
+
65
+
66
+
The site is generated using [Hakyll](https://jaspervdj.be/hakyll/).
67
+
Pull requests that make it easier to understand or navigate are very
68
+
welcome. The main generator `site.hs` is formatted using
69
+
[Ormolu](https://github.com/tweag/ormolu). See [Technology
70
+
choices][tech-choices] below for more info.
58
71
59
-
## GHCup and Error Codes
72
+
[tech-choices]: #reference-technology-choices
73
+
74
+
### Running Locally
75
+
76
+
The site is built with the [Hakyll](https://jaspervdj.be/hakyll/) static site generator. To view the site locally, enter the `message-index` directory and run:
77
+
```console
78
+
$ cabal run -- site watch
79
+
```
80
+
or
81
+
```console
82
+
$ stack run -- site watch
83
+
```
84
+
which fires up an HTTP server on `localhost:8000`.
85
+
86
+
The error messages:
87
+
```
88
+
cabal: There is no <pkgname>.cabal package file or cabal.project file. To
89
+
build packages locally you need at minimum a <pkgname>.cabal file. You can use
90
+
'cabal init' to create one.
91
+
92
+
For non-trivial projects you will also want a cabal.project file in the root
93
+
directory of your project. This file lists the packages in your project and
94
+
all other build configuration. See the Cabal user guide for full details.
95
+
```
96
+
and
97
+
```
98
+
No executables found.
99
+
```
100
+
typically indicate that the site was started from the root of the repository, rather than the `message-index` directory.
60
101
61
-
Since version 0.1.19.0, GHCup has supported error codes in the `GHCup-` namespace.
102
+
### `create-message-template`
62
103
63
-
## Contributing New Messages
104
+
If you want to work on the scaffolding tool itself, note that it has a test script at
105
+
`test/create-message-template/test.sh`.
106
+
107
+
## Reference: The Anatomy of a Message
64
108
65
109
The Haskell Message Index is generated from a collection of files on
66
-
disk using Hakyll. Inside the top-level of the site source, there is a
67
-
`messages` directory. Within `messages`, each subdirectory represents
68
-
a message whose name is the message code. This subdirectory contains a
69
-
file `index.md` that describes the message. Additionally,
70
-
subdirectories of the message directory may represent examples - each
71
-
example contains a file `index.md` as well as a number of Haskell,
72
-
Cabal, or YAML files that represent the example.
110
+
disk using Hakyll. This section describes those files.
73
111
74
112
A message with ID `GHC-123` and two examples might have the following structure:
75
113
@@ -85,17 +123,17 @@ A message with ID `GHC-123` and two examples might have the following structure:
85
123
*`/messages/GHC-123/example2/before/Main.hs` - an example file that exhibits the error
86
124
*`/messages/GHC-123/example2/after/Main.hs` - an example file in which the error has been fixed
87
125
126
+
Inside the top level of the site source, there is a
127
+
`messages` directory. Within `messages`, each subdirectory represents
128
+
a message whose name is the message code. This subdirectory contains a
129
+
file `index.md` that describes the message. Additionally,
130
+
subdirectories of the message directory may represent examples - each
131
+
example contains a file `index.md` as well as a number of Haskell,
132
+
Cabal, or YAML files that represent the example.
133
+
88
134
The path components `messages` and the two `index.md` files must be
89
135
named as specified here, while the other components may vary.
90
136
91
-
You can also use the `makeFolder.sh` templating script. Usage is as follows:
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.
98
-
99
137
### Message Descriptions
100
138
101
139
Message descriptions (in `index.md` in the message directory) are
@@ -137,9 +175,16 @@ field. All `.hs` files are shown in the list of files for the
137
175
example. The `index.md` file should explain how the files illustrate
138
176
the message.
139
177
140
-
## Contributing to the Site
178
+
## Reference: Technology choices
141
179
142
-
The site is generated using [Hakyll](https://jaspervdj.be/hakyll/).
143
-
Pull requests that make it easier to understand or navigate are very
144
-
welcome. The main generator `site.hs` is formatted using
145
-
[Ormolu](https://github.com/tweag/ormolu).
180
+
The website generated by `message-index` uses a few JS components.
181
+
182
+
-[highlight.js](https://highlightjs.org/) for highlighting blocks of code. [License: BSD 3-Clause](https://github.com/highlightjs/highlight.js/blob/main/LICENSE).
183
+
-[TableFilter](http://www.tablefilter.com/) for the filtering functionality in the error message table. [License: MIT](https://github.com/koalyptus/TableFilter/blob/master/LICENSE).
184
+
185
+
Generally speaking, we choose technology for this site based on the following criteria:
186
+
187
+
* The build process for the site should be simple, relying on no build tools or package managers aside from `cabal` or `stack`
188
+
* CSS and Javascript code should be straightforward to maintain by someone who has only rudimentary front-end development skills
189
+
* The generated site should consist only of static files that can be hosted anywhere
190
+
* URLs should be predictable, and easy for external tools to generate (e.g. so IDEs can link to error documentation)
Haskell tooling emits a variety of errors, warnings, and other messages. In the latest development versions that are leading to the release of version 9.6.1, GHC emits a unique code for each message that allows it to be identified. This site allows these codes to be looked up, providing examples, context, and further information that can make them easier to understand.
4
+
**View the site →**https://errors.haskell.org/
5
5
6
-
Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on improving the site. Thanks!
7
-
8
-
If you're a Haskell tool developer who would like to integrate your project with the site, please refer to [tool-developers.md](./tool-developers.md) for recommendations regarding the error codes themselves.
9
-
10
-
## Running Locally
6
+
Haskell tooling emits a variety of errors, warnings, and other messages. In recent versions, some of these tools emit a unique code for each message that allows it to be identified. This site allows these codes to be looked up, providing examples, context, and further information that can make them easier to understand.
11
7
12
-
The site is built with the [Hakyll](https://jaspervdj.be/hakyll/) static site generator. To view the site locally, enter the `message-index` directory and run:
13
-
```console
14
-
$ cabal run -- site watch
15
-
```
16
-
or
17
-
```console
18
-
$ stack run -- site watch
19
-
```
20
-
which fires up an HTTP server on `localhost:8000`.
8
+
## Supported Tools
21
9
22
-
The error messages:
23
-
```
24
-
cabal: There is no <pkgname>.cabal package file or cabal.project file. To
25
-
build packages locally you need at minimum a <pkgname>.cabal file. You can use
26
-
'cabal init' to create one.
10
+
Today, the Haskell Message Index supports three tools. Any user-facing Haskell-related programming tools are welcome to join the effort!
27
11
28
-
For non-trivial projects you will also want a cabal.project file in the root
29
-
directory of your project. This file lists the packages in your project and
30
-
all other build configuration. See the Cabal user guide for full details.
31
-
```
32
-
and
33
-
```
34
-
No executables found.
35
-
```
36
-
typically indicate that the site was started from the root of the repository, rather than the `message-index` directory.
We welcome contributions that help to further progress the project towards its goals.
20
+
Contributions may come in the form of changes to the code base, as well as opening or commenting on issues and pull requests. You are warmly invited to participate!
41
21
42
-
Contributions may come in the form of changes to the code base, as well as opening or commenting on issues and pull requests.
43
-
44
-
All contributors are expected to follow the [Haskell Foundation's Code of Conduct](https://haskell.foundation/guidelines-for-respectful-communication/).
22
+
Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for instructions on improving the site. Thanks!
45
23
24
+
If you're a Haskell tool developer who would like to integrate your project with the site, please refer to [tool-developers.md](./tool-developers.md) for recommendations regarding the error codes themselves.
0 commit comments