Skip to content

Commit 0bedd37

Browse files
Clarify relationship between codes and projects
1 parent d8227af commit 0bedd37

File tree

1 file changed

+12
-2
lines changed

1 file changed

+12
-2
lines changed

tool-developers.md

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@ The most important principle of error codes is that they exist primarily as a me
1919
The code links the output in the user's IDE or terminal to text that describes the error or warning.
2020
Codes should follow these principles:
2121
* 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
2323

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.
2525
There is an optional, recommended code assignment strategy later in this document.
2626

2727
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
3030
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.
3131
Like most forms of communication, this is a matter for human judgment that can't be automatically enforced.
3232

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+
3343
### Namespaces
3444

3545
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

Comments
 (0)