... | ... | @@ -237,27 +237,10 @@ previous state of affairs. |
|
|
* **Design choices**. A Note can be a good place to document the reasoning that led to a particular decision. Lacking the reasoning, someone might change the decision later, without realising the consequences.
|
|
|
* **Historical notes**. Sometimes it can be helpful to have a clearly-signposted section called "Historical note: blah blah" that describes some previous state of affairs. But the "Historical note" signpost signals that you don't need to read it to understand the current compiler.
|
|
|
|
|
|
## 3. Tickets, merge requests, and commits
|
|
|
|
|
|
### 3.1 Every MR should have a ticket
|
|
|
## 3. Warnings and assertions
|
|
|
|
|
|
* A *ticket* or *issue* (e.g. #21623) describes a *problem*.
|
|
|
* A *merge request* (e.g. !8750) describes a *solution*.
|
|
|
|
|
|
Every MR should point to the tickets that it solves. If you find yourself writing an MR without a ticket, consider opening a ticket that describes the problem you are solving.
|
|
|
|
|
|
### 3.2 Commit messages
|
|
|
|
|
|
Commit messages should aim to describe the changes a patch makes, e.g. "This patch modifies the Core simplifier to implement a new form of inlining pragma". Include ample information, in particular which commit the ticket fixed (if applicable) and which parts of the compiler are affected. This information is important to help GHC maintainers bisect regressions, compare features across branches, prepare release notes, etc.
|
|
|
|
|
|
The main content of a commit message should *not* be an explanation of the current implementation. This information is harder to find in a commit message, and (much worse) there is no explicit indication in the code that there is carefully-written information available about that particular line of code. Prefer instead writing an explanatory Note in the code, which you refer to in the commit message.
|
|
|
|
|
|
In short, commit messages describe *changes*, whereas comments explain the code *as it now is*.
|
|
|
|
|
|
|
|
|
## 4. Warnings and assertions
|
|
|
|
|
|
### 4.1 Warning flags
|
|
|
### 3.1 Warning flags
|
|
|
|
|
|
We are aiming to make the GHC code warning-free, for all warnings turned on by
|
|
|
|
... | ... | @@ -278,7 +261,7 @@ Currently we are some way from our goal, so some modules have a |
|
|
|
|
|
pragma; you are encouraged to remove this pragma and fix any warnings when working on a module.
|
|
|
|
|
|
### 4.2 Assertions
|
|
|
### 3.2 Assertions
|
|
|
|
|
|
GHC is littered with assertion checks like
|
|
|
```
|
... | ... | @@ -305,7 +288,7 @@ GHC.Utils.Panic.Plain: |
|
|
The `Ppr` versions take a `SDoc`; the plain versions reply on the `HasCallStack` to report the site of the failure.
|
|
|
|
|
|
|
|
|
## 5. Exports and Imports
|
|
|
## 4. Exports and Imports
|
|
|
|
|
|
### Exports
|
|
|
|
... | ... | @@ -359,7 +342,7 @@ In general we tend not to use `qualified` imports very often since we try choose |
|
|
|
|
|
One area where we do generally require export and import lists is in `hs-boot` files in order to clarify the reason for the boot file. This can help identify refactorings that would eliminate `hs-boot` files.
|
|
|
|
|
|
## 6. Compiler versions and language extensions
|
|
|
## 5. Compiler versions and language extensions
|
|
|
|
|
|
GHC must be compilable and validate by the previous two major GHC releases, and itself. It isn't necessary for it to be compileable by every intermediate development version.
|
|
|
|
... | ... | |