DOCS/xml/en/bugreports.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!-- $Revision$ -->
   3 <appendix id="bugreports">
   4 <title>How to report bugs</title>
   5
   6 <para>
   7 Good bug reports are a very valuable contribution to the development of any
   8 software project. But just like writing good software, good problem reports
   9 involve some work. Please realize that most developers are extremely busy and
  10 receive obscene amounts of email. So while your feedback is crucial in improving
  11 <application>MPlayer</application> and very much appreciated, please understand
  12 that you have to provide <emphasis role="bold">all</emphasis> of the information
  13 we request and follow the instructions in this document closely.
  14 </para>
  15
  16
  17 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  18
  19
  20 <sect1 id="bugreports_security">
  21 <title>Report security related bugs</title>
  22
  23 <para>
  24 In case you have found an exploitable bug and you would like to do the
  25 right thing and let us fix it before you disclose it, we would be happy
  26 to get your security advisory at
  27 <ulink url="mailto:&#115;&#101;&#99;&#117;&#114;&#105;&#116;&#121;&#64;&#109;&#112;&#108;&#97;&#121;&#101;&#114;&#104;&#113;&#46;&#104;&#117;">&#115;&#101;&#99;&#117;&#114;&#105;&#116;&#121;&#64;&#109;&#112;&#108;&#97;&#121;&#101;&#114;&#104;&#113;&#46;&#104;&#117;</ulink>.
  28 Please add [SECURITY] or [ADVISORY] in the subject.
  29 Be sure that your report contains complete and detailed analysis of the bug.
  30 Sending a fix is highly appreciated.
  31 Please don't delay your report to write proof-of-concept exploit, you can
  32 send that one with another mail.
  33 </para>
  34 </sect1>
  35
  36
  37 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  38
  39
  40 <sect1 id="bugreports_fix">
  41 <title>How to fix bugs</title>
  42
  43 <para>
  44 OUTDATED CONTENT REMOVED
  45 </para>
  46 </sect1>
  47
  48
  49 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  50
  51
  52 <sect1 id="bugreports_regression_test">
  53 <title>How to do regression testing using Subversion</title>
  54
  55 <para>
  56 OUTDATED CONTENT REMOVED
  57 </para>
  58 </sect1>
  59
  60
  61 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  62
  63
  64 <sect1 id="bugreports_report">
  65 <title>How to report bugs</title>
  66
  67 <para>
  68 OUTDATED CONTENT REMOVED
  69 </para>
  70 </sect1>
  71
  72
  73 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  74
  75
  76 <sect1 id="bugreports_where">
  77 <title>Where to report bugs</title>
  78
  79 <para>
  80 OUTDATED CONTENT REMOVED
  81 </para>
  82
  83 <para>
  84 The language of this list is <emphasis role="bold">English</emphasis>.
  85 Please follow the standard
  86 <ulink url="http://www.ietf.org/rfc/rfc1855.txt">Netiquette Guidelines</ulink>
  87 and <emphasis role="bold">do not send HTML mail</emphasis> to any of our
  88 mailing lists. You will only get ignored or
  89 banned. If you do not know what HTML mail is or why it is evil, read this
  90 <ulink url="http://efn.no/html-bad.html">fine document</ulink>.
  91 It explains all the details and has instructions for turning HTML off. Also
  92 note that we will not individually CC (carbon-copy) people so it is a good idea
  93 to subscribe to actually receive your answer.
  94 </para>
  95 </sect1>
  96
  97
  98 <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
  99
 100
 101 <sect1 id="bugreports_what">
 102 <title>What to report</title>
 103
 104 <para>
 105 OUTDATED CONTENT REMOVED
 106 </para>
 107
 108 <!-- ********** -->
 109
 110 <sect2 id="bugreports_system">
 111 <title>System Information</title>
 112
 113 <para>
 114 OUTDATED CONTENT REMOVED
 115 </para>
 116 </sect2>
 117
 118 <!-- ********** -->
 119
 120 <sect2 id="bugreports_hardware">
 121 <title>Hardware and drivers</title>
 122
 123 <para>
 124 OUTDATED CONTENT REMOVED
 125 </para>
 126 </sect2>
 127
 128 <!-- ********** -->
 129
 130 <sect2 id="bugreports_configure">
 131 <title>Configure problems</title>
 132
 133 <para>
 134 If you get errors while running <command>./configure</command>, or autodetection
 135 of something fails, read <filename>config.log</filename>. You may find the
 136 answer there, for example multiple versions of the same library mixed on your
 137 system, or you forgot to install the development package (those with the -dev
 138 suffix). If you think there is a bug, include <filename>config.log</filename>
 139 in your bug report.
 140 </para>
 141 </sect2>
 142
 143 <sect2 id="bugreports_compilation">
 144 <title>Compilation problems</title>
 145
 146 <para>
 147 Please include these files:
 148 <itemizedlist>
 149   <listitem><para>config.h</para></listitem>
 150   <listitem><para>config.mak</para></listitem>
 151 </itemizedlist>
 152 </para>
 153 </sect2>
 154
 155 <!-- ********** -->
 156
 157 <sect2 id="bugreports_playback">
 158 <title>Playback problems</title>
 159
 160 <para>
 161 Please include the output of <application>MPlayer</application> at verbosity
 162 level 1, but remember to
 163 <emphasis role="bold">not truncate the output</emphasis> when
 164 you paste it into your mail. The developers need all of the messages to properly
 165 diagnose a problem. You can direct the output into a file like this:
 166 <screen>
 167 mplayer -v <replaceable>options</replaceable> <replaceable>filename</replaceable> &gt; mplayer.log 2&gt;&amp;1
 168 </screen>
 169 </para>
 170
 171 <para>
 172 If your problem is specific to one or more files,
 173 then please upload the offender(s) to:
 174 <ulink url="ftp://upload.mplayerhq.hu/MPlayer/incoming/"/>
 175 </para>
 176
 177 <para>
 178 Also upload a small text file having the same base name as your file with a .txt
 179 extension. Describe the problem you are having with the particular file there
 180 and include your email address as well as the output of
 181 <application>MPlayer</application> at verbosity level 1.
 182 Usually the first 1-5 MB of a file are enough to reproduce
 183 the problem, but to be sure we ask you to:
 184 <screen>
 185 dd if=<replaceable>yourfile</replaceable> of=<replaceable>smallfile</replaceable> bs=1024k count=5
 186 </screen>
 187 It will take the first five megabytes of
 188 '<emphasis role="bold">your-file</emphasis>' and write it to
 189 '<emphasis role="bold">small-file</emphasis>'. Then try again on
 190 this small file and if the bug still shows up your sample is sufficient for us.
 191 Please <emphasis role="bold">do not ever</emphasis> send such files via mail!
 192 Upload it, and send only the path/filename of the file on the FTP-server. If the
 193 file is accessible on the net, then sending the
 194 <emphasis role="bold">exact</emphasis> URL is sufficient.
 195 </para>
 196 </sect2>
 197
 198 <!-- ********** -->
 199
 200 <sect2 id="bugreports_crash">
 201 <title>Crashes</title>
 202
 203 <para>
 204 You have to run <application>MPlayer</application> inside <command>gdb</command>
 205 and send us the complete output or if you have a <filename>core</filename> dump
 206 of the crash you can extract useful information from the Core file. Here's how:
 207 </para>
 208
 209
 210 <sect3 id="bugreports_debug">
 211 <title>How to conserve information about a reproducible crash</title>
 212
 213 <para>
 214 Recompile <application>MPlayer</application> with debugging code enabled:
 215 <screen>
 216 ./configure --enable-debug=3
 217 make
 218 </screen>
 219 and then run <application>MPlayer</application> within gdb using:
 220 <screen>gdb ./mplayer</screen>
 221 You are now within gdb. Type:
 222 <screen>
 223 run -v <replaceable>options-to-mplayer</replaceable> <replaceable>filename</replaceable>
 224 </screen>
 225 and reproduce your crash. As soon as you did it, gdb will return you to the
 226 command line prompt where you have to enter
 227 <screen>
 228 bt
 229 disass $pc-32 $pc+32
 230 info all-registers
 231 </screen>
 232 </para>
 233 </sect3>
 234
 235
 236 <sect3 id="bugreports_core">
 237 <title>How to extract meaningful information from a core dump</title>
 238
 239 <para>
 240 Create the following command file:
 241 <screen>
 242 bt
 243 disass $pc-32 $pc+32
 244 info all-registers
 245 </screen>
 246 Then simply execute this command:
 247 <screen>
 248 gdb mplayer --core=core -batch --command=command_file &gt; mplayer.bug
 249 </screen>
 250 </para>
 251 </sect3>
 252 </sect2>
 253 </sect1>
 254
 255 </appendix>