Add words on how to report bugs.

BUGS.txt

@@ -0,0 +1,137 @@
+
+HOW TO REPORT BUGS
+
+Before I can fix an error, I need to understand what the problem
+is. Try to explain what is wrong and why you think it is wrong. Please
+try to include sample code that demonstrates the problem. Include a
+description of what ivl does that is wrong, and what you expect should
+happen.
+
+* The Compiler Doesn't Compile
+
+If the tools don't compile, I need to know about the compilation tools
+you are using. Specifically, I need to know:
+
+	- Operating system and processor type,
+	- Compiler w/ version,
+	- Library version, and
+	- anything else you think relevent.
+
+Be aware that I do not have at my disposal a porting lab. I have the
+alpha on my desk, and the Linux/Intel box with logic analyzer and
+'scope hanging off it.
+
+* The Compiler Crashes
+
+No compiler should crash, no matter what kind of garbage is fed to
+it. If the compiler crashes, you definitely found a bug and I need to
+know about it.
+
+Ivl internally checks its state while it works, and if it detects
+something wrong that it cannot recover from, it will abort
+intentionally. The "assertion failure" message that the program
+prints in the process of dying is very important. It tells me where in
+the source the bad thing happened. Include that message in the bug
+report.
+
+If there are not assertion messages, I need to know that as well.
+
+I also need a complete test program that demonstrates the crash.
+
+* It Doesn't Like My Perfectly Valid Program(tm)
+
+I need to know what you think is right that ivl gets wrong. Does it
+reject your "Perfectly Valid Program(tm)" or does it compile it but
+give incorrect results? The latter is the most insidious as it doesn't
+scream out to be fixed unless someone is watching closely. However, if
+I get a sample program from you, and I can compile it, and I run it
+and nuclear junk doesn't fall from the sky, I'm moving on to the next
+problem.
+
+So, if your program doesn't compile, tell me so, tell me where the
+error occurs, and include a complete Perfectly Valid Test Program(tm).
+You tell me that it fails to compile for you, and I find that it
+compiles for me, then hooray I fixed it. It can happen, you
+know. What's on my disk is more recent then the latest snapshot.
+
+If your program does compile, but generates incorrect output, I need
+to know what it says and what you think it should say. From this I can
+take your sample program and work on ivl until it gets the proper
+results. For this to work, of course, I first need to know what is
+wrong with the output. Spell it out, because I've been known to miss
+the obvious. Compiler writers often get buried in the details of the
+wrong problem.
+
+* It Generates Incorrect Target Code (XNF, EDIF/LPM, etc.)
+
+As ivl adds target code generators, there will be cases where errors
+in the output netlist format occur. This is a tough nut because I
+might not have all the tools to test the target format you are
+reporting problems with. However, if you clearly explain what is right
+and wrong about the generated netlist, I will probably be able to fix
+the problem. It may take a few iterations.
+
+In this case, if possible include not only the sample verilog program,
+but the generated netlist file(s) and a clear indication of what went
+wrong. If it is not clear to me, I will ask for clarification.
+
+* The Output is Correct, But Less Then Ideal
+
+If the output is strictly correct, but just not good enough for
+practical use, I would like to know. These sorts of problems are
+likely to be more subjective then a core dump, but are worthy of
+consideration. However, realize that outright errors will get more
+attention then missed optimizations.
+
+THE MAKING OF A GOOD TEST PROGRAM
+
+If at all possible, please submit a complete source file that
+demonstrates the problem. If the error occurs after elaboration,
+please include a top level module in the program that is suitable for
+the target format. If I have to write the module myself, I might not
+write it in a way that tickles the bug. So please, send all the
+Verilog source (after preprocessing) that I need to invoke the error.
+
+Also, include the command line you use to invoke the compiler. For
+example:
+
+	ivl foo.vl -o foo.cc -tvvm
+	ivl foo.vl -s starthere
+
+If the error occurs with the null target (``-tnull'') then a top level
+module may not be needed as long as the ``-s <name>'' switch is
+given.
+
+So when you send a test case, ask yourself "Can poor overworked Steve
+invoke the error without any Verilog other then what is included?"
+
+HOW TO SEND PATCHES
+
+Bug reports with patches are very welcome, especially if they are
+formatted such that I can inspect them, decide that they are obviously
+correct, and apply them without worry.
+
+I prefer context or unified diffs as emitted by diff from GNU
+diffutils.  Human beings can read such things, and they are resilient
+to changing originals. A good set of flags to diff are ``diff -cNB''.
+With such diffs, I can look at the changes you are offering and
+probably tell at a glance that they are plausible. Then I can use
+patch(1) to apply them. Or I can apply them by hand.
+
+However, if you send patches, *please* tell me what this patch is
+supposed to accomplish, and if appropriate include a test program that
+demonstrates the efficacy of the patch. (If I have no idea what the
+patch is for, I will ask for clarification before applying it.)
+
+COPYRIGHT ISSUES
+
+Icarus Verilog is Copyright (c) 1998-1999 Stephen Williams except
+where otherwise noted. Minor patches are covered as derivative works
+(or editorial comment or whatever the appropriate legal term is) and
+folded into the rest of ivl. However, if a submission can reasonably
+be considered independently copyrightable, it's yours and I encourage
+you to claim it with appropriate copyright notices. This submission
+then falls under the "otherwise noted" category.
+
+I must insist that any copyright material submitted for inclusion
+include the GPL license notice as shown in the rest of the source.