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

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

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

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

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

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

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

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

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

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

Официальный форум Arch Linux или русскоязычный форум: форумы — это место, куда пользователи идут в первую очередь, когда им нужна помощь или они хотят высказать свою идею. И даже если решение проблемы ещё не нашли, дополнительная информация и обсуждения могут подсказать вам, куда дальше копать.
Систему отслеживания ошибок Arch Linux: Возможно, кто-то уже столкнулся с такой же проблемой и она была доведена до сведения разработчиков. Дублирование одних и тех же ошибок бесполезно. Сначала проверьте и закрытые, и открытые баги, выбрав «All Statuses» в Advanced-поиске. Также стоит поставить там галочки «Search details» и/или «Search in comments», поскольку один лишь заголовок может не содержать текст, который вы ищете.
Яндекс, 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 Linux в трекере соответствующего проекта на gitlab.archlinux.org или GitHub вместо bugs.archlinux.org.
Упаковка: как правило, упаковка пакета заключается в том, чтобы достать у разработчиков исходный код и собрать его с нужными параметрами, следя за тем, чтобы пакет был правильно установлен в системе и работала основная функциональность программы. Создание пакета не подразумевает добавления функций или патчей к существующим багам; это задача разработчиков программы.

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

Баг или фича?

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

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

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

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

Когда это ошибка...
Когда это не входит в зону ответственности Arch, то есть функциональность апстрима.
Пакет не является актуальным. Используйте функцию Пометить Пакет как Устаревший на сайте пакетов 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 — для пакетов в core-testing, core, extra-testing или extra. Сюда же относятся ошибки документации и сайта (кроме AUR) и ошибки, связанные с безопасностью.
Release Engineering — для всех ошибок, связанных с ошибками релизов (ISO-образов, инсталляторов и т.д.)

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

Сводка

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

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

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

Совет: Flyspray попытается распарсить ссылки, содержащие @ (например, ссылки на архивы списков рассылки), как email-адреса, и таким образом испортит их. При добавлении таких ссылок убедитесь, что символы @ экранированы как %40.

Серьёзность

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

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

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

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

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

Хорошая инструкция по отправлению баг-репортов есть здесь: https://www.chiark.greenend.org.uk/~sgtatham/bugs-ru.html

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

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

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

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

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

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

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

Наблюдение за багом — это очень важно. Вы будете получать email, когда будут появляться новые комментарии и когда изменится статус бага, если вы поставили галочку Notify me whenever this task changes (Уведомить меня при изменениях).

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

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

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

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

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

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

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

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

Статусы ошибок

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

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

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

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

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

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

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

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

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