Add documentation on how to report bugs.

diff --git a/BUGS.markdown b/BUGS.markdown
new file mode 100644 (file)
index 0000000..a214cb9
--- /dev/null
+++ b/BUGS.markdown
@@ -0,0 +1,104 @@
+Reporting bugs
+==============
+
+Please report any issues on
+[github](https://github.com/apitrace/apitrace/issues).
+
+Always include the following information:
+
+* operating system name and version
+
+* OpenGL/D3D driver name and version
+
+
+Proprietary/confidential applications
+=====================================
+
+Issues should be preferably filed on github to facilitate collaborative
+development and for future reference.
+
+Access to applications source code is not required -- binaries are sufficient.
+
+If the bug happens with a proprietary application, and you don't want to
+publicly release the application and/or any data collected from it, then
+alternatively you can provide the necessary application and/or data via e-mail,
+to *jose dot r dot fonseca at gmail dot com*.
+
+If it is not technically/legally feasible for you to provide application and/or
+data at all, then you must be either:
+
+* develop and provide a test application, stripped-down of all
+  proprietary/confidential data, but that can reproduce the issue;
+
+* be willing/able to do the investigation of the issue, namely to identify the
+  root cause of the issue (e.g., which OpenGL call is not properly handled and
+  why), using all necessary tools (such as debuggers).
+
+Failure to do so will render the apitrace authors powerless to address the
+issue.
+
+
+Attachments
+===========
+
+github issue tracker doesn't support attachments.
+
+Please attach long logs to https://gist.github.com/ and paste the URL into the
+issue description.
+
+For big attachments, such as traces, please upload it temporarily to a web
+server you control, or use a file upload service such as
+http://www.megaupload.com/ or http://dropbox.com/ and paste the URL into the
+issue description.
+
+Trace files are only slightly compressed (for performance reasons).  You can
+further reduce their size when attaching/uploading by compressing with
+[XZ](http://tukaani.org/xz/) or [7-Zip](http://www.7-zip.org/).
+
+
+Bugs on tracing
+===============
+
+For bugs that happen while tracing (e.g., crashes while tracing the
+application, or incorrect traces) please:
+
+* provide information on how to obtain the application;
+
+* describe how you were using it when the issue happened.
+
+
+Bugs on retracing/GUI
+=====================
+
+For bugs on retracing (e.g. crashes when retracing the application,
+incorrect inconsistent rendering, or viewing with the GUI) please:
+
+* provide the trace file;
+
+* describe the results you got, and what results you were expecting.
+
+
+Obtaining stack back-traces
+===========================
+
+
+Linux/MacOSX
+------------
+
+Please rebuild apitrace with debugging information, by passing
+`-DCMAKE_BUILD_TYPE=Debug` to cmake.
+
+To obtain a stack back-trace, run the application with gdb from a terminal:
+
+    $ gdb --args application arg1 arg2 ...
+    (gdb) run
+    ...
+    (gdb) bt
+
+
+Windows
+-------
+
+WRITEME
+
+

diff --git a/CMakeLists.txt b/CMakeLists.txt
index e840f21d193608b386d33edf84f72ea3511e1ea9..1f1ee6f6a2ee6090d7c87726827e1c5dfc7b0b52 100755 (executable)
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -425,7 +425,13 @@ endif ()
 ##############################################################################
 # Packaging
 
-install (FILES LICENSE README.markdown TODO.markdown DESTINATION doc)
+install (
+    FILES
+        BUGS.markdown
+        LICENSE
+        README.markdown
+        TODO.markdown
+    DESTINATION doc)
 
 set (CPACK_PACKAGE_VERSION_MAJOR "1")
 set (CPACK_PACKAGE_VERSION_MINOR "0")

diff --git a/README.markdown b/README.markdown
index f56412aea7c02914173ca6d9e0af3752ba08495c..f551ad2f9cf9a69581d4b864d91261a750d014da 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -217,7 +217,7 @@ Side by side retracing
 ----------------------
 
 In order to determine which draw call a regression first manifests one could
-generate snapshots for every draw call, using the -S option.  That is, however,
+generate snapshots for every draw call, using the `-S` option.  That is, however,
 very inefficient for big traces with many draw calls.
 
 A faster approach is to run both the bad and a good GL driver side-by-side.