Icarus PAL -- Bugs

Presumably, you are reading this page because you believe you found a problem with Icarus PAL. That's great, I very much appreciate it and I do what I can to encourage effective bug reports. There is a searchable reporting system to help you to help yourself, and to help me track problems. However, in order to get a bug fixed, I still need that first bug report, and if you are like me, the labor of writing a convincing bug report (or the fear of writing an unconvincing bug report) gets in the way, especially if you find a work around. In spite of the run-around you've learned to expect from commercial software vendors, I encourage you to try to make a good report, and this page is here to help you understand what I need.

The most important rule, though, is please browse the rest of this page before sending a bug report. It is much easier for both of us if we understand what is expected.

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 samples that demonstrate the problem. Include a description of what Icarus PAL does that is wrong, and what you expect should happen. If the problem is with one of the commands, please include in your report the command line flags you used. (This last step is often overlooked, and sometimes important.)

Report bugs to me at <ipal-bugs@icarus.com>, the geda-dev mailing list or the owner/maintainer of the component. If you send your report to ipal-bugs, the report will be entered into the bug management system. This is not a slight to you, I will respond to you personally. The advantage to you of using the trouble reporting system is that your report will be archived, indexed and tracked. This makes it easier for me to keep track of things. The URL for the bug tracking system is <http://www.icarus.com/cgi-bin/ipal-bugs>.

So now what sorts of problems might you report? Let's see...

The Tools Don't Compile

Icarus PAL is not very demanding on the compiler, but configuration can go wrong. I probably only need to know:

Operating system and processor type,
Compiler w/ 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 a logic analyzer and 'scope hanging off it.

The Tools Crash

This might mean that one of the Icarus PAL programs crashes, or you are using the library and it is crashing your program. The former is a bit easier for me to deal with, as often there is an assertion message that I can use to track down the problem. In this case, it would be most handy if you can submit the inputs that make the program crash, as well as the command line switches that you used.

If you think the library is crashing your program, I will need different information. Basically, I require whatever is needed for me to reproduce the problem. This may include some source code, input files, and information about your platform.

It Doesn't Like My Perfectly Valid Fuse Map(tm)

I need to know what you think is right that Icarus PAL gets wrong. Does it reject your "Perfectly Valid Fuse Map(tm)" or does it read it but give incorrect results? If I get a sample JEDEC file from you, and I can view it, I'm assuming all is well and moving on to the next problem.

In other words, make clear what Icarus PAL is doing wrong, and send tests that I can easily use.

The Making of a Good Test Program

If you are reporting a bug in the library, you may find yourself sending test programs. If at all possible, please submit a complete that demonstrates the problem. I need to be able to reproduce the problem, so please include instructions for repeating the problem with the test program. I may need to know about compiler flags to get the desired results.

So when you send a test case, ask yourself "Can poor overworked Steve invoke the error without any code other then what is included?" And while we are at it, please place a copyright notice in your test program and include a GPL license statement if you can. (See COPYRIGHT ISSUES below.)

How To Send Patches

Bug reports with patches are very welcome, if they are formatted such that I can inspect them, decide that they are obviously correct, and apply them without worry. It is important that I be able to read submitted patches.

I prefer context 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.

I find replacement files particularly inconvenient. Replacement files do not clearly highlight what they change, and they are particularly difficult to merge with local changes to the file. Please, if your changes are restricted to a single file, it is easy for you to use the diff command on that file, and diffs of this form are infinitely easier for me to accept, approve and apply.

Now that you have the perfect patch, 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.) The test program may well find its way into the regression test suite, so include copyright notices.

COPYRIGHT ISSUES

Icarus PAL is Copyright (c) 2000 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 Icarus PAL. 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. Examples of this might include architecture files that you submit.

I must insist that any copyright material submitted for inclusion include the GPL license notice as shown in the rest of the source.

And this of course brings up the issue of copyright status of test programs sent as bug reports. Basically, I presume when sample code is sent as part of a bug report that you are granting me license to redistribute it (properly attributed, of course) in a test suite or other forum. In particular, code that might reveal trade secrets and intellectual property should not be sent to me. If you are reporting a problem you are encountering in such code, try making a contrived example that does the trick. Just realize that I signed no non-disclosure agreements, so am not bound to non-disclosure.

$Id: bugs.html,v 1.7 2000/09/17 18:14:43 steve Exp $