Bug reporting guidelines (Русский)

Состояние перевода: На этой странице представлен перевод статьи Bug reporting guidelines. Дата последней синхронизации: 19 февраля 2022. Вы можете помочь синхронизировать перевод, если в английской версии произошли изменения.

Создание или закрытие отчётов об ошибках в системе отслеживания ошибок Arch Linux — это один из способов помочь сообществу. Однако плохо оформленный отчёт может и навредить: сообщество и разработчики будут впустую терять время, задавая вопросы и закрывая некорректные отчёты. Этот документ является руководством для тех кто хочет помочь сообществу созданием эффективных отчётов об ошибках и/или их отловом.

Смотрите также: Как эффективно сообщать об ошибках от Саймона Тэтхема.

До того как написать отчёт

Подготовка подробного и хорошо оформленного отчета об ошибке — несложная задача, но для его создания требуется приложить определённые усилия. Исследования, проделанные до того как написать отчёт, являются наиболее полезной частью работы. К сожалению, многие лишь отправляют отчёт об ошибке, не проводя никаких исследований.

Следующие шаги помогут вам в подготовке вашего отчёта об ошибке или запроса новой функциональности.

Избегайте дублирования

Если вы столкнулись с проблемой или хотите предложить новую функциональность, скорее всего у кого-то уже возникала эта проблема или идея. Тот человек уже мог создать такой запрос/отчёт. В таком случае не создавайте ещё один, а переходите в раздел #Сопровождение багов.

Тщательно просмотрите уже имеющуюся информацию, включая:

Официальный форум Arch Linux или русскоязычный форум: форумы — это место, куда пользователи идут в первую очередь, когда им нужна помощь или они хотят высказать свою идею. И даже если решение проблемы ещё не нашли, дополнительная информация и обсуждения могут подсказать вам, куда дальше копать.
Систему отслеживания ошибок Arch Linux: Возможно, кто-то уже столкнулся с такой же проблемой и она была доведена до сведения разработчиков. Дублирование одних и тех же ошибок бесполезно. Поэтому сначала проверьте недавно закрытые баги, а также незакрытые баги. Учтите, что метки в "деталях поиска" и/или в "поиске комментариев" может не содержать текста, который вы ищите.
Яндекс, Google или другой поисковик. Ищите по названию программы, её версии и ключевой части сообщения об ошибке.
Upstream: Апстримом обычно называют разработчиков и сообщество, которое непосредственно занимается разработкой программы. Если ошибка допущена разработчиком программы и Arch Linux в её появлении не виноват, то сообщать о ней следует именно в апстрим, а не в Arch. Поищите вашу проблему среди новых и недавно закрытых отчётов в баг-трекере апстрима: возможно, ошибку уже исправили в development-версии и исправление попадёт в следующий релиз программы.
Форумы других дистрибутивов: Сообщество свободного ПО очень велико, люди, не использующие Arch, могут тоже иметь хорошие идеи. Загляните на форум Gentoo, форум Fedora и Ubuntu форум и другие подобные ресурсы.

Где разработчик: апстрим или Arch

Arch Linux - один из множества дистрибутивов GNU/Linux. Arch разработчики и доверенные пользователи отвечают за компиляцию, упаковку и распространение софта, взятого из разных источников. Апстрим указывает на эти источники, то есть на непосредственных разработчиков той или иной программы, распространяющейся в Arch Linux'е. К примеру, браузер Firefox разработан в компании Mozilla, а разработчики Arch к нему не имеют отношения.

Проблему, не имеющую отношения к Arch Linux, невозможно решить, посылая багрепорт в Arch. Если ошибка возникает не из-за действий по портированию и интеграции в дистрибутив — скорее всего, ответственность за неё лежит на апстриме.

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

Как только вы это сделали или узнали другую важную информацию от разработчиков, может быть полезно разместить её на багтрекере Arch, так что о ней будут знать как Arch разработчики, так и пользователи Arch.

Итак, за что же отвечает Arch?

Собственные проекты Arch Linux: pacman, AUR, mkinitcpio, сайты Arch. Если вы не уверены, чей это проект, посмотрите в информации о пакете (pacman -Qi имя_пакета или через веб-сайт) и посмотрите URL проекта.
Упаковка: как правило, упаковка пакета заключается в том, чтобы достать у разработчиков исходный код и собрать его с нужными параметрами, следя за тем, чтобы пакет был правильно установлен в системе и работала основная функциональность программы. Создание пакета не подразумевает добавления функций или патчей к существующим багам; это задача разработчиков программы.

Если баг или желаемая функциональность не входит в компетенцию Arch — отправляйте сообщение в апстрим. Смотрите также раздел #В каких случаях не создавать отчёт об ошибке.

Баг или фича?

Баг: поведение программы не такое, как подразумевал разработчик.
Фича (Особенность): поведение программы такое, как и было задумано разработчиком.

В каких случаях не создавать отчёт об ошибке

Вы хотите, чтобы программа делала то, что не предусматривалось разработчиком. Иначе говоря, это запрос новой функциональности.
О баге уже известно разработчику.
Баг уже исправлен в апстриме, но в Arch Linux этот пакет ещё не обновили.
Пакет устарел. Воспользуйтесь функцией Пометить пакет как устаревший на сайте пакетов Arch.
Пакет, не использующий заплатки (патчи) Fedora, Ubuntu и других сообществ. Патчи должны быть представлены upstream'у.
Пакет, в котором несущественная функция X или функция Y не реализована. Это запрос функционала.
Пакет не включает файл .desktop, иконки или иные компоненты freedesktop. Если этих файлов нет в исходном tar архиве, это не баг. Сделайте запрос функционала в upstream. А вот если такие файлы апстрим предоставляет, но в пакете их нет, то это уже баг.

В каких случаях не создавать запрос функционала

Когда это ошибка...
Когда это не входит в зону ответственности Arch, например, свойство upstream.
Пакет не является актуальным. Используйте функцию Пометить Пакет как Устаревший на сайте пакетов Arch.
Пакет, который не использует патчи Fedora, Ubuntu или другие патчи сообщества. Патчи должны быть отправлены в upstream.

Сбор полезной информации

Список полезной информации, которая должна быть включена в отчёт об ошибке:

Версия пакета которую вы использовали. Всегда указывайте версию пакета. Не говорите "последняя", "сегодняшняя" или "пакет из extra", потому что это абсолютно бесполезно, особенно если понятно, что баг не будет исправлен в ближайшее время.
Версии основных библиотек (libraries), используемых пакетом (можно узнать из переменной depends (зависимости) в PKGBUILD) указываются в случаях, если они как-то вовлечены в проблему. Если не уверены, какую конкретно информацию нужно предоставить, дождитесь, когда охотник за багами вас о ней спросит.
Версия ядра, если проблема связана с оборудованием.
Укажите, работала ли программа раньше или нет. Если работала, скажите, когда она перестала работать.
Укажите производителя вашего аппаратного обеспечения, если вы столкнулись с аппаратными проблемами.
Добавьте необходимую информацию из логов, если она доступна. Она может быть получена из разных мест, в зависимости от проблемы:
- Журнал systemd. Если используете syslog-ng, /var/log/messages содержит логи, связанные с ядром или оборудованием.
- ~/.local/share/xorg/Xorg.0.log или /var/log/Xorg.0.log или /var/log/Xorg.2.log или какие-то другие Xorg log файлы в случае проблем, связанных с видео (nvidia, ati, xorg ...)
- Запустите вашу программу в терминале и используйте подробный режим (verbose) и/или режим отладки (debug), если возможно (узнайте в документации к программе). Скопируйте вывод в файл. Запуская приложение в терминале, убедитесь что необходимая информация отображалась на английском, чтобы как можно больше людей смогли понять её. Можно временно переключиться на английский язык, перед запуском программы выполнив export LC_ALL="C". Например, если программа называется foobar, у неё есть опция --verbose и вы хотите получить от неё релевантную информацию в процессе выполнения:

$ export LC_ALL="C"
$ foobar --verbose

Это затрагивает только текущий терминал. Когда вы закроете его, эти опции перестанут действовать.

Если вам нужно вставить большой кусок текста, например вывод dmesg или логи Xorg, желательно сохранить его в файле на вашем компьютере и прикрепить его к сообщению. Прикрепление файла предпочтительнее, чем заливка его в pastebin (в основном из-за того, что контент в pastebin может быть удалён из-за просрочки и других потенциальных проблем). Прикрепление файла гарантирует, что предоставленная информация всегда будет доступна.

Укажите, как можно воспроизвести эту ошибку. Это очень важно, так как поможет людям протестировать баг и потенциальные заплатки на их собственных компьютерах.
Трассировка стека. Это список вызовов, сделанных программой во время выполнения. Трассировка помогает найти ту часть программы, в которой находится баг, особенно если баг приводит к падению программы. Вы можете получить её с помощью gdb (The GNU Debugger). Подробности описаны в статье Отладка/Трассировка#Получение трассировки.

Создание отчета об ошибке

Когда вы определились с багом или фичей и собрали всю необходимую информацию, вы готовы к открытию нового бага или запросу функциональности.

Создание аккаунта

Зарегистрируйтесь в Системе отслеживания ошибок Arch. Это так же просто, как создание аккаунта на вики или на форуме, здесь нет ничего особенного.

Проекты

Когда вы убедились, что фича или баг относятся к Arch Linux, а не к другому апстриму, опубликуйте ваше сообщение в правильном проекте. Выберите название проекта в выпадающем списке слева от кнопки "Switch" в левом верхнем углу на странице создания отчёта об ошибке (не путайте его с пунктом "Category"). Существует пять проектов:

Arch Linux — для пакетов в testing, core, или extra. Сюда же относятся ошибки документации, сайта (кроме AUR), и ошибок безопасности.
AUR web interface — для веб-сайта и сервера AUR. Это не место для ошибок сторонних программ, взаимодействующих с AUR, или пакетов unsupported.
Community Packages — для пакетов из community. Это не место для пакетов из unsupported.
Pacman — для pacman и официальных скриптов, а также инструментов, связанных с ним. Сюда относятся такие вещи как makepkg и abs; но не для пакетов, разработанных сообществом, таких как инструменты AUR.
Release Engineering — для всех ошибок, связанных с ошибками релизов (ISO-образов, инсталляторов и т.д.)

Это не место для отчётов об ошибках в пакетах из unsupported. AUR предоставляет возможность комментирования пакетов из unsupported. Используйте её для информирования об ошибках меинтейнера (сопроводителя) соответствующего пакета.

Сводка

Пожалуйста, пишите краткую и описательную сводку (Summary).

Здесь представлен список рекомендаций:

Не называйте ваш отчёт "такая-то_программа не работает после последнего обновления" - это не информативно и, кроме того, в Arch Linux не бывает никаких "последних обновлений".
Начинайте сводку с названия пакета, заключённого в квадратные скобки, например "[баганутая_программа] 3.0.5-1 невозможно скопировать/вставить текст". Называя отчёты подобным образом вы облегчаете разработчикам поиск по названиям пакетов.
Не пишите слишком много букв в сводке. Излишний текст не будет виден в списке отчётов.

Серьёзность

Выбор critical в статусе серьёзности не поможет быстрее исправить ошибку. Это только приведет к тому, что действительно серьёзные проблемы станут менее заметны. Ещё возможно, что разработчик будет меньше хотеть исправлять эту ошибку.

Вот примерная шкала серьёзности ошибок:

Critical — Системный сбой, серьёзная ошибка загрузки, которая может касаться не только вас или подверженные эксплуатации ошибки безопасности в core или внешние сервис пакеты.
High — Основная работоспособность программы нарушена; менее серьёзные проблемы безопасности, и т.д.
Medium — Некритические возможности программы неисправны или не соблюдены стандарты UNIX.
Low — Дополнительная функциональность не работает(отдельный plugin или всё вместе с ним).
Very Low — Ошибка в переводе или документации. Что-то что не имеет большого значения, но необходимо отметить для исправления в будущем.

Добавление необходимой информации

Это наверное самая сложная часть в создании баг репорта. Вы должны выбрать из списка какую информацию надо приложить к отчёту об ошибке. Это зависит от того, какая у вас ошибка. Если не знаете, какую информацию нужно предоставлять, не стесняйтесь, лучше дать больше информации, чем нужно, чем дать недостаточно информации.

Хорошая инструкция по отправлению баг репортов вот здесь [1]

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

Краткая информация может быть включена в баг репорт, а объёмная информация (логи, скриншоты...) должна быть прикреплена.

Сопровождение багов

Не думайте, что вы отделались, написав баг-репорт!

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

Голосование и Наблюдение

Вы можете голосовать за избранные баги. Количество голосов показывает разработчикам, скольких людей затронул этот баг. Однако, это не самый эффективный способ борьбы с багами. Гораздо более важным является сообщение дополнительной информации, которая вам известна по данному багу, если вы не первоначальный информатор.

Наблюдение за багом — это очень важно. Вы будете получать email, когда будут появляться новые комментарии и когда изменится статус бага, в случае, если вы поставили галочку "Уведомить меня при изменениях".

Ответы на запрос дополнительных сведений

Через некоторое время люди увидят ваш баг-репорт и попытаются вам помочь. Вы должны продолжать содействовать в поиске исправления бага. Оставление их вопросов без ответа повлечёт за собой угасание энтузиазма для его исправления и баг останется открытым.

Пожалуйста, найдите время, чтобы предоставить запрошенную информацию и попробуйте следовать предложенным советам.

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

Обновление баг-репорта после выхода новой версии программы

Бывает так, что баг может проявляться только в определённой версии пакета, а в новой версии программы его уже нет. В этом случае сообщите об этом в комментариях к баг-репорту и попросите его закрыть.

Закрытие в случае нахождения решения

Иногда люди отправляют баг-репорт, а потом самостоятельно находят решение, но не уведомляют об этом баг-трекер, заставляя людей искать уже найденное решение. Пожалуйста, попросите закрыть баг, и приведите найденное решение в комментариях.

Дополнительная информация о статусах ошибок

В течение своей жизни ошибка проходит несколько статусов:

Unconfirmed — Это состояние по умолчанию. Вы только что сообщили о ней, никому пока не удалось воспроизвести проблему и подтвердить, что это действительно ошибка.

New — Баг подтверждён, но не закреплён за разработчиком, ответственным за соответствующую программу. Обычно это случаи, когда требуется дополнительное расследование, чья программа вызывает баг.

Assigned — Баг закреплён за разработчиком, ответственным за софт, вовлечённый в баг. Это не означает, что разработчик будет единственным, кто будет фиксить баг. Это даже не означает что он вообще будет работать над решением. Это просто означает, что разработчик займется отслеживанием жизни бага, обзором патчей, если они будут, выпуском фикса и закрытием бага когда потребуется. Это не повод контактировать непосредственно с девелопером, прося пофиксить баг побыстрее: ей/ему это не понравится...

Researching — Кто-то ищет решение. Такой статус редко бывает в Arch и это даже хорошо. Потому что статус researching заставляет думать людей, что им не нужно заботиться об этом баге. Но обычно требуется более одного человека, чтобы пофиксить его: несколько опытных людей на баг очень сильно помогают.

Waiting on Response и Requires testing — Того, кто создал репорт, попросили предоставить дополнительную информацию или попробовать предложенное решение, но она/он ещё не ответил. Такие статусы редко используются в Arch и должны быть использованы более часто. Однако, важно чтобы вы сопровождали баг (смотрите раздел #Сопровождение багов), так как девелоперы и охотники на багов часто спрашивают вопросы в комментариях.

A task closure has been requested — Это не совсем статус, но вы можете найти некоторые баги с такой пометкой. Она означает, что кто-то попросил закрыть баг. Обычно причина указана в запросе. Дальше дело за разработчиком, решит она/он закрыть баг или нет.

Closed — Либо это неправильно составленный баг (смотрите раздел #В каких случаях не создавать отчёт об ошибке), либо же решение было найдено и выпущено исправление.

Некоторые люди (разработчики, доверенные пользователи и т.д.) вправе изменять статус багов.