... | ... | @@ -31,12 +31,64 @@ Use a comma or space (but not semicolon) to separate your email address from the |
|
|
## What to put in a bug report
|
|
|
|
|
|
|
|
|
The name of the bug-reporting game is: facts, facts, facts. Don't omit them because "Oh, they won't be interested…"
|
|
|
The Trac bug report system has various fields. Here's how to fill them in:
|
|
|
|
|
|
- **Your email or user name**. If you are logged in this will be filled in automatically. If you are only logged in as *guest* then please consider replacing it with your email address. That way we can ask you questions, and you'll get email from Trac when something happens to your bug.
|
|
|
|
|
|
- **Short summary**. This is what appears in one-bug-per line lists, so try to make it as informative as you can.
|
|
|
|
|
|
- **Type** says what kind of Trac ticket this is:
|
|
|
|
|
|
- Bug: something wrong with GHC.
|
|
|
- Feature request: something you would like GHC to do
|
|
|
- Task: something we intend to do sometime (for use by GHC developers only)
|
|
|
- Merge: job done, but must be merged to stable branch (for use by GHC developers only)
|
|
|
|
|
|
- **Severity**. How much this bug matters to you.
|
|
|
|
|
|
- **Full description**. This is where you describe your bug in details. See "What information to provide" below. Use the [wiki markup](trac-wiki-misc) in your description, especially `{{{` ... `}}}` brackets to mark up literal code.
|
|
|
|
|
|
- **Component**, **Version**, **Operating system**, **Architecture** all help to describe the setup that failed. Please pay particular attention to **version**, which is the version of GHC that you are running.
|
|
|
|
|
|
- **Priority** and **Milestone**. Please do not fill in these fields. We use them to organise our priorities. The **severity** field lets you say how important the bug is to you.
|
|
|
|
|
|
- **Assign to**, **Difficulty**, **Test case**. For use by GHC developers; please don't fill these in.
|
|
|
|
|
|
|
|
|
See also [GHC working conventions](working-conventions).
|
|
|
|
|
|
|
|
|
## Full description: what information to provide in the body of your bug report
|
|
|
|
|
|
|
|
|
The name of the bug-reporting game is: facts, facts, facts. Don't omit them because "Oh, they won't be interested…".
|
|
|
|
|
|
**The absolutely key thing is that we must be able to reproduce the bug**. Without this, we are virtually helpless; we know there's a problem but we usually can make no progress with fixing it. The easiset way to help us reproduce the bug is to provide us with a program that elicits it:
|
|
|
|
|
|
- The smaller the better. It costs you real work to "boil down" the bug from a big program to a small one, but the plain truth is that the easier the bug is to reproduce, and the smaller the test program (= smaller debug output), the more likely we are to fix it.
|
|
|
- The fewer dependencies the better. If your program depends on many libraries, it's harder for us to reproduce.
|
|
|
|
|
|
|
|
|
One way to cut down programs is to replace library functions with definitions like
|
|
|
|
|
|
```wiki
|
|
|
displayWidget :: This -> IO That
|
|
|
displayWidget = error "urk"
|
|
|
```
|
|
|
|
|
|
|
|
|
and thereby avoid the necessity for the supporting library.
|
|
|
|
|
|
|
|
|
Here is a check-list of things to cover in your description:
|
|
|
|
|
|
1. The source code of the program that shows the bug. You can give the code inline, or attach a file, or attach a tarball.
|
|
|
1. What kind of machine are you running on, and exactly what version of the operating system are you using? (on a Unix system, `uname -a` or `cat /etc/motd` will show the desired information.) In the bug tracker, this information can be given in the "Architecture" and "Operating system" fields.
|
|
|
1. What version of GCC are you using? `gcc -v` will tell you.
|
|
|
1. Run the sequence of compiles/runs that caused the offending behaviour, cut-and-paste the whole session into the bug report. We'd prefer to see the whole thing.
|
|
|
1. Add the `-v` flag when running GHC, so we can see exactly what was run, what versions of things you have, etc.
|
|
|
1. Add the `-dcore-lint` flag when running GHC. This adds some significant internal consistency-checking, which often nails bugs early.
|
|
|
1. What is the program behaviour that is wrong, in your opinion?
|
|
|
1. If practical, please attach or send enough source files for us to duplicate the problem.
|
|
|
1. If you are a Hero and track down the problem in the compilation-system sources, please send us patches (either `darcs send`, plain patches, or just whole files if you prefer). |
|
|
|
|
|
|
|
|
If you are a Hero and track down the problem in the compilation-system sources, please [send us patches](working-conventions/submissions). |