diff options
author | 2006-12-08 11:38:06 +0000 | |
---|---|---|
committer | 2006-12-08 11:38:06 +0000 | |
commit | dc86f6ed17b8e7a702856baefc1d8c3dbd8e229a (patch) | |
tree | c264928fb78e3044f7bf3d8c2eafe2ca607561c4 /DOCS/xml/en/bugreports.xml | |
parent | bd007d8968b264bda27028d280c042f3e23178fa (diff) |
General reformatting round:
- fix some " -> "
- reindent with more consistency
- visual markup of <sect?> tags
- break overly long lines
- add missing <replaceable> tags in examples
- cola truck standing by
git-svn-id: svn://svn.mplayerhq.hu/mplayer/trunk@21537 b3059339-0415-0410-9bf9-f77b7e298cf2
Diffstat (limited to 'DOCS/xml/en/bugreports.xml')
-rw-r--r-- | DOCS/xml/en/bugreports.xml | 264 |
1 files changed, 175 insertions, 89 deletions
diff --git a/DOCS/xml/en/bugreports.xml b/DOCS/xml/en/bugreports.xml index d40a16723b..3122c3bca4 100644 --- a/DOCS/xml/en/bugreports.xml +++ b/DOCS/xml/en/bugreports.xml @@ -2,6 +2,7 @@ <!-- $Revision$ --> <appendix id="bugreports"> <title>How to report bugs</title> + <para> Good bug reports are a very valuable contribution to the development of any software project. But just like writing good software, good problem reports @@ -11,8 +12,14 @@ receive obscene amounts of email. So while your feedback is crucial in improving that you have to provide <emphasis role="bold">all</emphasis> of the information we request and follow the instructions in this document closely. </para> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_security"> <title>Report security releated bugs</title> + <para> In case you have found an exploitable bug and you would like to do the right thing and let us fix it before you disclose it, we would be happy @@ -25,33 +32,48 @@ Please don't delay your report to write proof-of-concept exploit, you can send that one with another mail. </para> </sect1> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_fix"> <title>How to fix bugs</title> + <para> If you feel have the necessary skills you are invited to have a go at fixing the bug yourself. Or maybe you already did that? Please read -<ulink url="../../tech/patches.txt">this short document</ulink> to find out how to -get your code included in <application>MPlayer</application>. The people on the +<ulink url="../../tech/patches.txt">this short document</ulink> to find out how +to get your code included in <application>MPlayer</application>. The people on +the <ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-dev-eng">MPlayer-dev-eng</ulink> mailing list will assist you if you have questions. </para> </sect1> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_regression_test"> <title>How to do regression testing using Subversion</title> + <para> A problem that can happen sometimes is 'it used to work before, now it doesn't anymore...'. Here is a step by step procedure to try to pinpoint when the problem occurred. This is <emphasis role="bold">not</emphasis> for casual users. </para> + <para> First, you'd need to fetch MPlayer's source tree from Subversion. Instructions can be found at the bottom of <ulink url="http://www.mplayerhq.hu/dload.html">this page</ulink>. </para> + <para> -You will have now in the mplayer/ directory an image of the Subversion tree, on the -client side. +You will have now in the mplayer/ directory an image of the Subversion tree, on +the client side. Now update this image to the date you want: <screen> cd mplayer/ @@ -62,6 +84,7 @@ Using this date format ensure that you will be able to extract patches according to the date at which they were committed, as in the <ulink url="http://lists.mplayerhq.hu/pipermail/mplayer-cvslog/">MPlayer-cvslog archive</ulink>. </para> + <para> Now proceed as for a normal update: <screen> @@ -69,6 +92,7 @@ Now proceed as for a normal update: make </screen> </para> + <para> If any non-programmer reads this, the fastest method to get at the point where the problem occurred is to use a binary search — that is, @@ -79,6 +103,7 @@ For example, if the problem occurred in 2003, start at mid-year, then ask If yes, go back to the first of April; if not, go to the first of October, and so on. </para> + <para> If you have lot of free hard disk space (a full compile currently takes 100 MB, and around 300-350 MB if debugging symbols are enabled), copy the @@ -89,6 +114,7 @@ earlier version, so if you do not make a backup copy of your original source tree, you will have to recompile everything in it when you come back to the present.) </para> + <para> When you have found the day where the problem happened, continue the search using the mplayer-cvslog archive (sorted by date) and a more precise svn @@ -98,6 +124,7 @@ svn update -r {"2004-08-23 15:17:25"} </screen> This will allow you to easily find the exact patch that did it. </para> + <para> If you find the patch that is the cause of the problem, you have almost won; report about it to the @@ -110,80 +137,102 @@ You may also look hard at the patch until it is coerced to reveal where the bug is :-). </para> </sect1> + + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_report"> <title>How to report bugs</title> + <para> -First of all please try the latest Subversion version of <application>MPlayer</application> +First of all please try the latest Subversion version of +<application>MPlayer</application> as your bug might already be fixed there. Development moves extremely fast, -most problems in official releases are reported within days or even hours, so -please use <emphasis role="bold">only Subversion</emphasis> to report bugs. This -includes binary packages of <application>MPlayer</application>. Subversion -instructions can be found at the bottom of +most problems in official releases are reported within days or even hours, +so please use <emphasis role="bold">only Subversion</emphasis> to report bugs. +This includes binary packages of <application>MPlayer</application>. +Subversion instructions can be found at the bottom of <ulink url="http://www.mplayerhq.hu/dload.html">this page</ulink> or in the README. If this did not help please refer to the list of -<link linkend="bugs">known bugs</link> and the rest of the documentation. If your -problem is not known or not solvable by our instructions, then please report the bug. +<link linkend="bugs">known bugs</link> and the rest of the documentation. +If your problem is not known or not solvable by our instructions, +then please report the bug. </para> <para> Please do not send bug reports privately to individual developers. This is -community work and thus there might be several people interested in it. Sometimes -other users already experienced your troubles and know how to circumvent a problem -even if it is a bug in <application>MPlayer</application> code. +community work and thus there might be several people interested in it. +Sometimes other users already experienced your troubles and know how to +circumvent a problem even if it is a bug in <application>MPlayer</application> +code. </para> <para> -Please describe your problem in as much detail as possible. Do a little detective -work to narrow down the circumstances under which the problem occurs. Does the bug -only show up in certain situations? Is it specific to certain files or file types? -Does it occur with only one codec or is it codec independent? Can you reproduce it -with all output drivers? The more information you provide the better are our -chances at fixing your problem. Please do not forget to also include the valuable -information requested below, we will be unable to properly diagnose your problem -otherwise. +Please describe your problem in as much detail as possible. Do a little +detective work to narrow down the circumstances under which the problem occurs. +Does the bug only show up in certain situations? Is it specific to certain +files or file types? Does it occur with only one codec or is it codec +independent? Can you reproduce it with all output drivers? The more information +you provide the better are our chances at fixing your problem. Please do not +forget to also include the valuable information requested below, we will be +unable to properly diagnose your problem otherwise. </para> <para> An excellent and well written guide to asking questions in public forums is -<ulink url="http://www.catb.org/~esr/faqs/smart-questions.html">How To Ask -Questions The Smart Way</ulink> by <ulink url="http://www.catb.org/~esr/">Eric S. Raymond</ulink>. +<ulink url="http://www.catb.org/~esr/faqs/smart-questions.html">How To Ask Questions The Smart Way</ulink> +by <ulink url="http://www.catb.org/~esr/">Eric S. Raymond</ulink>. There is another called -<ulink url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report -Bugs Effectively</ulink> by <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/">Simon Tatham</ulink>. +<ulink url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report Bugs Effectively</ulink> +by <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/">Simon Tatham</ulink>. If you follow these guidelines you should be able to get help. But please understand that we all follow the mailing lists voluntarily in our free time. We are very busy and cannot guarantee that you will get a solution for your problem or even an answer. </para> - </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_where"> <title>Where to report bugs</title> + <para> Subscribe to the MPlayer-users mailing list: <ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-users"/> and send your bug report to <ulink url="mailto:mplayer-users@mplayerhq.hu"/> where you can discuss it. </para> + <para> If you prefer, you can use our brand-new <ulink url="http://bugzilla.mplayerhq.hu/">Bugzilla</ulink> instead. </para> + <para> -The language of this list is <emphasis role="bold">English</emphasis>. Please follow the standard -<ulink url="http://www.ietf.org/rfc/rfc1855.txt">Netiquette Guidelines</ulink> and -<emphasis role="bold">do not send HTML mail</emphasis> to any of our mailing lists. You will only get ignored or +The language of this list is <emphasis role="bold">English</emphasis>. +Please follow the standard +<ulink url="http://www.ietf.org/rfc/rfc1855.txt">Netiquette Guidelines</ulink> +and <emphasis role="bold">do not send HTML mail</emphasis> to any of our +mailing lists. You will only get ignored or banned. If you do not know what HTML mail is or why it is evil, read this -<ulink url="http://expita.com/nomime.html">fine document</ulink>. It explains all -the details and has instructions for turning HTML off. Also note that we will not -individually CC (carbon-copy) people so it is a good idea to subscribe to actually -receive your answer. +<ulink url="http://expita.com/nomime.html">fine document</ulink>. +It explains all the details and has instructions for turning HTML off. Also +note that we will not individually CC (carbon-copy) people so it is a good idea +to subscribe to actually receive your answer. </para> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_what"> <title>What to report</title> + <para> You may need to include log, configuration or sample files in your bug report. If some of them are quite big then it is better to upload them to our @@ -193,54 +242,56 @@ name in your bug report. Our mailing lists have a message size limit of 80k, if you have something bigger you have to compress or upload it. </para> +<!-- ********** --> + <sect2 id="bugreports_system"> <title>System Information</title> + <para> <itemizedlist> <listitem><para> -Your Linux distribution or operating system and version e.g.: + Your Linux distribution or operating system and version e.g.: <itemizedlist> <listitem><para>Red Hat 7.1</para></listitem> <listitem><para>Slackware 7.0 + devel packs from 7.1 ...</para></listitem> </itemizedlist> </para></listitem> <listitem><para> -kernel version: -<screen>uname -a</screen> + kernel version: + <screen>uname -a</screen> </para></listitem> <listitem><para> -libc version: -<screen>ls -l /lib/libc[.-]*</screen> + libc version: + <screen>ls -l /lib/libc[.-]*</screen> </para></listitem> <listitem><para> -gcc and ld versions: -<screen> + gcc and ld versions: + <screen> gcc -v -ld -v -</screen> +ld -v<!-- + --></screen> </para></listitem> <listitem><para> -binutils version: -<screen> -as --version -</screen> + binutils version: + <screen>as --version</screen> </para></listitem> <listitem><para> -If you have problems with fullscreen mode: + If you have problems with fullscreen mode: <itemizedlist> <listitem><para>Window manager type and version</para></listitem> </itemizedlist> </para></listitem> <listitem><para> -If you have problems with XVIDIX: + If you have problems with XVIDIX: <itemizedlist> - <listitem><para>X colour depth: -<screen>xdpyinfo | grep "depth of root"</screen> - </para></listitem> + <listitem><para> + X colour depth: + <screen>xdpyinfo | grep "depth of root"</screen> + </para></listitem> </itemizedlist> </para></listitem> <listitem><para> -If only the GUI is buggy: + If only the GUI is buggy: <itemizedlist> <listitem><para>GTK version</para></listitem> <listitem><para>GLIB version</para></listitem> @@ -252,23 +303,26 @@ If only the GUI is buggy: </para> </sect2> +<!-- ********** --> + <sect2 id="bugreports_hardware"> <title>Hardware and drivers</title> + <para> <itemizedlist> <listitem><para> -CPU info (this works on Linux only): -<screen>cat /proc/cpuinfo</screen> + CPU info (this works on Linux only): + <screen>cat /proc/cpuinfo</screen> </para></listitem> <listitem><para> -Video card manufacturer and model, e.g.: + Video card manufacturer and model, e.g.: <itemizedlist> <listitem><para>ASUS V3800U chip: nVidia TNT2 Ultra pro 32MB SDRAM</para></listitem> <listitem><para>Matrox G400 DH 32MB SGRAM</para></listitem> </itemizedlist> </para></listitem> <listitem><para> -Video driver type & version, e.g.: + Video driver type & version, e.g.: <itemizedlist> <listitem><para>X built-in driver</para></listitem> <listitem><para>nVidia 0.9.623</para></listitem> @@ -277,7 +331,7 @@ Video driver type & version, e.g.: </itemizedlist> </para></listitem> <listitem><para> -Sound card type & driver, e.g.: + Sound card type & driver, e.g.: <itemizedlist> <listitem><para>Creative SBLive! Gold with OSS driver from oss.creative.com</para></listitem> <listitem><para>Creative SB16 with kernel OSS drivers</para></listitem> @@ -285,14 +339,17 @@ Sound card type & driver, e.g.: </itemizedlist> </para></listitem> <listitem><para> -If in doubt include <command>lspci -vv</command> output on Linux systems. + If in doubt include <command>lspci -vv</command> output on Linux systems. </para></listitem> </itemizedlist> </para> </sect2> +<!-- ********** --> + <sect2 id="bugreports_configure"> <title>Configure problems</title> + <para> If you get errors while running <command>./configure</command>, or autodetection of something fails, read <filename>configure.log</filename>. You may find the @@ -305,57 +362,74 @@ in your bug report. <sect2 id="bugreports_compilation"> <title>Compilation problems</title> + <para> Please include these files: <itemizedlist> -<listitem><para>config.h</para></listitem> -<listitem><para>config.mak</para></listitem> + <listitem><para>config.h</para></listitem> + <listitem><para>config.mak</para></listitem> </itemizedlist> </para> </sect2> +<!-- ********** --> + <sect2 id="bugreports_playback"> <title>Playback problems</title> + <para> -Please include the output of <application>MPlayer</application> at verbosity level -1, but remember to <emphasis role="bold">not truncate the output</emphasis> when +Please include the output of <application>MPlayer</application> at verbosity +level 1, but remember to +<emphasis role="bold">not truncate the output</emphasis> when you paste it into your mail. The developers need all of the messages to properly diagnose a problem. You can direct the output into a file like this: -<screen>mplayer -v <replaceable>options</replaceable> <replaceable>filename</replaceable> > mplayer.log 2>&1</screen> +<screen> +mplayer -v <replaceable>options</replaceable> <replaceable>filename</replaceable> > mplayer.log 2>&1 +</screen> </para> <para> -If your problem is specific to one or more files, then please upload the offender(s) to: +If your problem is specific to one or more files, +then please upload the offender(s) to: <ulink url="ftp://upload.mplayerhq.hu/MPlayer/incoming/"/> </para> <para> Also upload a small text file having the same base name as your file with a .txt -extension. Describe the problem you are having with the particular file there and -include your email address as well as the output of <application>MPlayer</application> -at verbosity level 1. Usually the first 1-5 MB of a file are enough to reproduce +extension. Describe the problem you are having with the particular file there +and include your email address as well as the output of +<application>MPlayer</application> at verbosity level 1. +Usually the first 1-5 MB of a file are enough to reproduce the problem, but to be sure we ask you to: -<screen>dd if=<replaceable>yourfile</replaceable> of=<replaceable>smallfile</replaceable> bs=1024k count=5</screen> -It will take the first five megabytes of '<emphasis role="bold">your-file</emphasis>' -and write it to '<emphasis role="bold">small-file</emphasis>'. Then try again on +<screen> +dd if=<replaceable>yourfile</replaceable> of=<replaceable>smallfile</replaceable> bs=1024k count=5 +</screen> +It will take the first five megabytes of +'<emphasis role="bold">your-file</emphasis>' and write it to +'<emphasis role="bold">small-file</emphasis>'. Then try again on this small file and if the bug still shows up your sample is sufficient for us. Please <emphasis role="bold">do not ever</emphasis> send such files via mail! Upload it, and send only the path/filename of the file on the FTP-server. If the -file is accessible on the net, then sending the <emphasis role="bold">exact</emphasis> -URL is sufficient. +file is accessible on the net, then sending the +<emphasis role="bold">exact</emphasis> URL is sufficient. </para> </sect2> +<!-- ********** --> + <sect2 id="bugreports_crash"> <title>Crashes</title> + <para> You have to run <application>MPlayer</application> inside <command>gdb</command> -and send us the complete output or if you have a <filename>core</filename> dump of -the crash you can extract useful information from the Core file. Here's how: +and send us the complete output or if you have a <filename>core</filename> dump +of the crash you can extract useful information from the Core file. Here's how: </para> + <sect3 id="bugreports_debug"> <title>How to conserve information about a reproducible crash</title> + <para> Recompile <application>MPlayer</application> with debugging code enabled: <screen> @@ -365,9 +439,11 @@ make and then run <application>MPlayer</application> within gdb using: <screen>gdb ./mplayer</screen> You are now within gdb. Type: -<screen>run -v <replaceable>options-to-mplayer</replaceable> <replaceable>filename</replaceable></screen> -and reproduce your crash. As soon as you did it, gdb will return you to the command -line prompt where you have to enter +<screen> +run -v <replaceable>options-to-mplayer</replaceable> <replaceable>filename</replaceable> +</screen> +and reproduce your crash. As soon as you did it, gdb will return you to the +command line prompt where you have to enter <screen> bt disass $pc-32 $pc+32 @@ -376,8 +452,10 @@ info all-registers </para> </sect3> + <sect3 id="bugreports_core"> <title>How to extract meaningful information from a core dump</title> + <para> Create the following command file: <screen> @@ -386,30 +464,38 @@ disass $pc-32 $pc+32 info all-registers </screen> Then simply execute this command: -<screen>gdb mplayer --core=core -batch --command=<replaceable>command_file</replaceable> > mplayer.bug</screen> +<screen> +gdb mplayer --core=core -batch --command=command_file > mplayer.bug +</screen> </para> </sect3> </sect2> </sect1> + +<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --> + + <sect1 id="bugreports_advusers"> <title>I know what I am doing...</title> + <para> -If you created a proper bug report following the steps above and you are confident -it is a bug in <application>MPlayer</application>, not a compiler problem or broken -file, you have already read the documentation and you could not find a solution, -your sound drivers are OK, then you might want to subscribe to the MPlayer-advusers -list and send your bug report there to get a better and faster answer. +If you created a proper bug report following the steps above and you are +confident it is a bug in <application>MPlayer</application>, not a compiler +problem or broken file, you have already read the documentation and you could +not find a solution, your sound drivers are OK, then you might want to +subscribe to the MPlayer-advusers list and send your bug report there to get +a better and faster answer. </para> <para> Please be advised that if you post newbie questions or questions answered in the -manual there, you will be ignored or flamed instead of getting an appropriate answer. -So do not flame us and subscribe to -advusers only if you really know what you are -doing and feel like being an advanced <application>MPlayer</application> user or -developer. If you meet these criteria it should not be difficult to find out how to subscribe... +manual there, you will be ignored or flamed instead of getting an appropriate +answer. So do not flame us and subscribe to -advusers only if you really know +what you are doing and feel like being an advanced +<application>MPlayer</application> user or developer. If you meet these +criteria it should not be difficult to find out how to subscribe... </para> - </sect1> </appendix> |