The first step to take when you have a problem with BSF is to read the manual entry for the task or concept that is giving you trouble. In particular, check the meaning of a task's attributes and nested elements. Perhaps an attribute is available that would provide the behavior you require. If you have problems with the manual itself, you can submit a documentation bug report (see below) to help us improve the BSF documentation.

If you're still having a problem, the next step is to try and gather additional information about what BSF is doing.

The trace output from a BSF run is helpful in determining causes of failure, and is useful in bug reports.

After examining the debug output, if you still believe that the problem you are having is caused by BSF, chances are that someone else may have already encountered this problem, and perhaps it has been fixed. The next step, therefore, may be to try a nightly build of BSF to see if the problem has been fixed. Nightly builds for BSF are available from the Jakarta web site. While BSF nightly builds are typically quite stable and are used by Gump to build many other Jakarta projects, these builds should nonetheless be treated as experimental. Note that nightly builds do not build many of the optional tasks the come with BSF. A snapshot of these optional tasks is occasionally uploaded to the nightly download area. However, even this snapshot does not contain every optional task.

If the current nightly build doesn't resolve your problem, it is possible that someone else has reported the issue. It is time to look at the Apache Bug Database (jira). This system is easy to use, and it will let you search the currently open and resolved bugs to see if your problem has already been reported. If your problem has been reported, you can see whether any of the developers have commented, suggesting workarounds, or the reason for the bug, etc. Or you may have information to add (see about creating and modifying bug reports below), in which case, go right ahead and add the information. If you don't have any additional information, you may just want to vote for this bug, and perhaps add yourself to the CC list to follow the progress of this bug.

By this time, you may have decided that there is an unreported bug in BSF. You have a few choices at this point. You can send an email to the bsf-user mailing list to see if others have encountered your issue and find out how they may have worked around it. If after some discussion, you feel it is time to create a bug report, this is a simple operation in the bug database. Please try to provide as much information as possible in order to assist the developers in resolving the bug. Please try to enter correct values for the various inputs when creating the bug, such as which version of BSF you are running, and on which platform, etc. Once the bug is created, you can also add attachments to the bug report.

What information should you include in your bug report? The easiest bugs to fix are those that are most easily reproducible, so it is really helpful if you can produce a small test case that exhibits the problem. In this case, you would attach the build file and any other files necessary to reproduce the problem, probably packed together in an archive. If you can't produce a test case, you should try to include a snippet from your build file and the relevant sections from the verbose or debug output from BSF. Try to include the header information where BSF states the version, the OS and VM information, etc. As debug output is likely to be very large, it's best to remove any output that is not relevant. Once the bug is entered into the bug database, you will be kept informed by email about progress on the bug. If you receive email asking for further information, please try to respond, as it will aid in the resolution of your bug.

Sometimes, you may find that BSF just doesn't do what you need it to. It isn't a bug, as such, since BSF is working the way it is supposed to work. Perhaps it is some additional functionality for a task that hasn't been thought of yet, or maybe a completely new task. For these situations, you will want to raise an enhancement request. Enhancement requests are managed using the same Apache Bug Database described above. These are just a different type of bug report. If you look in the bug database, you will see that one of the severity settings for a bug is "Enhancement". Just fill the bug report in, set the severity of the bug to "Enhancement", and state in the description how you would like to have BSF enhanced. Again, you should first check whether there are any existing enhancment requests that cover your needs. If so, just add your vote to these.

If you aren't satisfied with just filing a bug report, you can try to find the cause of the problem and provide a fix yourself. The best way to do that is by working with the latest code from CVS. Alternatively, you can work with the source code available from the source distributions. If you are going to tackle the problem at this level, you may want to discuss some details first on the bsf-dev mailing list. Once you have a fix for the problem, you may submit the fix as a patch to either the bsf-dev mailing list, or enter the bug database as described above and attach the patch to the bug report. Using the bug database has the advantage of being able to track the progress of your patch.

If you have a patch to submit and are sending it to the bsf-dev mailing list, prefix "[PATCH]" to your message subject. Please include any relevant bug numbers. Patch files should be created with the -u option of the diff or cvs diff command. For example:



diff -u Javac.java.orig Javac.java > javac.diffs



or, if you have source from CVS:



cvs diff -u Javac.java > javac.diffs



Note: You should give your patch files meaningful names. This makes it easier for developers who need to apply a number of different patch files.