X-Git-Url: https://review.openocd.org/gitweb?p=openocd.git;a=blobdiff_plain;f=BUGS;h=4381c87b5d093071bc030f369ce6c99afa877034;hp=6b08ba4ca5fdcaa608590725403edba8818a6ce7;hb=0f0545d6dc8e8bf1b472c9ef2afcb76739d22f80;hpb=23fd80f2b658395d24056f6b84c8483f428ab33d

diff --git a/BUGS b/BUGS
index 6b08ba4ca5..4381c87b5d 100644
--- a/BUGS
+++ b/BUGS
@@ -1,37 +1,65 @@
+// This file is part of the Doxygen Developer Manual
 /** @page bugs Bug Reporting
 
 Please report bugs by subscribing to the OpenOCD mailing list and
 posting a message with your report:
 
-	openocd-development@lists.berlios.de
+	openocd-devel@lists.sourceforge.net
 
-To minimize work for OpenOCD developers, you can include
-all the information below.  If you feel that some of the
-items below are unnecessary for a clear bug report, you
-leave them out.
+Also, please check the Trac bug database to see if a ticket for
+the bug has already been opened.  You might be asked to open
+such a ticket, or to update an existing ticket with more data.
+
+	https://sourceforge.net/apps/trac/openocd/
+
+To minimize work for OpenOCD developers, you should try to include
+all of the information listed below.  If you feel that some of the
+items below are unnecessary for a clear bug report, you may leave
+them out; likewise, feel free to include additional information
+that may be important.
 
 - Target PCB/board description
-- Config scripts
+- Configuration scripts
 - OpenOCD command line
 - List of commands issued or GDB operations performed
 - Expected result
 - Actual result
-- Logs using @c debug_level 3 (e.g. add '-d 3' to the command line)
-- If this is a regression, include logs for working and broken version
-- If this is a regression, please find out the precise version that
-  caused the regression.  This can be done via a binary search; For
-  example: if testing version 550 works but 600 fail, then try 575, etc.
+- Logs using <code>debug_level 3</code> (or with '-d 3' on the command line)
+- If the report is for a regression:
+  - Include logs for both working and broken versions.
+  - Find the precise version that caused the regression by binary search.
+    You can use "git bisect" to expedite this binary search:
+    http://www.kernel.org/pub/software/scm/git/docs/git-bisect.html
+
+If possible, please develop and attach a patch that helps to expose or
+solve the reported problem.  See the HACKING file for information
+about that process.
+
+Attach all files directly to your posting.  The mailing list knows to
+transform attachments to links, but attachments must be less than 300KB
+in total.
 
-- If OpenOCD is crashing, you can use GDB to get a trace:@par
+@section bugscrashdump Obtaining Crash Backtraces
+
+If OpenOCD is crashing, there are two very effective things you can do to
+improve your chances of getting help on the development mailing list.
+
+Try to reproduce the problem using the dummy JTAG interface to allow other developers to replicate
+your problem robustly and use GDB to get a trace:@par
 @code
+% OPENOCDSRC/configure --enable-dummy ...
+% openocd -f interface/dummy.cfg -f target/xxx.cfg
+=> SEGFAULT
 % gdb --args openocd ....
 (gdb) run
 (gdb) bt
 => here a stack trace is dumped.
 @endcode
 
-- To run or debug the in-tree executable (not recommended), you must
-  use libtool to set up the correct shared library paths:
+@section bugsintreedebug Running and Debugging In-Tree
+
+To run or debug the in-tree executable (not recommended), you must
+use libtool to set up the correct shared library paths:
 @code
   libtool gdb --args openocd ....
 @endcode
@@ -39,8 +67,8 @@ or the more pedantic (and forward-compatible):
 @code
   libtool --mode=execute gdb --args openocd ....
 @endcode
-- Attach files directly to the posting.  The mailing list knows to
-transform attachments to links so you will not be bloating anyones mail
-box.  Please keep attachments to less than 100KB.
 
  */
+/** @file
+This file contains the @ref bugs page.
+*/