Dodatek B - Jak zgłaszać błędy

Dobre raporty o błędach są niezwykle cennym wkładem w rozwój każdego projektu. Ale dokładnie tak jak pisanie dobrego oprogramowania, dobre raporty o błędach wymagają wysiłku. Prosimy o zdanie sobie sprawy z faktu iż większość programistów jest ekstremalnie zajęta i otrzymuje obscenicznie dużo listów. Więc chociaż Twoje informacje zwrotne są niezwykle cenne dla udoskonalenia MPlayera, prosze zrozumieć że musisz dostarczyć wszystkie informacje o które prosimy, oraz dokładnie wykonać intrukcje opisane w tym dokumencie.

B.1 Jak naprawiać błędy

Jeśli uważasz że posiadasz niezbędne umiejętności, zapraszamy by spróbować naprawić błąd samemu. A jeśli już tak zrobiłeś, prosze przeczytać ten krótki dokument by dowiedzieć się jak sprawić by Twój kod został dołączony do MPlayera. Ludzie z listy dyskusyjnej mplayer-dev-eng pomogą Ci jeśli będziesz miał pytania.

B.2 Jak zgłaszać blędy?

Przede wszystkim prosze spróbować najnowszą wersję mplayera z CVS, gdyż Twój problem może być już naprawiony. Program rozwija się niezwykle szybko, większość problemów zgłaszonych po wypuszczeniu oficjalnej wersji naprawiana jest w przeciągu dni, a nawet godzin. Prosimy więc by użycwać wyłącznie wersji CVS przy zgłaszaniu problemów. Instrukcje dotyczące CVS można znaleźć na końcu tej strony bądź w dokumencie README. Jeśli ta wersja nie rozwiąże problemów, prosimy skonsultować się z lista znanych pluskiew i pozostałą częścią dokumentacji. Jeśli problem który napotkałeś nie jest znany bądź nie rozwiązują go nasze instrukcje, prosimy o wysłanie raportu o błędzie.

Prosimy nie wysyłać raportu o błędach bezpośrednio do programistów. MPlayer jest produktem rozwijanym przez grupę programistów, wiele osób może być zainteresowanych raportem. Czasami inni użytkownicy mogli już napotkać błąd z którym się borykasz, a nawet posiadać informacje jak go ominąć, nawet jeśli to błąd w kodzie MPlayera.

Prosimy o opisanie problemu dokładnie i z uwzględnieniem możliwie największej ilości szczegółów. Jeśli to możliwe, pobaw się w detektywa by zawęzić okoliczności przy których występuje problem. Czy pluska daje znać o sobie tylko w jakichś szczególnych okolicznościach? Czy dotyczy tylko niektórych plików bądź typów plików? Czy pojawia się przy jednym kodeku czy niezależnie od kodeka? Im więcej informacji dostarczysz tym większe szanse na to że naprawimy problem.

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.

An excellent and well written guide to asking questions in public forums is How To Ask Questions The Smart Way by Eric S. Raymond. There is another called How to Report Bugs Effectively by Simon Tatham. 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.

B.3 Where to report bugs

Subscribe to the mplayer-users mailing list:
    http://mplayerhq.hu/mailman/listinfo/mplayer-users
and send your bug report to:
    mplayer-users@mplayerhq.hu

The language of this list is English. Please follow the standard Netiquette Guidelines and do not send HTML mail 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 fine document. 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.

B.4 What to report

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 FTP server in a compressed format (gzip and bzip2 preferred) and include only the path and file 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.

B.4.1 System Information

B.4.2 Hardware and drivers

B.4.3 Compilation problems

Please include these files: Only if compilation fails below one of these directories, include these files:

B.4.4 Configure problems

Include configure.log.

B.4.5 Playback problems

Please include the output of MPlayer at verbosity level 1, but remember to not truncate the output 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:

    mplayer -v [options] [filename] > mplayer.log 2>&1

If your problem is specific to one or more files, then please upload the offender(s) to:

    ftp://mplayerhq.hu/MPlayer/incoming/

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 MPlayer 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:

    dd if=yourfile of=smallfile bs=1024k count=5

It will take the first five megabytes of 'your-file' and write it to 'small-file'. Then try again on this small file and if the bug still shows up your sample is sufficient for us. Please do not ever 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 exact URL is sufficient.

B.4.6 Crashes

You have to run MPlayer inside gdb and send us the complete output or if you have a core dump of the crash you can extract useful information from the Core file. Here's how:

B.4.6.1 How to conserve information about a reproducible crash

Recompile MPlayer with debugging code enabled:

    ./configure --enable-debug=3
    make

and then run MPlayer within gdb using:

    gdb ./mplayer

You are now within gdb. Type:

    run -v [options-to-mplayer] filename

and reproduce your crash. As soon as you did it, gdb will return you to the command line prompt where you have to enter

    bt
    disass $pc-32 $pc+32
    info all-registers

B.4.6.2 How to extract meaningful information from a core dump

Please create the following command file:

disass $pc-32 $pc+32
info all-registers

Then simply execute the following on your command line:

    gdb mplayer --core=core -batch --command=command_file > mplayer.bug

B.5 I know what I am doing...

If you created a proper bug report following the steps above and you are confident it is a bug in MPlayer, 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.

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 MPlayer user or developer. If you meet these criteria it should not be difficult to find out how to subscribe...