package PDL::Bugs;

# How to get help diagnosing PDL problems and
# how to make and submit a useful bug report

__END__

=pod

=head1 NAME

PDL::Bugs - How to diagnose and report PDL problems

=head1 VERSION

version 1.0000

=head1 DESCRIPTION

This module explains how to get help with a PDL problem
and how, when, and where to submit a bug report.  In the
future it may be extended to provide some sort of automated
bug reporting capability.

=head1 IF YOU HAVE A PDL PROBLEM

The primary resource for support for the Perl Data Language
is via the PDL mailing lists.  The pdl-general list is for general
use and discussions and is the one to use for questions about
problems with PDL or PDL use for computation.  This
I<is almost always> the list to post to for PDL problems.

The pdl-devel list is I<specifically> for PDL development
and often contains discussions of a rather technical nature
relating to PDL internals.  This is I<not> the list for
general PDL discussion or questions:
L<http://pdl.perl.org/?page=mailing-lists>.

B<NOTE>: Both pdl-general and pdl-devel are read by the PDL
developers so you don't save time or increase the probability
of response by posting to pdl-devel or by cross-posting
to pdl-devel.  Please stick to pdl-general list posts unless
you want to talk PDL implementation and development.

B<NOTE>: There is also a PDL IRC channel which can be useful
for immediate questions if populated.  However, it has the
big disadvantage of not being easily searched or routinely
read by all PDL developers and users.  As a result, if you
get an answer there, it may be incorrect or incomplete
depending on who happens to be chatting at the time.  It
is definitely not readily searchable.

=head1 REPORTING BUGS

Please submit bug reports via the GitHub issue tracker at
L<https://github.com/PDLPorters/pdl/issues>.

where you can review the previously submitted bug reports.
Click on C<New issue> to generate a bug report.  If you do not
already have a GitHub account, you will need to
create one to submit the report.

Try to include any information you think might help someone
isolate, reproduce, and fix your problem.

At a I<minimum>, include the following information:

=over

=item *

PDL version number (e.g. PDL-2.007)

=item *

Perl version information.  Output from C<perl -v> or C<perl -V> (even better!)

=item *

Your operating System.  You can run the C<uname -a> command on many unix systems

=item *

The full output of C<perldl -V> 

If you are reporting a bug with an already installed PDL.  If the PDL
has compiled and built but not been installed, you may run
C<perl -Mblib perldl -V> from the top level of the PDL build directory.

=item *

The bug description and how to reproduce it.

Short examples using the PDL shells, C<pdl2> or C<perldl>, are excellent!
Don't forget to include needed input data (as small as possible) so that
the code can be run with a cut and paste.

=back

Other things that are often helpful:

=over

=item *

Details about your operating environment that might be related to the problem

=item *

Exact cut and pasted error or warning messages

=item *

The shortest, clearest code you can manage to write which reproduces the bug described.

=item *

A patch against the latest released version of this distribution which fixes this bug.

=back

Alternatively, send an e-mail report with the above
information (including the output of C<perldl -V>)
to the pdl-devel mailing list. See
L<http://pdl.perl.org/?page=mailing-lists>
for info on how to subscribe to this list.


=head1 BEFORE YOU SEND A REPORT

BEFORE you report a bug make sure you got the latest
release version of PDL, always available from CPAN,
check L<http://metacpan.org/pod/PDL>.

Also, you can check the FAQ at L<http://pdl.perl.org/?docs=FAQ&title=PDL::FAQ>.
and the mailing list archives for hints. You can find links to the
searchable archives at L<http://pdl.perl.org/?page=mailing-lists>.

and there is a Google enable search box on the top right of
L<http://pdl.perl.org> which usually gives the best results.


=head1 PATCHES

Patches can be submitted in several ways, in order of decreasing preference:

=over 4

=item 1

Fork the pdl repository on GitHub, make and test your changes, and submit a pull request;

=item 2

Edit (or suggesting an edit to) the files in-place on GitHub;

=item 3

Email a patch to the pdl-devel mailing list.

=back

Patches should be made against the latest released
PDL or, ideally, against the current git sources
which you can browse and check out at L<https://github.com/PDLPorters/pdl>.

Thanks,
The PDL developers.

=cut