improve bug reporting section

1 files changed, 110 insertions, 22 deletions

diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst
index 61d38787..1e276f7d 100644
--- a/docs/testers/howto.rst
+++ b/docs/testers/howto.rst
@@ -5,34 +5,125 @@ Howto for Testers
 
 This document covers a how-to guide to:
 
-#. Quickly fetching latest development code, and
-#. Reporting bugs.
+#. :ref:`Where and how report bugs for Bitmask <reporting_bugs>`, and
+#. :ref:`Quickly fetching latest development code <fetchinglatest>`.
 
 Let's go!
 
+.. _reporting_bugs:
+
+Reporting bugs
+--------------
+
+Report all the bugs you can find to us! If something is not quite working yet,
+we really want to know. Reporting a bug to us is the best way to get it fixed
+quickly, and get our unconditional gratitude.
+
+It is quick, easy, and probably the best way to contribute to Bitmask
+development, other than submitting patches.
+
+.. admonition:: Reporting better bugs
+
+   New to bug reporting? Here you have a `great document about this noble art
+   <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_.
+
+Where to report bugs
+^^^^^^^^^^^^^^^^^^^^
+
+We use the `Bitmask Bug Tracker <https://leap.se/code/projects/eip-client>`_,
+although you can also use `Github issues
+<https://github.com/leapcode/bitmask_client/issues>`_. But we reaaaally prefer if you
+sign up in the former to send your bugs our way.
+
+What to include in your bug report
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* The symptoms of the bug itself: what went wrong? What items appear broken, or
+  do not work as expected? Maybe an UI element that appears to freeze?
+* The Bitmask version you are running. You can get it by doing `bitmask
+  --version`, or you can go to `Help -> About Bitmask` menu.
+* The installation method you used: bundle? from source code? debian package?
+* Your platform version and other details: Ubuntu 12.04? Debian unstable?
+  Windows 8? OSX 10.8.4? If relevant, your desktop system also (gnome, kde...)
+* When does the bug appear? What actions trigger it? Does it always
+  happen, or is it sporadic?
+* The exact error message, if any.
+* Attachments of the log files, if possible (see section below).
+
+Also, try not to mix several issues in your bug report. If you are finding
+several problems, it's better to issue a separate bug report for each one of
+them.
+
+Attaching log files
+^^^^^^^^^^^^^^^^^^^
+
+If you can spend a little time getting them, please add some logs to the bug
+report. They are **really** useful when it comes to debug a problem. To do it:
+
+Launch Bitmask in debug mode. Logs are way more verbose that way::
+
+  bitmask --debug
+
+Get your hand on the logs. You can achieve that either by clicking on the "Show
+log" button, and saving to file, or directly by specifying the path to the
+logfile in the command line invocation::
+  
+  bitmask --debug --logfile /tmp/bitmask.log
+
+Attach the logfile to your bug report.
+
+Need human interaction?
+^^^^^^^^^^^^^^^^^^^^^^^
+
+You can also find us in the ``#leap-dev`` channel on the `freenode network
+<https://freenode.net>`_. If you do not have a IRC client at hand, you can
+`enter the channel via web
+<http://webchat.freenode.net/?nick=leaper....&channels=%23leap-dev&uio=d4>`_.
+
+
 .. _fetchinglatest:
 
 Fetching latest development code
 ---------------------------------
 
-To allow rapid testing in different platforms, we have put together a quick script that is able to fetch latest development code. It more or less does all the steps covered in the :ref:`Setting up a Work Enviroment <environment>` section, only that in a more compact way suitable (ahem) also for non developers. 
+Normally, testing the latest :ref:`client bundles <standalone-bundle>` should be
+enough. We are engaged in a two-week release cycle with minor releases that are
+as stable as possible.
+
+However, if you want to test that some issue has *really* been fixed before the
+next release is out (if you are testing a new provider, for instance), you are
+encouraged to try out the latest in the development branch. If you do not know
+how to do that, or you prefer an automated script, keep reading for a way to
+painlessly fetch the latest development code.
+
+We have put together a script to allow rapid testing in different platforms for
+the brave souls like you. It more or less does all the steps covered in the
+:ref:`Setting up a Work Enviroment <environment>` section, only that in a more
+compact way suitable (ahem) also for non developers.  
 
 .. note::
 
-   In the near future, we will be using :ref:`standalone bundles <standalone-bundle>` with the ability to self-update.
+   At some point in the near future, we will be using :ref:`standalone bundles
+   <standalone-bundle>` with the ability to self-update.
 
 Install dependencies
 ^^^^^^^^^^^^^^^^^^^^
-First, install all the base dependencies plus git, virtualenv and development files needed to compile several extensions::
+First, install all the base dependencies plus git, virtualenv and development
+files needed to compile several extensions::
 
    apt-get install openvpn git-core python-dev python-pyside python-setuptools python-virtualenv
 
-.. TODO Should review these dependencies. ^^
+.. TODO Should review these dependencies. I think python-sqlite is missing, we
+   have an issue for that^^
+
+.. TODO we really should keep the dependencies in a single file that we are able to
+   include, to avoid phasing out.
+
 
 Bootstrap script
 ^^^^^^^^^^^^^^^^
 .. note::
-   This will fetch the *develop* branch. If you want to test another branch, just change it in the line starting with *pip install...*. Alternatively, bug kali so she add an option branch to a decent script.
+   This will fetch the *develop* branch. If you want to test another branch, just change it in the line starting with *pip install...*. Alternatively, bug kali so she add an option branch to an improved script.
 
 .. note::
    This script could make use of the after_install hook. Read http://pypi.python.org/pypi/virtualenv/
@@ -47,15 +138,22 @@ Download and source the following script in the parent folder where you want you
 
 Tada! If everything went well, you should be able to run bitmask by typing::
 
-    bitmask
+    bitmask --debug
 
 Noticed that your prompt changed? That was *virtualenv*. Keep reading...
 
 Activating the virtualenv
 ^^^^^^^^^^^^^^^^^^^^^^^^^
-The above bootstrap script has fetched latest code inside a virtualenv, which is an isolated, *virtual* python local environment that avoids messing with your global paths. You will notice you are *inside* a virtualenv because you will see a modified prompt reminding it to you (*bitmask-testbuild* in this case).
+The above bootstrap script has fetched latest code inside a virtualenv, which is
+an isolated, *virtual* python local environment that avoids messing with your
+global paths. You will notice you are *inside* a virtualenv because you will see
+a modified prompt reminding it to you (*bitmask-testbuild* in this case).  
 
-Thus, if you forget to *activate your virtualenv*, bitmask will not run from the local path, and it will be looking for something else in your global path. So, **you have to remember to activate your virtualenv** each time that you open a new shell and want to execute the code you are testing. You can do this by typing::
+Thus, if you forget to *activate your virtualenv*, bitmask will not run from the
+local path, and it will be looking for something else in your global path. So,
+**you have to remember to activate your virtualenv** each time that you open a
+new shell and want to execute the code you are testing. You can do this by
+typing::
 
     $ source bin/activate
 
@@ -87,11 +185,11 @@ You should be able to cd into the downloaded repo and pull latest changes::
     (bitmask-testbuild)$ cd src/bitmask
     (bitmask-testbuild)$ git pull origin develop
 
-However, as a tester you are encouraged to run the whole bootstrap process from time to time to help us catching install and versioniing bugs too.
+However, you are encouraged to run the whole bootstrapping process from time to time to help us catching install and versioning bugs too.
 
 Testing the packages
 ^^^^^^^^^^^^^^^^^^^^
-When we have a release candidate for the supported platforms (Debian stable, Ubuntu 12.04 by now), we will announce also the URI where you can download the rc for testing in your system. Stay tuned!
+When we have a release candidate for the supported platforms, we will announce also the URI where you can download the rc for testing in your system. Stay tuned!
 
 Testing the status of translations
 ----------------------------------
@@ -104,13 +202,3 @@ If you want to check the current status of bitmask localization in a language ot
 
 for running Bitmask with the spanish locales.
 
-Reporting bugs
---------------
-
-.. admonition:: Reporting better bugs
-
-   There is a great text on the art of bug reporting, that can be found `online <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_.
-
-.. TODO add a line with ref. to running Bitmask in debug mode...
-
-We use the `Bitmask Bug Tracker <https://leap.se/code/projects/eip-client>`_, although you can also use `Github issues <https://github.com/leapcode/bitmask/issues>`_.