Руководство по описанию ошибок

Зачем это читать

Все просто: чем более эффективно составлен отчет об ошибке, тем более вероятно, что она будет исправлена разработчиком.

Данное руководство имеет общий характер и предназначено для пользователей, не имеющих большого опыта написания отчетов об ошибках. Не все положения документа могут быть применимы к конкретному проекту.

Как составить эффективный отчет

Отчет об шибке эффективен, если приводит к ее исправлению. Эффективный отчет отличается двумя свойствами:

  1. Воспроизводимость. Если инженер не убедится в наличии ошибки, она вероятнее всего будет отмечена как "WORKSFORME" (не подтверждается тестами) или "INVALID" (неверное сообщение). Здесь важна каждая деталь.

  2. Конкретность. Чем быстрее инженер локализует ошибку в определенной области, тем больше шансов на ее скорое исправление. (Если разработчик или тестер вынужден гадать, он проведет больше времени, проклиная пользователя, нежели собственно решая проблему.)

    [ Пример ]

Допустим, вы тестируете программу-обозреватель Internet. Она свалилась при обращении к foo.com, и вы пишете отчет об ошибке:

НЕПРАВИЛЬНО: "Программа рухнула. Кажется, на www.foo.com. Я играю в гольф с Биллом Гейтсом, поэтому если вы не исправите проблему, я при встрече ему пожалуюсь. Кстати, кнопка возврата выглядит как дохлая крыса. Б-р-р-р! И еще: страничку моей бабушки в вашей программе смотреть невозможно. Thx 4 UR help."

ПРАВИЛЬНО: "Фатальная ошибка каждый раз при обращении к www.foo.com, версия программы от 25.02.2002, система Windows 2000. Проблема воспроизводима также в Linux, с версией от 24.02.2002.

Ошибка происходит про отображении логотипа Foo наверху страницы. Методом деления страницы найдена проблемная ссылка: ошибка исчезает, если удалить атрибут "border=0":

<IMG SRC="http://www.foo.com/images/topics/topicfoos.gif" width="34" height="44" border="0" alt="News"> "

Как ввести эффективный отчет в Bugzilla:

Прежде, чем добавлять ошибку, используйте форму поиска Bugzilla на случай, если обнаруженный вами дефект уже известен. Регистрируя давно известную проблему в 37 раз, вы наверняка беспокоите программиста попусту. (Раздраженный программист исправляет меньше ошибок.)

Кроме того, воспроизведите ошибку на свежей версии программы. Разработчиков как правило интересуют ошибки в коде, над которым они активно работают в настоящее время. Кроме того, ошибка может быть уже исправлена в текущей версии.

Если вы обнаружили незарегистрированную ранее ошибку в текущей версии программы, пишите отчет в Bugzilla:

  1. На главной странице Bugzilla выберите "Регистрация новой ошибки".
  2. Выберите продукт, в котором обнаружена ошибка.
  3. Введите ваш адрес электронной почты, пароль и нажмите кнопку "Login". (Если у вас еще нет пароля, не заполняйте это поле и нажмите кнопку "E-mail me a password". Вы вскоре получите пароль по электронной почте.)

Теперь перейдем к заполнению формы:

Где обнаружена ошибка?

Product: В каком программном продукте обнаружена ошибка?
Поскольку значение уже выбрано на предыдущей странице, поле закрыто для редактирования.

Version: In which product version did you find the bug?
(If applicable)

Component: В каком компоненте продукта проявляется ошибка?
Требуется указать наименование компонента. (Если вы затрудняетесь с выбором, нажмите ссылку "Component". Появится краткое описание компонентов продукта.)

OS: В какой операционной системе проявляется ошибка? (Например: Linux, Windows 2000, Mac OS 9.)
Если известно, что ошибка происходит в любой системе, выберите 'All'. В противном случае выберите операционную систему, либо "Other" -- если вашей системы нет в списке.

Насколько серьезна ошибка?

Severity: Насколько опасны последствия ошибки?
Значение по умолчанию -- 'normal'. Если вы затрудняетесь с выбором, нажмите ссылку "Severity". Появится описание значений шкалы опасности ошибок.

Кто будет заниматься ошибкой?

Assigned To: Кто будет отвечать за исправление ошибки?
При регистрации ошибки Bugzilla автоматически назначает ответственного за компонент. Если необходимо указать другого инженера, введите его email. (Список ответственных можно увидеть на странице описания компонентов.)

Cc: Кто еще должен быть оповещен об изменениях состояния ошибки?
Перечислите адреса тех, кто должен получать по email отчеты об изменениях состояния ошибки. Адреса разделяются пробелами или запятыми. Количество адресов неограничено, но все должны быть зарегистрированы ранее в Bugzilla.

Что еще известно об ошибке?

Summary: How would you describe the bug, in approximately 60 or fewer characters?
A good summary should quickly and uniquely identify a bug report. Otherwise, an engineer cannot meaningfully identify your bug by its summary, and will often fail to pay attention to your bug report when skimming through a 10 page bug list.

A useful summary might be "PCMCIA install fails on Tosh Tecra 780DVD w/ 3c589C". "Software fails" or "install problem" would be examples of a bad summary.

[ Tell Me More ]

Description:
Please provide a detailed problem report in this field. Your bug's recipients will most likely expect the following information:

Overview Description: More detailed expansion of summary.

Drag-selecting any page crashes Mac builds in NSGetFactory

Steps to Reproduce: Minimized, easy-to-follow steps that will trigger the bug. Include any special setup steps.

1) View any web page. (I used the default sample page,
resource:/res/samples/test0.html)
                          
2) Drag-select the page. (Specifically, while holding down 
the mouse button, drag the mouse pointer downwards from any 
point in the browser's content region to the bottom of the 
browser's content region.)

Actual Results: What the application did after performing the above steps. 

The application crashed. Stack crawl appended below from MacsBug.

Expected Results: What the application should have done, were the bug not present.

The window should scroll downwards. Scrolled content should be selected. 
(Or, at least, the application should not crash.)

Build Date & Platform: Date and platform of the build that you first encountered the bug in.

Build 2002-03-15 on Mac OS 9.0

Additional Builds and Platforms: Whether or not the bug takes place on other platforms (or browsers, if applicable).

- Also Occurs On        
    Mozilla (2002-03-15 build on Windows NT 4.0) 
                                    
- Doesn't Occur On        
    Mozilla (2002-03-15 build on Red Hat Linux; feature not supported)        
    Internet Explorer 5.0 (shipping build on Windows NT 4.0)        
    Netscape Communicator 4.5 (shipping build on Mac OS 9.0)

Additional Information: Any other debugging information. For crashing bugs:

  • Win32: if you receive a Dr. Watson error, please note the type of the crash, and the module that the application crashed in. (e.g. access violation in apprunner.exe)
  • Mac OS: if you're running MacsBug, please provide the results of a how and an sc:
*** MACSBUG STACK CRAWL OF CRASH (Mac OS)
Calling chain using A6/R1 links 
    Back chain  ISA  Caller 
    00000000    PPC  0BA85E74   
    03AEFD80    PPC  0B742248   
    03AEFD30    PPC  0B50FDDC  NSGetFactory+027FC
PowerPC unmapped memory exception at 0B512BD0 NSGetFactory+055F0

You're done!

After double-checking your entries for any possible errors, press the "Commit" button, and your bug report will now be in the Bugzilla database.

More Information on Writing Good Bugs

1. General Tips for a Useful Bug Report

Use an explicit structure, so your bug reports are easy to skim. Bug report users often need immediate access to specific sections of your bug. If your Bugzilla installation supports the Bugzilla Helper, use it.

Avoid cuteness if it costs clarity. Nobody will be laughing at your funny bug title at 3:00 AM when they can't remember how to find your bug.

One bug per report. Completely different people typically fix, verify, and prioritize different bugs. If you mix a handful of bugs into a single report, the right people probably won't discover your bugs in a timely fashion, or at all. Certain bugs are also more important than others. It's impossible to prioritize a bug report when it contains four different issues, all of differing importance.

No bug is too trivial to report. Unless you're reading the source code, you can't see actual software bugs, like a dangling pointer -- you'll see their visible manifestations, such as the segfault when the application finally crashes. Severe software problems can manifest themselves in superficially trivial ways. File them anyway.

2. How and Why to Write Good Bug Summaries

You want to make a good first impression on the bug recipient. Just like a New York Times headline guides readers towards a relevant article from dozens of choices, will your bug summary suggest that your bug report is worth reading from dozens or hundreds of choices?

Conversely, a vague bug summary like install problem forces anyone reviewing installation bugs to waste time opening up your bug to determine whether it matters.

Your bug will often be searched by its summary. Just as you'd find web pages with Google by searching by keywords through intuition, so will other people locate your bugs. Descriptive bug summaries are naturally keyword-rich, and easier to find.

For example, you'll find a bug titled "Dragging icons from List View to gnome-terminal doesn't paste path" if you search on "List", "terminal", or "path". Those search keywords wouldn't have found a bug titled "Dragging icons doesn't paste".

Ask yourself, "Would someone understand my bug from just this summary?" If so, you've written a fine summary.

Don't write titles like these:

  1. "Can't install" - Why can't you install? What happens when you try to install?
  2. "Severe Performance Problems" - ...and they occur when you do what?
  3. "back button does not work" - Ever? At all?

Good bug titles:

  1. "1.0 upgrade installation fails if Mozilla M18 package present" - Explains problem and the context.
  2. "RPM 4 installer crashes if launched on Red Hat 6.2 (RPM 3) system" - Explains what happens, and the context.

(Written and maintained by Eli Goldberg. Claudius Gayle, Gervase Markham, Peter Mock, Chris Pratt, Tom Schutter and Chris Yeh also contributed significant changes. Constructive suggestions welcome.

Русский перевод -- Виталий Федрушков.)