@cindex Octave
@smalldisplay
Most of this appendix was taken from the
@uref{http://@/www.gnu.org/@/software/@/octave/, Octave} documentation.
@end smalldisplay

@cindex bug reports
@cindex problem reports
@noindent
Bug reports play an important role in making Enblend and Enfuse
reliable and enjoyable.

@cindex LaunchPad
@cindex bug database, LaunchPad
@cindex LaunchPad, bug database
When you encounter a problem, the first thing to do is to see if it is
already known.  To this end visit the package's
@uref{https://@/launchpad.net/, LaunchPad} bug
@uref{@value{CFG::PACKAGE_BUGREPORT}, database}.  Search it for your
particular problem.  If it is not known, please report it.

In order for a bug report to serve its purpose, you must include the
information that makes it possible to fix the bug.


@section Have You Really Found a Bug?

If you are not sure whether you have found a bug, here are some
guidelines:

@itemize
@item
If Enblend or Enfuse get a fatal signal, for any options or input
images, that is a bug.

@item
If Enblend or Enfuse produce incorrect results, for any input
whatever, that is a bug.

@item
If Enblend or Enfuse produce an error message for valid input, that is
a bug.

@item
If Enblend or Enfuse do not produce an error message for invalid
input, that is a bug.
@end itemize


@section How to Report Bugs

The fundamental principle of reporting bugs usefully is this: report
all the facts.  If you are not sure whether to state a fact or leave
it out, state it.  Often people omit facts because they think they
know what causes the problem and they conclude that some details do
not matter.  Play it safe and give a specific, complete example.

Keep in mind that the purpose of a bug report is to enable someone to
fix the bug if it is not known.  Always write your bug reports on the
assumption that the bug is not known.

Try to make your bug report self-contained.  If we have to ask you for
more information, it is best if you include all the previous
information in your response, as well as the information that was
missing.

@noindent
To enable someone to investigate the bug, you should include all these
things:

@itemize
@item
The exact version and configuration of Enblend or Enfuse.  You can get
this by running it with the options @option{--version} and
@option{--verbose}.

@item
A complete set of input images that will reproduce the bug.  Strive
for a minimal set of @emph{small}@footnote{Images of a size less than
1500@classictimes{}1000 pixels qualify as small.} images.

@item
The type of machine you are using, and the operating system name and
its version number.

@item
A complete list of any modifications you have made to the source.  Be
precise about these changes.  Show a @command{diff} for them.

@item
Details of any other deviations from the standard procedure for
installing Enblend and Enfuse.

@item
The @emph{exact command line} you use to call Enblend or Enfuse, which
then triggers the bug.

@noindent
Examples:

@example
~/local/bin/enblend -v \
    --fine-mask \
    --optimizer-weights=3:2 --mask-vectorize=12.5% \
    image-1.png image-2.png
@end example

@noindent
or:

@example
/local/bin/enfuse \
    --verbose \
    --exposure-weight=0 --saturation-weight=0 --entropy-weight=1 \
    --gray-projector=l-star \
    --entropy-cutoff=1.667% \
    layer-01.ppm layer-02.ppm layer-03.ppm
@end example

@cindex Hugin
@cindex KImageFuser
If you call Enblend or Enfuse from within a @acronym{GUI} like, for
example, @uref{http://@/hugin.sourceforge.net/, Hugin} or
@uref{http://@/panorama.dyndns.org/@/index.php?@/lang=@/en&@/subject=@/KImageFuser&@/texttag=@/KImagefuser,
KImageFuser} by @sc{Harry van der Wolf}, copy&paste or write down the
command line that launches Enblend or Enfuse.

@item
A description of what behavior you observe that you believe is
incorrect.  For example, ``The application gets a fatal signal,'' or,
``The output image contains black holes.''

Of course, if the bug is that the application gets a fatal signal,
then one cannot miss it.  But if the bug is incorrect output, we might
not notice unless it is glaringly wrong.
@end itemize


@section Sending Patches for Enblend or Enfuse

If you would like to write bug fixes or improvements for Enblend or
Enfuse, that is very helpful.  When you send your changes, please
follow these guidelines to avoid causing extra work for us in studying
the patches.  If you do not follow these guidelines, your information
might still be useful, but using it will take extra work.

@itemize
@item
Send an explanation with your changes of what problem they fix or what
improvement they bring about.  For a bug fix, just include a copy of
the bug report, and explain why the change fixes the bug.

@item
Always include a proper bug report for the problem you think you have
fixed.  We need to convince ourselves that the change is right before
installing it.  Even if it is right, we might have trouble judging it
if we do not have a way to reproduce the problem.

@item
Include all the comments that are appropriate to help people reading
the source in the future understand why this change was needed.

@item
Do not mix together changes made for different reasons.  Send them
individually.

If you make two changes for separate reasons, then we might not want
to install them both.  We might want to install just one.

@item
Use the version control system to make your diffs.  Prefer the
@uref{http://@/en.wikipedia.org/@/wiki/@/Diff#@/Unified_@/format,
unified diff} format: @code{hg diff --unified 4}.

@item
You can increase the probability that your patch gets applied by
basing it on a recent revision of the sources.
@end itemize
