diff --git a/ru_RU.KOI8-R/articles/problem-reports/article.sgml b/ru_RU.KOI8-R/articles/problem-reports/article.sgml new file mode 100644 index 0000000000..1c2afd4dbf --- /dev/null +++ b/ru_RU.KOI8-R/articles/problem-reports/article.sgml @@ -0,0 +1,747 @@ + + + +%man; + +%mailing-lists; + +%trademarks; +]> + +
+ + Составление сообщений о проблеме во FreeBSD + + $FreeBSD$ + + + &tm-attrib.freebsd; + &tm-attrib.cvsup; + &tm-attrib.ibm; + &tm-attrib.intel; + &tm-attrib.sparc; + &tm-attrib.sun; + &tm-attrib.general; + + + + Эта статья описывает, как наилучшим образом сформулировать и + послать сообщение о проблеме в Проект FreeBSD. + + + + + Dag-Erling + Smørgrav + Текст предоставил + + + + + сообщения о проблемах + +
+ Введение + + Одной из самых разочаровывающим практик, которую можно получить в + качестве пользователя программного обеспечения, является посылка + сообщения о проблеме, которое вскоре закрывается с кратким и ничему не + помогающим объяснением типа это не ошибка или + неправильное PR. Подобным же образом одной из самых + разочаровывающим практик, которую можно получить в качестве разработчика + программного обеспечения, является получение массы сообщений о проблемах, + которые на самом деле не являются сообщениями о проблемах, а запросами на + получение поддержки, или которые содержат мало или вообще не содержат + никакой информации о сути проблемы или способе ее воспроизвести. + + В этом документе делается попытка описать то, как составлять хорошие + сообщения о проблемах. Что же, спросите вы, является хорошим сообщением + об ошибке? Ну, если перейти прямо к сути, то хорошим сообщением об + ошибке является то, которое может быть быстро проанализировано и + отработано, к обоюдному удовлетворению как пользователя, так и + разработчика. + + Хотя в основном статья фокусируется на сообщениях о проблемах во + FreeBSD, большей частью она должна хорошо подходить и другим программным + проектам. + + Заметьте, что эта статья организована по тематическому принципу, а + не хронологически, так что вы должны прочесть документ целиком прежде, + чем посылать сообщение об ошибке, и не воспринимать его как пошаговое + руководство. +
+ +
+ Когда нужно посылать сообщение об ошибке + + Имеется много классов ошибок, и не все они должны приводить к + появлению сообщения о проблеме. Конечно же, нет идеальных людей, и + будут моменты, когда вы решите, что нашли ошибку в программе, а на самом + деле вы неправильно поняли синтаксис команды или сделали опечатку в + конфигурационном файле (хотя само по себе это иногда говорит о плохой + документации или неправильной обработке ошибок в прикладной программе). + Есть еще много случаев, когда посылка сообщения об ошибке явно не + является правильным действием, а только приводит к разочарованию вас и + разработчиков. И наоборот, есть случаи, когда может быть нужно послать + сообщение о чем-то, не являющемся ошибкой—к примеру, запрос на + доработку или расширение функциональности. + + Но как же определить, что является ошибкой, а что нет? Простым + правилом, которому нужно следовать, является следующее - ваша проблема + не является ошибкой, если она формулируется как + вопрос (обычно в форме Как сделать X? или Где можно + найти Y?). Не всегда это так однозначно, но правило вопроса + покрывает большинство случаев. Если Вам нужен ответ, лучше всего задать + свой вопрос в &a.questions;. + + Вот некоторые случаи, в которых может оказаться полезным послать + сообщение о чем-то, что не является ошибкой: + + + + Запросы на расширение функций. Обычно хорошей идеей является + озвучивание этого в списках рассылки до того, как посылать сообщение + о проблеме. + + + + Уведомление об обновлении программного обеспечения, которое + поддерживается сторонними разработчиками (в основном порты, но также + и компоненты базовой системы, разрабатываемые сторонними + организациями, такие, как BIND или различные утилиты GNU). + + + + Кроме того, если система, на которой вы столкнулись с ошибкой, давно + не обновлялась, вы должны серьезно подумать об обновлении и попытаться + воспроизвести проблему на обновленной системе прежде, чем посылать + сообщение об ошибке. Есть лишь несколько вещей, которые выводят из + себя разработчика больше, чем получение сообщений об уже исправленных + ею ошибках. + + И наконец, ошибка, которую нельзя воспроизвести, вряд ли будет + исправлена. Если ошибка возникла только единожды, и вы не можете ее + воспроизвести, к тому же никто с ней больше не сталкивался, нет никаких + шансов, что разработчики смогут ее воспроизвести или понять, что делается + неправильно. Это не значит, что такого не случается, но это значит, что + шансов у вашего сообщения дойти когда либо до стадии исправления ошибки + очень малы, и вам лучше его не посылать. +
+ +
+ Подготовка + + Нужно следовать хорошему правилу всегда сначала выполнять + дополнительные исследования перед тем, как послать сообщение о проблеме. + Может быть, о вашей проблеме уже сообщено; может быть, она недавно + обсуждалась или обсуждается в списках рассылки; она может быть уже + исправлена в более новой версии, чем та, что вы используете. Поэтому вы + должны проверить все обычные места до того, как послать ваше сообщение о + проблеме. Для FreeBSD это значит: + + + + FreeBSD + FAQ + (Ответы на часто задаваемые вопросы). + FAQ содержит ответы на вопросы из самых разных категорий, + в частности, + аппаратной + совместимости, + пользовательских + программ + и конфигурации + ядра. + + + + Списки + рассылки—если Вы не подписаны на них, воспользуйтесь + поиском + в архивах на сайте FreeBSD. Если ваша проблема не + обсуждалась в списках рассылки, вы можете попытаться опубликовать + сообщение о ней и подождать несколько дней, пока кто-нибудь не сможет + увидеть то, что вы не заметили. + + + + Как вариант, весь веб—используйте вашу любимую поисковую + систему для нахождения каких-либо ссылок на вашу проблему. Вы можете + даже увидеть ссылки на архивы списков рассылки или телеконференций, о + которых вы не знали или не думали там искать. + + + + Следующим пунктом должна быть + + база данных PR FreeBSD (GNATS). Если только ваша проблема не + нова или редка, есть некоторый шанс, что о ней уже сообщено. + + + + Наконец, если вы обновляли версию системы (в особенности, если + вы обновляете ветку -current), вам следует + тщательно изучить содержимое файла + /usr/src/UPDATING или его текущую версию по адресу + . + Этот файл содержит немало жизненно важной информации. + + + + Теперь вам нужно добиться того, чтобы ваше сообщение о проблеме + попало в нужные руки. + + Здесь первым правилом будет то, что если проблема является ошибкой в + программном обеспечении сторонних разработчиков (порт или пакадж, которые + вы установили), то вы должны сообщить об ошибке автору программы, а не в + Проект FreeBSD. Есть два исключения из этого правила: во-первых, если + ошибка не проявляется на других платформах, то в этом случае проблема + может заключаться в том, как программное обеспечение было перенесено на + FreeBSD; во-вторых, если автор уже исправил ошибку и выпустил патч или + новую версию своей программы, а порт FreeBSD еще не был обновлен. + + Вторым правилом является то, что система отслеживания ошибок FreeBSD + сортирует сообщения о проблеме в соответствии с категорией, выбранной + тем, кто сообщает о проблеме. Таким образом, если вы выберите + неправильную категорию при посылке сообщения о проблеме, есть большая + вероятность, что оно будет незамеченно до тех пор, пока кто-нибудь не + сменит у него категорию. +
+ +
+ Написание сообщения о проблеме + + Теперь, после того, как вы решили, что ваш вопрос подпадает под + категорию сообщения о проблеме, и это проблема FreeBSD, самое время + написать собственно сообщение о проблеме (PR). Прежде чем мы углубимся + в частности использования программы для создания и отправки PR, вот + несколько советов, которые помогут вам сделать PR более эффективным. + + +
+ Как писать хорошие сообщения о проблемах + + + + Основным языком общения разработчиков FreeBSD является + английский. База данных по проблемам также ведется на английском. + Если вы испытываете проблемы с формулировкой описания проблемы + по-английски, свяжитесь со своими соотечественниками, которые + помогут вам составить PR. + + + + Не оставляйте поле Synopsis + (краткое описание) пустым. Сообщения о проблемах + попадают как в списки рассылки, которые затем расходятся по всему + миру (в них поле Synopsis определяет тему письма), + так и в базу данных. Просматривающий эту базу, как правило, + пройдет мимо PR с пустым кратким описанием. Не забудьте, что PR + остается в базе до тех пор, пока кто-либо не закроет его; + сообщение-аноним, скорее всего, просто потеряется на общем + фоне. + + + + Не оставляйте поле Synopsis + (краткое описание) пустым. Сообщения о проблемах + попадают как в списки рассылки, которые затем расходятся по всему + миру (в них поле Synopsis определяет тему письма), + так и в базу данных. Просматривающий эту базу, как правило, + пройдет мимо PR с пустым кратким описанием. Не забудьте, что PR + остается в базе до тех пор, пока кто-либо не закроет его; + сообщение-аноним, скорее всего, просто потеряется на общем + фоне. + + + + Избегайте туманных описаний в поле + Synopsis. Не стоит предполагать, что + читающий ваше сообщение владеет контекстом; поэтому, чем подробнее + вы опишете ситуацию, тем лучше. В частности, к какой части системы + относится ваша проблема? Проявляется ли она на этапе установки или + во время нормальной работы? Например, вместо строки + Synopsis: portupgrade is broken следовало бы + написать что-то вроде Synopsis: port sysutils/portupgrade + coredumps on -current. В случае портированных приложений + в поле Synopsis полезно указывать не только имя + порта, но и категорию. + + + + Если у вас есть готовый патч, скажите об + этом. PR, содержащий патч, имеет куда больше шансов + быть рассмотренным. В этом случае добавьте строку + [patch] в начало поля Synopsis + (хотя использование именно этой формы необязательно, она является + стандартом де-факто). + + + + Если вы ведете фрагмент кода, сообщите об + этом. Если вы—ответственная персона, можете + добавить в начало поля Synopsis строку + [maintainer update], а также установить класс + вашего сообщения (поле Class) в + maintainer-update. В этом случае коммиттеру, + обрабатывающему ваш PR, не придется лишний раз сверяться с файлом + Makefile. + + + + Будьте точны в формулировках. + Чем больше информации вы можете предоставить о проблеме, тем больше + у вас шансов получить ответ. Например, следует предоставить + информацию о версии системы, на которой вы работаете (для этого + предназначено специальное поле, см. ниже), о платформе, работаете ли + вы на версии с CD-ROM или обновлялись посредством &man.cvsup.1; + (если да, то укажите момент обновления). В случае проблем с ядром + укажите, что вы прочли файл src/UPDATING, иначе + кто-нибудь обязательно спросит, делали ли вы это. Нет + необходимости сразу предоставлять файл конфигурации ядра, список + установленных портов и/или образ памяти; однако, вы должны быть + готовы выслать или предоставить их по запросу. + + + + Избегайте нечетких запросов о новых + возможностях. Сообщение типа кто-то обязательно + должен сделать так, чтобы такая-то утилита вела себя так-то + имеет куда меньше шансов встретить позитивный отклик, чем более + четко сформулированный запрос. Помните, что исходные тексты + доступны всем, так что если вам нужна реализация какого-то нового + свойства, лучший способ— взяться за работу самому! Не + забудьте также, что такие моменты лучше обсуждать в списках + рассылки, таких как freebsd-questions, чем + делать это посредством базы данных PR. + + + + Убедитесь, что ваша проблема еще никем не описана. + Мы уже говорили об этом, но стоит повториться. + Потратьте пару минут на составление запросов к базе PR: + . + (Несмотря на повторы, об этом постоянно забывают) + + + + Избегайте полемики. + Если ваше сообщение касается области или способов реализации, + которые ранее вызвали разногласия, вам стоит быть готовым + предоставить не только патчи, но и внятные аргументы, почему + следует поступать именно так (то есть, это Правильный + Путь). Как отмечалось выше, аккуратный поиск по архиву + списков рассылки + + никогда не помешает. + + + + Будьте вежливы. + Почти каждый из тех, кто может заниматься вашим сообщением, + является добровольцем. Никому не понравятся указания, как и что + делать, когда он и так занимается этим, да еще и по каким-либо + причинам, отличным от денежных. Вообще говоря, этого подхода + следует придерживаться, имея дело с любым проектом с Открытыми + Исходными текстами (Open Source). + + +
+ +
+ Прежде всего + + Перед запуском утилиты &man.send-pr.1; проверьте, что переменная + вашего окружения VISUAL (или EDITOR, если + VISUAL не задана) задана подходящим образом. + + Следует также проверить, что от вас нормально ходит электронная + почта. Утилита &man.send-pr.1; генерит ваш PR в виде почтового + сообщения. Если с машины, на которой вы запускаете &man.send-pr.1;, + нельзя отправить почту, ваше сообщение не дойдет до базы данных GNATS. + Об установках электронной почты в FreeBSD можно прочитать в главе + Электронная почта в Руководстве по FreeBSD по адресу + . + +
+ +
+ Вложение патчей или файлов + + Программа &man.send-pr.1; предусматривает присоединение файлов к + сообщению о проблеме. Вы можете вложить сколько угодно файлов, но + каждый с уникальным именем (имеется в виду имя файла без маршрута). + Просто используйте параметр командной строки для + задания имен файлов, которые вы хотите присоединить: + + &prompt.user; send-pr -a /var/run/dmesg -a /tmp/errors + + Не беспокойтесь о бинарных файлах, они будут автоматически + перекодированы для того, чтобы не повредить работе вашей почтовой + программы. + + Если вы вкладываете патч, обязательно используйте параметр + или вместе с командой + &man.diff.1; для создания контекстного или унифицированного diff-файла + (унифицированный формат предпочтителен), + и обязательно укажите точные номера версий CVS файлов, которые вы + изменяли, чтобы разработчики, которые будут читать ваше сообщение, + смогли легко его применить. Предпочтительным является патч + относительно ветки CURRENT или HEAD CVS, поскольку весь новый код + должен быть сначала оттестирован в -CURRENT. После завершения + тестирования код будет интегрирован в ветвь STABLE. + + Если вы вставляете патч в тело сообщения, учтите, что некоторые + почтовые программы имеют тенденцию заменять табуляции серией пробелов, + что полностью разрушит, например, часть файла сборки (Makefile). + + Следует также заметить, что включение небольших патчей в сообщение о + проблеме является приемлемой практикой, в особенности если они решают + проблему, описанную в сообщении, большие же патчи, а в особенности + новый код, который может требовать значительного просмотра перед тем, + как он будет внесен в дерево исходных текстов, должны быть размещены на + web- или ftp-сервере, а в сообщение о проблеме должен быть включён + только URL указывающий на этот патч. Очень часто патчи, пересылаемые по + электронной почте, а в особенности если задействована GNATS, бывают + искажены, и, как следствие, чем больше патч, тем труднее будет для + заинтересованных людей привести его к нормальному виду. Также то, что + патч будет размещён отдельно от сообщения о проблеме, даёт возможность + изменять его не отсылая полный патч в дополнение к изначальному + сообщению об ошибке. + + Вы должны также помнить, что пока вы явно не укажете обратного в + вашем сообщении о проблеме или в самих патчах, будет предполагаться, + что они подпадают под те же условия лицензирования, что и оригинальный + файл, измененный вами. +
+ +
+ Заполнение шаблона + + После запуска утилиты &man.send-pr.1; вам будет представлен шаблон + сообщения о проблеме. + Шаблон состоит из списка полей, некоторые из которых уже заполнены, + а некоторые содержат комментарии, объясняющие назначение поля или + перечисляющие подходящие значения. Не беспокойтесь о комментариях; они + будут автоматически удалены, если вы их не изменяли, или удалите их + сами. + + Вверху шаблона, ниже строк SEND-PR: находятся + заголовки почтового сообщения. Вам обычно не нужно их изменять, если + только вы не посылаете сообщение о проблеме с машины или от учетной + записи, которая может посылать, но не может получать электронную почту, + в случае чего вы можете задать в полях From: и + Reply-To: ваши реальные адреса электронной почты. + Вы можете также послать самому себе (или кому-то еще) копию сообщения + о проблеме, добавив один или большее количество адресов к заголовку + Cc:. + + Далее следует последовательности однострочных полей: + + + + Submitter-Id: Не меняйте его. Значение + по умолчанию current-users правильно, даже если + вы используете FreeBSD-STABLE. + + + + Originator: Обычно оно заполнено полем + дополнительной информации учетной записи пользователя. Пожалуйста, + укажите ваше реальное имя, за которым опционально следует адрес + вашей электронной почты в угловых скобках. + + + + Organization: Все, что вы захотите здесь + указать. Это поле не используется ни для чего серьезного. + + + + Confidential: Предварительно заполнено как + no, его изменение не имеет значения, так как нет + такого понятия, как конфиденциальное сообщение о + проблеме—база данных PR распространяется по всему миру + посредством CVSup. + + + + Synopsis: Заполняется кратким и точным + описанием проблемы. Краткое описание используется в качестве темы + сообщения электронной почты о проблеме, и используется при выдаче + списков и выборках сообщений о проблемах; сообщения о проблемах с + непонятными краткими описаниями чаще всего игнорируются. + + Повторим: если к вашему сообщению о проблеме приложен патч, + то, пожалуйста, начните краткое описание с + [PATCH]; если вы являетесь ответственным за + данную часть кода или порт, можете начать описание с + [maintainer update] и/или установить класс + проблемы (поле Class) в + maintainer-update. + + + + Severity: Одно из + non-critical, + serious или critical. Не + переусердствуйте; избегайте пометки вашей проблемы как + critical, если только это не действительно + критичная проблема (к примеру, уязвимость пользователя root, легко + воспроизводимый останов системы). Разработчики чаще всего + игнорируют это и следующее поля, и именно потому, что посылающие + слишком часто переоценивают критичность своих проблем. + + + + Priority: Одно из + low, medium или + high. Смотрите выше. + + + + Category: Выберите одно из + следующего: + + + advocacy: проблемы, связанные с + общественным мнением о FreeBSD. Используется редко. + + + + alpha: проблемы, специфичные для + платформы Alpha. + + + + amd64: проблемы, специфичные для + платформы AMD64. + + + + bin: проблемы с пользовательскими + программами из базовой системы. + + + + conf: проблемы с настроечными файлами, + используемыми по умолчанию значениями и прочее. + + + + docs: проблемы со страницами справочной + системы или онлайновой документацией. + + + + gnu: проблемы с программным обеспечением + GNU, таки, как &man.gcc.1; или &man.grep.1;. + + + + i386: проблемы, специфичные для + платформы &i386;. + + + + ia64: проблемы, специфичные для + платформы ia64. + + + + java: проблемы, связанные с &java;. + + + + + kern: проблемы с ядром. + + + + misc: все, что не подпадает ни под какую + другую категорию (Надо отметить, что проблемы этой категории + имеют тенденцию теряться легче всего). + + + + ports: проблемы, связанные с деревом + портов. + + + + powerpc: проблемы, специфичные для + платформы &powerpc;. + + + + sparc64: проблемы, специфичные для + платформы &sparc64;. + + + + standards: проблемы, связанные с + соответствием стандартам. + + + + www: изменения или улучшения сайта + FreeBSD + + + + + + Class: Выберите одно из следующего: + + + + sw-bug: ошибки в программном + обеспечении. + + + + doc-bug: ошибки в документации. + + + + change-request: запросы на расширение + функций или изменение в существующих. + + + + update: обновления портов или другого + программного обеспечения сторонних разработчиков. + + + + maintainer-update: обновления в портах, + для которых вы являетесь ответственной персоной. + + + + + + Release: Используемая вами версия FreeBSD. + Оно заполняется автоматически программой &man.send-pr.1; и требует + изменения, если только вы отсылаете сообщение о проблеме с системы, + отличающейся от той, где вы столкнулись с проблемой. + + + + И наконец, последовательность многострочных полей: + + + + Environment: Оно должно максимально точно + описывать окружение, в котором встречается проблема. Сюда + включается версия операционной системы, версия конкретной программы + или файла, содержащего проблему, и любая другая информация, такая, + как конфигурация системы, другое программное обеспечение, которое + влияет на проблему, и так далее—просто все, что разработчик + должен знать для создания условий появления проблемы. + + + + Description: Полное и точное описание + проблемы, с которой вы столкнулись. Попытайтесь избежать своих + предположений о причинах проблемы, если только вы не + уверены, что правы, так как разработчик может сделать неправильные + предположения о проблеме. + + + + How-To-Repeat: Последовательность + действий, которые должны быть выполнены для повторения + проблемы. + + + + Fix: Предпочтителен патч, или по крайней + мере обходной путь (который не только поможет другим людям обойти + ту же самую проблему, но также поможет разработчику понять ее + причины), однако если у вас нет никаких здравых идей, то лучше + оставить это поле пустым, чем строит догадки. + + +
+ +
+ Отсылка сообщения о проблеме + + Как только вы заполните шаблон, сохраните его и выйдете из + редактора, &man.send-pr.1; запросит вас + s)end, e)dit or a)bort?. Вы можете нажать + s для продолжения и посылки сообщения о + проблеме, e для повторного запуска редактора и + выполнения дальнейших изменений, или a для + отказа от вашего сообщения. Если вы выберете последнее, то ваше + сообщение о проблеме останется на диске (&man.send-pr.1; укажет вам + имя файла перед завершением работы), так что вы сможете отредактировать + его на свой вкус или передать в систему с лучшим подключением к сети, + перед тем, как послать его при помощи параметра + программы &man.send-pr.1;: + + &prompt.user; send-pr -f ~/my-problem-report + + При этом будет прочитан указанный файл, будет проверено содержимое, + убраны комментарии и сообщение будет отослано. +
+
+ +
+ Отслеживание + + После того, как ваше сообщение будет принято, вы получите по + электронной почте уведомление, в котором будет указан номер для + отслеживания, который был назначен вашему сообщению о проблеме и URL, + который вы можете использовать для проверки его состояния. В случае + удачи кто-нибудь проявит интерес к вашей проблеме и попытается ее + решить, или, как это бывает, описать, почему это не является проблемой. + Вы будет автоматически оповещаться о любом изменении состояния и получать + копии всех комментариев или патчей, которые будут присоединяться в + процессе отработки вашего сообщения о проблеме. + + Если кто-то запросит дополнительную информацию от вас, или вы + вспомните или обнаружите нечто, что не указали в начальном сообщении, + просто пошлите письмо на адрес bug-followup@FreeBSD.org, + включив отслеживаемый номер в теме, чтобы система отслеживания сообщений + могла знать, к какому сообщению о проблеме его присоединить. + + Если сообщение о проблеме остается открытым после того, как проблема + была решена, просто пошлите сообщение вдогонку (так, как это описано + выше), в котором укажите, что сообщение о проблеме может быть закрыто, и + если это возможно, объясните, как и когда проблема была устранена. +
+ +
+ Дополнительная литература + + Это список информационных ресурсов, относящихся к правильному + написанию и обработке сообщений о проблемах. Он, без сомнения, не + полон. + + + + + How to Report Bugs Effectively—прекрасное эссе, которое + написал Simon G. Tatham о составлении полезных (не специфичных для + FreeBSD) сообщений о проблемах. + + + Problem + Report Handling Guidelines—интересный взгляд на + обработку сообщений об ошибках самими разработчиками FreeBSD. + + +
+