.. _asking-for-help:

Asking for Help
===============

If you run into problems with ``yt``, you should feel **encouraged** to ask for
help -- whether this comes in the form of reporting a bug or emailing the
mailing list.  If something doesn't work for you, it's in everyone's best
interests to make sure that it gets fixed.

.. _mailing-list:

The Mailing List
----------------

The mailing list should be your first stop, every time and always.  If you are
having a problem, it might be something other people have struggled with and
fixed on their own, or it might be a bug -- in which case it has to be brought
to the attention of the developers!

There are two mailing lists,
`yt-users <http://lists.spacepope.org/listinfo.cgi/yt-users-spacepope.org>`_ and
`yt-dev <http://lists.spacepope.org/listinfo.cgi/yt-dev-spacepope.org>`_.  The
first should be used for asking for help, suggesting features and so on, and
the latter has more chatter about the way the code is developed and discussions
of changes and feature improvements.

If you email ``yt-users`` asking for help, there are several things you must
provide, or else we won't be able to do much:

#. What it is that went wrong, and how you knew it went wrong.
#. A traceback if appropriate -- but see :ref:`error-reporting` for some help with
   that.
#. If possible, the smallest number of steps that can reproduce the problem.
#. Which version of the code you are using.

When you email the list, providing this information can help the developers
understand what you did, how it went wrong, and any potential fixes or similar
problems they have seen in the past.  Without this context, it can be very
difficult to help out!

Installation Issues
-------------------

If you are having installation issues, and you've read the :ref:`installation`
section of the manual, you should *definitely* email the
``yt-users`` email list.  You should provide information about the host, the
version of the code you are using, and the output of ``yt_install.log`` from
your installation.  We are very interested in making sure that ``yt`` installs
everywhere!

Vanilla Usage Issues
--------------------

If you're running ``yt`` without having made any modifications to the code
base, please provide as much of your script as you are able to.  Submitting
both the script and the traceback to the pastebin (as described in :ref:`pastebin`)
is usually sufficient to reproduce the error.

Customization and Scripting Issues
----------------------------------

If you have customized ``yt`` in some way, or created your own plugins file (as
described in :ref:`plugin-file`) then it may be necessary to supply both your
patches to the source and the plugin file, if you are utilizing something
defined in that file.

How To Report A Bug
-------------------

The first step, when reporting a bug, is to identify the smallest piece of code
that reproduces the bug.

To submit a bug report, register an account on the 
`yt Trac site <http://yt.enzotools.org/wiki/>`_ and submit a 
`new ticket <http://yt.enzotools.org/newticket>`_.  Alternatively, email the
``yt-users`` mailing list and we will construct a new ticket in your stead.
