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
Copy file name to clipboardExpand all lines: tool-developers.md
+12-2Lines changed: 12 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,9 +19,9 @@ The most important principle of error codes is that they exist primarily as a me
19
19
The code links the output in the user's IDE or terminal to text that describes the error or warning.
20
20
Codes should follow these principles:
21
21
* A code should always have the same meaning forever
22
-
* Codes may be retired and introduced
22
+
* Codes may be retired or introduced in new releases
23
23
24
-
Aside from that, tools may assign codes however they wish.
24
+
Aside from that, tools may assign codes however they wish, and need not do anything but begin emitting them.
25
25
There is an optional, recommended code assignment strategy later in this document.
26
26
27
27
Error codes are associated with the _meaning_ of a message, rather than its text.
@@ -30,6 +30,16 @@ That is, rephrasing a message or modifying its presentation should not result in
30
30
Splitting one message into two should result in at least one new code: if one of the new messages is a natural continuation of the prior one and one is a specific special case, then the special case should get a new code, but if neither is clearly the successor, then the prior code should be retired and fresh codes should be assigned to each of the new messages.
31
31
Like most forms of communication, this is a matter for human judgment that can't be automatically enforced.
32
32
33
+
### Error Code Lifecycle
34
+
35
+
Because error codes exist in a project-administered namespace, there is no need to check in with anyone else to start emitting a new error code.
36
+
A new release may add or remove as many codes as the developers wish, so long as a code is never used with two completely different meanings.
37
+
There is no obligation to document every error code prior to a release.
38
+
The codes are an opportunity for community members to help out, not a new obligation for busy tool developers.
39
+
40
+
Once a project has committed to the meaning of a code (typically by merging a PR that emits it into their `main` or `master` branch, but the specifics are up to each project), the message index will accept documentation.
41
+
Users and develoeprs need not wait for a release to begin documenting error codes.
42
+
33
43
### Namespaces
34
44
35
45
The Haskell Foundation administers the error code namespaces - please open an issue here or have a chat with the HF executive team to get a namespace assignment.
0 commit comments