diff --git a/documentation/content/ru/articles/committers-guide/_index.adoc b/documentation/content/ru/articles/committers-guide/_index.adoc index 18dd58d8fe..527d827223 100644 --- a/documentation/content/ru/articles/committers-guide/_index.adoc +++ b/documentation/content/ru/articles/committers-guide/_index.adoc @@ -1,1149 +1,1165 @@ --- title: Справочник коммиттера authors: - author: The FreeBSD Documentation Project - author: Дмитрий Морозовский copyright: 1999-2007 The FreeBSD Documentation Project releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "cvsup", "ibm", "intel", "sparc", "general"] --- = Справочник коммиттера :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример +ifeval::["{backend}" == "html5"] include::shared/authors.adoc[] include::shared/ru/teams.adoc[] include::shared/ru/mailing-lists.adoc[] include::shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/ru/mailing-lists.adoc[] +include::../../../../shared/ru/teams.adoc[] +include::../../../../shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/ru/mailing-lists.adoc[] +include::../../../../shared/ru/teams.adoc[] +include::../../../../shared/ru/urls.adoc[] +endif::[] [.abstract-title] Аннотация Данный документ содержит информацию для сообщества коммиттеров FreeBSD. Все новые коммиттеры должны изучить его перед началом работы; прочим коммиттерам также рекомендуется время от времени просматривать его. ''' toc::[] [[admin]] == Административные детали [.informaltable] [cols="20%,80%", frame="none"] |=== |__Хост основного репозитория__ |`ncvs.FreeBSD.org` |__Способ авторизации__ |man:ssh[1], только протокол 2 |__Основной корень репозитория (CVSROOT)__ |`ncvs.FreeBSD.org`: [.filename]#/home/ncvs# (см. также <>). |__`{cvsadm}`__ |`{peter}` и `{markm}`, а также `{joe}` и `{marcus}` для иерархии [.filename]#ports/# |__Списки рассылки__ |{doc-developers-name}, {doc-committers-name}; {ports-developers-name}, {ports-committers-name}; {src-developers-name}, {src-committers-name}. (Каждому репозиторию проекта соответствуют отдельные списки рассылки с суффиксами -developers и -committers. Архивы этих списков хранятся в файлах [.filename]#/home/mail/repository-name-developers-archive# и [.filename]#/home/mail/repository-name-committers-archive# на машинах кластера `FreeBSD.org`). |__Отчеты Правления__ |[.filename]#/home/core/public/monthly-report# на машинах кластера `FreeBSD.org`. |__Наиболее значимые метки CVS__ |`RELENG_4` (ветвь 4.X-STABLE), `RELENG_5` (ветвь 5.X-STABLE), `RELENG_6` (ветвь 6.X-STABLE), `HEAD` (ветвь -CURRENT) |=== Для авторизации на машины проекта вы должны использовать протоколы man:ssh[1] или man:telnet[1] с включенным Kerberos 5. В случае man:ssh[1], допустим только протокол версии 2. Эти протоколы являются значительно более защищенными по сравнению с man:telnet[1] или man:rlogin[1], поскольку информация об авторизации передается в зашифрованном виде. По умолчанию, протокол man:ssh[1] также шифрует весь трафик. Учитывая наличие таких утилит, как man:ssh-agent[1] и man:scp[1], протокол man:ssh[1] значительно удобнее прочих в использовании. Если вы ничего не знаете об man:ssh[1], загляните в раздел <>. [[committer.types]] == Типы коммит битов CVS Репозиторий FreeBSD состоит из нескольких разделов, охватывающих исходные тексты базовой операционной системы, документацию, инфраструктуру построения внешних приложений (портов), а также различные служебные утилиты. Право записи в репозиторий ("коммит бит") подразумевает указание области дерева, в которое оно может быть применено. Как правило, области напрямую связаны с группой, подтвердившей право коммиттера на бит. В дальнейшем, область действия коммит бита может быть расширена; в этом случае, коммиттер должен следовать стандартным правилам нового для коммиттера в данной области, в частности, получая подтверждения на каждый коммит и, возможно, в течение какого-то времени работу с ментором. [.informaltable] [cols="1,1,1", frame="none"] |=== |__Тип коммит бита__ |__Ответственные__ |__Области репозитория__ |src |core@ |src/ и соответствующие части doc/ |doc |doceng@ |doc/, www/, документация дерева src/ |ports |portmgr@ |ports/ |=== Биты, выделенные до разделения дерева на области могут использоваться во всех частях дерева. Однако, с точки зрения здравого смысла, коммиттер, не имеющий опыта работы в какой-либо части дерева, должен предоставлять предлагаемые изменения для рассмотрения другими коммиттерами, получать подтверждения от ответственных за различные части репозитория, а также, возможно, работать совместно с ментором. Поскольку правила ведения различных областей кода различаются, указанные нормы скорее направлены на благо коммиттера, не имеющего достаточного опыта работы в данной области. Вне зависимости от области приложения усилий, запросы коммиттеров на рассмотрение предлагаемых изменений в процессе разработки могут только приветствоваться. === Правила для коммиттеров документации ([.filename]#doc/#) при работе с деревом исходных текстов ([.filename]#src/#) * Коммиттеры документации могут самостоятельно изменять документацию к исходным текстам, например, страницы справочника, файлы README, базы данных утилиты fortune, календарей, а также исправлять комментарии в исходных текстах без дополнительного согласования с коммиттерами исходных текстов, при условии сохранения здравого смысла и манеры коммитов. * Коммиттеры документации могут вносить незначительные изменения и исправления в исходные тексты (такие как исправления к процессу сборки, добавление малых дополнительных возможностей и т.п.) при наличии одобрения от коммиттера исходных текстов. * Коммиттер документации может расширить область действия своего бита на область исходных текстов (и стать, таким образом, коммиттером исходных текстов), найдя себе ментора, который предложит это расширение Правлению (Core). После одобрения, строка с его именем пользователя вносится в файл 'access', и применяются обычные правила периода работы с ментором, подразумевающие получение одобрения на каждый коммит. * Одобрение коммита ("Approved by") может производиться только "полновесным" (не работающим с ментором) коммиттером исходных текстов; последние могут рассматривать предлагаемые изменения и указываться в строке "Reviewed by". [[cvs.operations]] == Работа с CVS Подразумевается, что вы уже имеете опыт базовой работы с CVS. `{cvsadm}` являются "владельцами" репозитория CVS и ответственны за все прямые его изменения (в целях чистки или исправления каких-либо вопиющих ошибок коммиттеров при работе с CVS). Если в результате ваших действий с частью репозитория произошел несчастный случай, например, после неверной операции `cvs import` или `cvs tag`, пошлите письмо соответствующей подгруппе `{cvsadm}` (см. следующую таблицу) и сообщите о проблеме. В наиболее серьезных случаях, касающихся не только какой-либо части репозитория, а дерева CVS в целом, вы можете написать `{cvsadm}`. Пожалуйста, _не надо_ писать группе `{cvsadm}` по поводу репозиторного копирования и прочих вопросов, которые может решить соответствующая подгруппа. [[repomeisters]]Напрямую изменять содержимое репозитория может только группа CVS-мастеров; для обеспечения этого, только CVS-мастера имеют учетные записи на машинах, поддерживающих основной репозиторий. [NOTE] ==== Адреса, на которые следует посылать запросы, зависят от области репозитория, которую требуется поправить: * ncvs@ - репозиторий [.filename]#/home/ncvs#, основные исходные тексты * pcvs@ - репозиторий [.filename]#/home/pcvs#, порты * dcvs@ - репозиторий [.filename]#/home/dcvs#, документация * projcvs@ - репозиторий [.filename]#/home/projcvs#, прочие проекты ==== Дерево CVS в настоящее время разделено на четыре независимых репозитория: `doc`, `ports`, `projects` и `src`. Для удобства работы пользователей при распространении через CVSup различные деревья комбинируются в одно, с одним служебным каталогом `CVSROOT`. [NOTE] ==== Обратите внимание, что модуль `www`, содержащий исходные тексты http://www.FreeBSD.org[веб-сайта FreeBSD], расположен в репозитории `doc`. ==== В настоящее время, все репозитории CVS располагаются на одной машине, `ncvs.FreeBSD.org`, однако, для обеспечения возможности в будущем разнести их по физически различным машинам, для каждой поддерживается отдельное имя хоста. Их и следует использовать коммиттерам. Наконец, каждый репозиторий расположен в отдельном каталоге. В итоге, общая картина выглядит так: [[cvs-repositories-and-hosts]] .Репозитории CVS FreeBSD, хосты и каталоги [cols="1,1,1", frame="none", options="header"] |=== | Репозиторий | Хост | Каталог |doc |dcvs.FreeBSD.org |/home/dcvs |ports |pcvs.FreeBSD.org |/home/pcvs |projects |projcvs.FreeBSD.org |/home/projcvs |src |ncvs.FreeBSD.org |/home/ncvs |=== Операции с CVS производятся удаленно, путем установки переменной окружения `CVSROOT` (она должна указывать на соответствующий хост и каталог верхнего уровня, например `ncvs.FreeBSD.org``:`[.filename]#/home/ncvs#) и последующего выполнения команд выгрузки и коммита. Многие коммиттеры определяют команды-синонимы, разворачивающиеся в запуск CVS с правильными параметрами. В частности, пользователи оболочки man:tcsh[1] могут добавить следующие строки в свой скрипт начальной загрузки [.filename]#.cshrc#: [.programlisting] .... alias dcvs cvs -d user@dcvs.FreeBSD.org:/home/dcvs alias pcvs cvs -d user@pcvs.FreeBSD.org:/home/pcvs alias projcvs cvs -d user@projcvs.FreeBSD.org:/home/projcvs alias scvs cvs -d user@ncvs.FreeBSD.org:/home/ncvs .... Теперь все операции с CVS могут выполняться на локальной машине, а для внесения изменений в официальное дерево CVS следует использовать команду `__X__cvs commit`. Если вам нужно добавить в проект что-либо совершенно новое (например, исходные тексты сторонних разработчиков), нужно использовать команду `cvs import`; обратитесь к странице справочника по man:cvs[1] за подробностями. [NOTE] ==== Пожалуйста, _не используйте_ команды `cvs checkout` или `cvs update` для синхронизации ваших исходных текстов. Протокол CVS не оптимизирован для удаленной работы и требует значительных накладных расходов со стороны сервера. Пожалуйста, используйте метод синхронизации посредством `cvsup`, а основной хост используйте только для собственно коммитов. Наша распределенная сеть серверов cvsup достаточно развита. При необходимости синхронизации с самыми свежими изменениями вы можете пользоваться машиной `cvsup-master`, которая обладает достаточными ресурсами для удаленной работы с CVS; за нее отвечает `{kuriyama}`. ==== Если вам нужно использовать команды CVS `add` и `delete`, так чтобы в реальности переместить часть исходных текстов подобно действию команды man:mv[1], нужно запросить операцию "репозиторного копирования" (repository copy). При этом кто-либо из <> скопирует необходимые файлы внутри репозитория на нужное место и даст вам знать об этом. Репозиторное копирование производится для сохранения истории (журналов изменения). Возможность отследить историю изменений очень ценна для всего проекта FreeBSD. Документация по CVS, учебные материалы и FAQ можно найти по адресу: http://www.cvshome.org/docs/[http://www.cvshome.org/docs/]. Очень полезна также книга Карла Фогеля (Karl Fogel) http://cvsbook.red-bean.com/cvsbook.html[Open Source Development with CVS]. Некоторая полезная информация о CVS на русском языке может быть найдена http://alexm.here.ru/cvs-ru/[здесь]. `{des}` написал такой "мини-пример" работы с CVS: . Извлечение нужного модуля из репозитория: команда `co` или `checkout`. + [source,shell] .... % cvs checkout shazam .... + Эта команда извлечет копию модуля [.filename]#shazam#. Если модуль с таким именем не существует (не описан в файле modules), будет произведена попытка извлечь директорию верхнего уровня [.filename]#shazam#. + .Полезные опции команды `cvs checkout` [cols="1,1", frame="none"] |=== |`-P` |Не создавать (точнее, удалить после завершения выполнения) пустые каталоги |`-l` |Извлекать один уровень каталогов (без подкаталогов) |`-r__rev__` |Извлечь ревизию, ветвь или тег _rev_ для указанного модуля |`-D__date__` |Извлечь состояние модуля в репозитории на момент _date_ |=== + Примеры в применении к FreeBSD: ** Извлечь модуль [.filename]#miscfs#, расположенный в каталоге репозитория [.filename]#src/sys/miscfs#: + [source,shell] .... % cvs co miscfs .... + После выполнения вы получите каталог [.filename]#miscfs#, содержащий подкаталоги [.filename]#CVS#, [.filename]#deadfs#, [.filename]#devfs# и т.д. Один из них ([.filename]#linprocfs#) будет пустым. ** Извлечь те же файлы, но с полным путем: + [source,shell] .... % cvs co src/sys/miscfs .... + Теперь у вас есть каталог [.filename]#src#, содержащий подкаталоги [.filename]#CVS# и [.filename]#sys#. Каталог [.filename]#src/sys# содержит подкаталоги [.filename]#CVS# и [.filename]#miscfs# и т.д. ** Извлечь те же файлы, удалив при этом пустые подкаталоги: + [source,shell] .... % cvs co -P miscfs .... + Вы получите каталог [.filename]#miscfs# с подкаталогами [.filename]#CVS#, [.filename]#deadfs#, [.filename]#devfs#... однако без подкаталога [.filename]#linprocfs#, поскольку он не содержит файлов. ** Извлечь каталог [.filename]#miscfs# без подкаталогов: + [source,shell] .... % cvs co -l miscfs .... + Теперь в каталоге [.filename]#miscfs# будет только один подкаталог [.filename]#CVS#. ** Извлечь модуль [.filename]#miscfs# из ветви 6.X: + [source,shell] .... % cvs co -rRELENG_6 miscfs .... + Теперь вы можете изменить исходные тексты и произвести коммит в эту ветвь. ** Извлечь модуль [.filename]#miscfs# по состоянию на момент выхода 6.0-RELEASE: + [source,shell] .... % cvs co -rRELENG_6_0_0_RELEASE miscfs .... + В этом случае вы не сможете внести изменения в репозиторий, поскольку `RELENG_6_0_0_RELEASE` описывает момент времени, а не ветвь разработки. ** Извлечь модуль [.filename]#miscfs# по состоянию на 15 января 2000 г: + [source,shell] .... % cvs co -D'01/15/2000' miscfs .... + Как и в предыдущем случае, изменения не могут быть записаны. ** Извлечь модуль [.filename]#miscfs#, каким он был неделю назад: + [source,shell] .... % cvs co -D'last week' miscfs .... + И вновь, изменения не могут быть записаны. + Обратите внимание, что мета-данные хранятся в подкаталогах [.filename]#CVS#. + Аргументы опций `-D` and `-r` сохраняются (являются "клейкими", sticky), например, при последующем использовании команды `cvs update`. . Проверка состояния извлеченных файлов: команда `status`. + [source,shell] .... % cvs status shazam .... + Эта команда покажет статус файла [.filename]#shazam# или каждого файла в директории [.filename]#shazam#. Для каждого из файлов статус может быть одним из: + [.informaltable] [cols="1,1", frame="none"] |=== |Up-to-date |Файл соответствует репозиторию и не модифицировался |Needs Patch |Файл не изменялся, но репозиторий содержит обновленную версию |Locally Modified |Файл соответствует репозиторию, но был изменен локально |Needs Merge |Файл изменен локально; вместе с тем, файл изменен и в репозитории |File had conflicts on merge |После последнего обновления возникли конфликты, и они все еще не устранены |=== + Кроме того, будут показаны локальная версия и дата модификации, версия и дата последней из доступных (если вы применяли "клейкие" дату, тег или ветвь, последняя доступная версия может отличаться от вашей), а также клейкие теги, временные метки и опции. . Обновление извлеченного модуля: команда `update`. + [source,shell] .... % cvs update shazam .... + Эта команда обновит состояние файла [.filename]#shazam# или файлов в каталоге [.filename]#shazam# до наиболее свежих версий выбранной вами при извлечении ветви. Если выбирался "момент времени", не произойдет ничего, если только за истекшее время в репозитории не был перемещен тег или не произошло чего-нибудь еще непредвиденного. + Полезные опции в дополнение к уже описанным для команды `checkout`: + [.informaltable] [cols="1,1", frame="none"] |=== |`-D` |Извлечь вновь появившиеся или пропущенные ранее подкаталоги |`-a` |Обновиться до текущего состояния головной ветви |`-j__rev__` |магическая опция (см. ниже) |=== + Если вы извлекали модуль с опциями `-r` или `-D`, выполнение команды `cvs update` с другими параметрами `-r` или `-D` или с опцией `-a` приведет к выбору новой ветви, ревизии или даты. Использование опции `-a` удаляет использованные ранее клейкие свойства; опции `-r` и `-D`, наоборот, фиксируют их. + Теоретически использование `HEAD` в качестве аргумента опции `-r` должно дать тот же результат, что и указание опции `-a`, однако это верно лишь в теории. + Опция `-D` полезна, если: ** после извлечения вами модуля кем-либо еще в него были добавлены дополнительные каталоги; ** вы извлекали верхний уровень модуля при помощи опции `-l`, а в дальнейшем решили извлечь и подкаталоги; ** вы удалили какие-либо подкаталоги и теперь хотите вновь извлечь их. + __Обращайте внимание на вывод команды `cvs update`.__ Действие, произведенное с файлом, обозначается буквой перед его именем: + [.informaltable] [cols="1,1", frame="none"] |=== |`U` |Файл был успешно обновлен. |`P` |Файл был успешно обновлен (произведен успешный патч из удаленного репозитория). |`M` |Файл был изменен, и при этом обновлен успешно. |`C` |Файл был изменен, и при объединении изменений возникли конфликты. |=== + Объединение (merging) производится, если вы выгрузили рабочую копию какого-то модуля, изменили его, затем кто-либо еще произвел коммит собственных изменений, и, наконец, вы выполняете команду `cvs update`. CVS знает, что производились локальные изменения, и пытается объединить ваши изменения с теми, что произошли в репозитории (от состоянии версии, которую вы выгружали, до версии, до которой вы пытаетесь обновиться). Если изменения происходили с различными частями файла, объединение почти всегда произойдет успешно (хотя результат при этом может не быть синтаксически или семантически корректным). + CVS выводит букву `M` перед именем всех локально измененных файлов, даже если у них нет новых версий в репозитории, так что команда `cvs update` удобна для быстрого получения списка файлов, которые вы изменяли. + Если в результате вы видите букву `C`, ваши изменения конфликтуют с изменениями, внесенными в репозиторий (изменения были в одних и тех же или рядом расположенных строках, либо вы изменили файл настолько, что при сравнении `cvs` не смогла удержать контекст и приложить изменения из репозитория). Вам необходимо устранить конфликты, вручную редактируя файл. Конфликтующие фрагменты помечаются строками из знаков `<`, `=` и `>`. В начале каждого из конфликтов присутствует строка из семи знаков `<` и имени файла, затем идет фрагмент, содержащий внесенные вами изменения, разделитель из семи знаков `=`, соответствующий фрагмент из версии файла, содержащейся в репозитории, и, наконец, строка из семи знаков `>` совместно с номером версии, до которой вы обновляли файл. + Опция `-J` содержит некоторое количество черной магии. При ее наличии локальный файл обновляется до указанной версии так же, как и при использовании опции `-r`, но отслеживаемые номер версии или ветвь не изменяются. Эта опция умеет смысл лишь при парном использовании: при этом делается попытка применить изменения между двумя указанными версиями к локальной копии файла. + К примеру, вы внесли изменения и произвели коммит в файл [.filename]#shazam/shazam.c# в FreeBSD-CURRENT, а позднее хотите перенести обновления в FreeBSD-STABLE (Merge-From-Current, MFC). Версия, которая требует переноса - 1.15: ** Извлеките текущую версию модуля [.filename]#shazam# для ветви FreeBSD-STABLE: + [source,shell] .... % cvs co -rRELENG_6 shazam .... ** Приложите изменения между версиями 1.14 и 1.15: + [source,shell] .... % cvs update -j1.14 -j1.15 shazam/shazam.c .... + Почти наверняка вы получите конфликт в строках, содержащих идентификатор файла (`$Id: article.xml,v 1.19 2007-05-09 06:08:50 bvs Exp $` или, в случае FreeBSD, `$FreeBSD: head/ru_RU.KOI8-R/articles/committers-guide/article.xml 45050 2014-06-13 14:53:24Z taras $`). Вам потребуется отредактировать файл для устранения конфликта (в данном случае достаточно убрать строки-разделители и вторую строку `$Id: article.xml,v 1.19 2007-05-09 06:08:50 bvs Exp $`, оставив лишь строку с `$Id: article.xml,v 1.19 2007-05-09 06:08:50 bvs Exp $` для FreeBSD-STABLE). . Просмотр изменение между локальной версией и версией из репозитория: команда `diff`. + [source,shell] .... % cvs diff shazam .... + Эта команда покажет все отличия локального состояния файла (или файлов модуля) [.filename]#shazam# от состояния, сохраненного в репозитории. + .Полезные опции команды `cvs diff` [cols="1,1", frame="none"] |=== |`-u` |Использовать унифицированный (unified) формат. |`-c` |Использовать контекстный (context) формат. |`-N` |Показывать отсутствующие или созданные файлы. |=== + Всегда имеет смысл пользоваться опцией `-u`, поскольку унифицированный формат гораздо удобнее и лучше читаем, чем почти все другие (в некоторых случаях контекстный формат, генерируемый опцией `-c` может быть несколько лучше, но он гораздо более громоздок). Унифицированный формат различий состоит из серии фрагментов, каждый из которых начинается со строки, состоящей из двух символов `@` и номеров строк, описывающих положение изменившегося участка. Затем следует группа строк: те, что начинаются с пробела, описывают контекст, начинающиеся с символа `-` определяют удаленные строки, наконец, начинающиеся с символа `+` - добавленные. + Вы можете сравнивать текущее состояние с версией, отличающейся от той, с которой вы извлекали файл, указав опцию `-r` или `-D` подобно командам `checkout` и `update`, или даже получить список изменений между любыми двумя версиями (вне зависимости от того, что лежит в вашей локальной копии), указав _две_ версии при помощи опций `-r` или `-D`. . Просмотр журнала изменений: команда `log`. + [source,shell] .... % cvs log shazam .... + Если [.filename]#shazam# является обычным файлом, эта команда выдаст на экран _заголовок_ с информацией о файле, в частности, его местоположении в репозитории, какая версия соответствует текущему состоянию (`HEAD`), в каких ветвях разработки файл присутствует, а также перечислит теги, которыми он помечен. Затем, для каждой версии файла выводится соответствующее ей журнальное сообщение, включающее дату, время и автора коммита, количество добавленных и удаленных строк и собственно журнального сообщения, написанного коммиттером. + Если [.filename]#shazam# является каталогом, вышеописанная процедура выполняется для каждого файла в каталоге. Если при этом команде `log` не был указан флаг `-l`, процедура рекурсивно повторяется для всех подкаталогов. + Команда `log` используется для просмотра истории одного или нескольких файлов в том виде, как она сохранена в репозитории CVS. Используя опцию `-r__rev__`, вы можете посмотреть журнальное сообщение к одной определенной версии: + [source,shell] .... % cvs log -r1.2 shazam .... + Эта команда покажет журнальное сообщение для версии `1.2` файла [.filename]#shazam# (или для версий `1.2` каждого из файлов в каталоге [.filename]#shazam#). . Кто что делал: команда `annotate`. Эта команда показывает перед каждой строкой указанного файла (файлов) имя пользователя, вносившего последние изменения в эту строку. + [source,shell] .... % cvs annotate shazam .... . Добавление новых файлов: команда `add`. + Создайте файл, выполните для него команду `cvs add`, затем произведите запись в репозиторий (коммит): `cvs commit`. + Точно так же, новые каталоги добавляются в репозиторий путем создания и последующего выполнения команды `cvs add`. Заметьте, что выполнять коммит после добавления каталога не надо. . Удаление устаревших файлов: команда `remove`. + Удалите файл, затем выполните команду `cvs rm` с его именем в качестве параметра, наконец, выполните для него `cvs commit`. . Внесение изменений в репозиторий: команда `commit` или `checkin`. + .Useful `cvs commit` options [cols="1,1", frame="none"] |=== |`-F` |Форсировать внесение изменений для не модифицированного файла. |`-m__msg__` |Указать сообщение для журнала в командной строке (не запускать текстовый редактор). |=== + Опцию `-F` следует использовать, если вы поняли, что забыли указать какую-либо важную информацию в журнале изменений. + Хорошие журнальные сообщения очень важны. Они дают возможность другим узнать, зачем вы производили изменения, причем не только в момент их произведения, но и месяцы или годы спустя, когда кто-либо заинтересуется, почему выглядящий нелогично или неэффективно фрагмент кода попал в каши исходные тексты. Кроме того, это очень помогает в оценке того, нужно ли переносить соответствующий код в FreeBSD-STABLE (MFC). + Сообщения должны быть ясными, краткими, четкими, и представлять из себя разумную аннотацию, какие изменения были произведены и почему. + Сообщения должны достаточно ясно показывать сторонним разработчикам, насколько их касаются изменения и нужно ли им исследовать изменения подробно. + Избегайте внесения нескольких не связанных друг с другом изменений за один раз. Это затрудняет объединение изменений, а также, при обнаружении ошибок, усложняет поиск ответственного за ошибки участка. + Избегайте смешивания в одном коммите изменений функциональности со стилистическими правками или исправлениями в пробелах. Это усложняет объединение, и, кроме того, затрудняет понимание того, какие именно функциональные изменения были внесены. В случае коммита в файлы документации, это затруднит работу групп поддержки перевода, поскольку становится сложнее отделить изменения, требующие перевода. + Избегайте коммита большой группы файлов за один раз с одним общим и невнятным сообщением. Напротив, вносите изменения в отдельные файлы (или небольшие группы связанных файлов) с адекватными сообщениями для журналирования. + Перед коммитом, __обязательно__: ** проверьте, что вы будете выполнять коммит в правильную ветвь, посредством команды `cvs status`. ** проверьте ваши изменения при помощи команды `cvs diff` + Кроме того, ВСЕГДА указывайте, в какие именно файлы вы вносите изменения, так чтобы не включить в этот список лишних файлов. Команда `cvs commit` без аргументов включит все измененные файлы в текущем каталоге и всех подкаталогах. Еще несколько полезных советов: . Часто используемые опции можно занести в файл [.filename]#~/.cvsrc#, например: + [.programlisting] .... cvs -z3 diff -Nu update -Pd checkout -P .... + Для данного случая: ** всегда использовать компрессию уровня 3 для связи с удаленным сервером CVS. В случае медленного соединения это избавит вас от лишней головной боли. ** всегда использовать опции `-N` (показывать добавленные или удаленные файлы) и `-u` (унифицированный формат) для man:diff[1]. ** всегда использовать опции `-P` (удалять пустые каталоги) и `-D` (добавлять новые каталоги) при обновлении. ** всегда использовать опцию `-P` (удалять пустые каталоги) при извлечении файлов и модулей. . Пользуйтесь скриптом Эйвинда Эклунда (Eivind Eklund) `cdiff` для просмотра изменению унифицированного формата. Он является оберткой для man:less[1], добавляющей цветовые коды ANSI для выделения заголовком, добавленных и удаленных строк; прочие строки не модифицируются. Помимо этого, скрипт корректно разворачивает табуляции (которые часто выглядят неправильно в изменениях из-за дополнительного символа в начале строки). + package:textproc/cdiff[] + Просто используйте его вместо man:more[1] или man:less[1]: + [source,shell] .... % cvs diff -Nu shazam | cdiff .... + Помимо этого, некоторые текстовые редакторы, такие как man:vim[1] (package:editors/vim[]) поддерживают цветовую синтаксическую разметку многих типов файлов, в том числе файлов изменений и журналов CVS/RCS. + [source,shell] .... % echo "syn on" >> ~/.vimrc % cvs diff -Nu shazam | vim - % cvs log shazam | vim - .... . CVS - старая, загадочная и порой слабо предсказуемая в своем поведении программа. Ни один человек не способен удержать в голове все тонкости ее работы, так что не бойтесь спрашивать совета у Искусственного Интеллекта (а именно `{cvsadm}`). . Не оставляйте компьютер в процессе работы команды `cvs commit` (в редакторе при написании журнального сообщения) слишком надолго (более чем на 2-3 минуты). Эта команда блокирует каталог репозитория, в котором она запущена, и не позволяет другим разработчикам изменять его содержимое. Если вам нужно написать длинное журнальное сообщение, подготовьте его заранее и вставьте в редакторе во время выполнения команды `cvs commit`, либо запишите его в файл и используйте опцию CVS `-F`: + [source,shell] .... % vi logmsg % cvs ci -F logmsg shazam .... + Это самый быстрый способ передать журнальное сообщение CVS; однако, вы должны быть внимательны при редактировании файла [.filename]#logmsg#, поскольку при выполнении коммита у вас не будет шансов его поправить. . Вы можете существенно ускорить скорость работы CVS с центральным репозиторием, используя постоянное соединение с репозиторием. Для этого добавьте в файл [.filename]#~/.ssh/config# строки + [.programlisting] .... Host ncvs.FreeBSD.org ControlPath /home/user/.ssh/cvs.cpath Host dcvs.FreeBSD.org ControlPath /home/user/.ssh/cvs.cpath Host projcvs.FreeBSD.org ControlPath /home/user/.ssh/cvs.cpath Host pcvs.FreeBSD.org ControlPath /home/user/.ssh/cvs.cpath .... + Затем откройте постоянное соединение с машиной repoman: + [source,shell] .... % ssh -fNM ncvs.FreeBSD.org .... + Теперь команды CVS должны выполняться быстрее, поскольку используют существующее соединение с репозиторием. Учтите, что регистр в именах хостов имеет значение. [[conventions]] == Соглашения и традиции Став коммиттером, вы должны прежде всего произвести некоторые стандартные действия. * Добавьте себя в список "SGML сущностей" авторов в файл [.filename]#doc/en_US.ISO8859-1/shared/xml/authors.ent#; это изменение должно быть сделано прежде прочих, поскольку в противном случае следующий ваш коммит неизбежно разрушит процесс построения дерева doc/. + Это довольно простая задача, но при этом она является неплохим первым тестом ваших навыков работы с CVS. * Также добавьте свою "SGML сущность" в [.filename]#www/en/developers.xml#. * Добавьте себя в раздел "Разработчики" статьи link:{contributors}[Участники проекта FreeBSD] ([.filename]#doc/en_US.ISO8859-1/articles/contributors/contrib.committers.xml#) и удалите свою запись из раздела "Прочие участники" ([.filename]#doc/en_US.ISO8859-1/articles/contributors/contrib.additional.xml#). * Добавьте новость о новом коммиттере в файл [.filename]#www/shared/xml/news.xml#. Используйте существующие записи вида "Новый коммиттер" как шаблон. * Вам нужно добавить ваш PGP или GnuPG ключ в каталог [.filename]#doc/shared/pgpkeys# (а если у вас нет ключа, вам нужно его создать). Не забудьте изменить и произвести коммит в файл [.filename]#doc/shared/pgpkeys/pgpkeys.ent#. + `{des}` написал скрипт для упрощения этого процесса. Дополнительную информацию можно прочесть в файле http://cvsweb.FreeBSD.org/doc/shared/pgpkeys/README[README]. + [NOTE] ==== Очень важно, чтобы в Руководстве пользователя был записан актуальный PGP/GnuPG ключ, поскольку он может потребоваться для идентификации коммиттера (например, его будет проверять группа `{admins}` для аварийного восстановления учетной записи). Полный набор актуальных ключей пользователей домена `FreeBSD.org` можно найти по адресу link:https://www.FreeBSD.org/doc/pgpkeyring.txt[http://www.FreeBSD.org/doc/pgpkeyring.txt]. ==== * Добавьте себя в файл [.filename]#src/shared/misc/committers-репозиторий.dot#, где репозиторием будет являться либо doc, либо ports, либо src в зависимости от полученных вами коммиттерских привилегий. * Некоторые коммиттеры добавляют информацию о своем местоположении в файл [.filename]#ports/astro/xearth/files/freebsd.committers.markers#. * Некоторые добавляют данные о дне своего рождения в файл [.filename]#src/usr.bin/calendar/calendars/calendar.freebsd#. * Представьтесь другим коммиттерам, иначе никто не будет знать, кто вы и чем занимаетесь. От вас не требуется писать подробное резюме или биографию: будут достаточны один-два абзаца о себе и областях FreeBSD, в которых вы планируете работать. Пошлите это письмо в {src-developers-name} - и все! * Зайдите на машину `hub.FreeBSD.org` и создайте файл [.filename]#/var/forward/user# (замените _user_ на ваше имя пользователя). Этот файл должен содержать адрес электронной почты, на который будет переправляться вся почта на адрес _yourusername_@FreeBSD.org, в том числе сообщения о коммитах и другая почта на адреса {committers-name} и {src-developers-name}. Слишком большие почтовые ящики на машине `hub` могут быть "нечаянно" удалены или обрезаны без предупреждения, так что, чтобы не потерять почту, регулярно читайте ее либо перенаправьте куда-нибудь еще. + Из-за ощутимой загрузки, возникающей на серверах, обрабатывающих списки рассылки, из-за большого количества незапрошенной почты (спама), сервер, принимающий почту для домена FreeBSD.org, производит некоторые основные проверки и на основании их отвергает некоторые письма. На настоящий момент единственным проверяемым параметром является корректность информации DNS для хоста, доставляющего почту, но в будущем список может вырасти. Эти проверки временами обвиняют в том, что они отвергают правильную почту. Если вы хотите отключить проверки для своего адреса, создайте файл [.filename]#~/.spam_lover# в своей домашней директории на машине `freefall.FreeBSD.org`. * Если вы были подписаны на {cvs-all}, вам, скорее всего, следует отписаться от него, чтобы не получать дубликатов каждого сообщения о коммитах. Все новые коммиттеры первоначально работают под руководством ментора. Ваш ментор отвечает за обучение вас правилам и соглашениям, принятым в проекте, и помогает вам сделать первые шаги в среде коммиттеров. Он(а) также персонально отвечает за ваши действия в этот начальный период. До тех пор, пока ваш ментор не решит (и не анонсирует это посредством форсированного коммита файла [.filename]#access#), что вы достаточно освоились и готовы работать самостоятельно, перед любым коммитом вы должны получить одобрение (approval) ментора и указать это в журнальном сообщении коммита строкой `Approved by:`. Все коммиты в дерево [.filename]#src# сначала должны производиться в ветвь FreeBSD-CURRENT и лишь затем интегрироваться в FreeBSD-STABLE. Никакие серьезные изменения, новые возможности или рискованные модификации не должны производиться напрямую в ветви FreeBSD-STABLE. [[pref-license]] == Предпочтительная лицензия для новых файлов В настоящее время Проект FreeBSD считает предпочтительной формой лицензии на исходные тексты следующий текст: [.programlisting] .... /*- * Copyright (c) [year] [your name] * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * * [id for your version control system, if any] */ .... Проект FreeBSD крайне не рекомендует так называемый "третий пункт", или "пункт о рекламе" в лицензии на новый исходный код. В связи с большим количеством участников проекта FreeBSD, выполнение этого пункта большинством коммерческих производителей все более затруднительно. Если ваш код в дереве исходников содержит "пункт о рекламе", рассмотрите возможность его удаления. На самом деле, рассмотрите возможность перехода на приведенную лицензию. Проект FreeBSD не рекомендует использование полностью новых лицензий или вариаций стандартных лицензий. Новые лицензии перед использованием в репозитории проекта требуют утверждения группой mailto:core@FreeBSD.org[core@FreeBSD.org]. Большое число различных лицензий затрудняет использование кода, в основном из-за ненамеренных неверных выводов из плохо сформулированных формулировок лицензии. Политика проекта требует, чтобы код под НЕ-BSD лицензиями располaгался только в определённых местах репозитория, а в некоторых случаях компиляция должна быть условной по умолчанию или вообще отключена. К примеру, ядро GENERIC должно состоять только из лицензий идентичных или в значительной степени схожих с BSD лицензией. Программное обеспечение под лицензиями GPL, APSL, CDDL и др. не должно включаться в состав GENERIC. Разработчикам напоминается, что в open source правильное понимание "open" также важно, как правильное понимание "source", ибо некорректное использование интеллектуальной собственности имеет серьезные последствия. Какие-либо вопросы или беспокойства на этот счёт должны быть немедленно вынесены на обсуждение главной команде разработчиков (core team). [[developer.relations]] == Взаимодействие между разработчиками Если вы работаете над собственным исходным кодом, либо в области, в которой вы уже определены как ответственная персона, вам, скорее всего, не потребуется согласовывать коммит с кем-либо еще из разработчиков. Те же правила действуют, если вы нашли ошибку в той части системы, которой явно давно никто не занимается (к нашему стыду, существует несколько таких областей). Если же вы собираетесь модифицировать что-либо активно поддерживаемое (по-хорошему, узнать это можно только исследуя архивы списка рассылки `cvs-committers`), стоит послать предполагаемый патч ответственному за этот участок кода, как вы бы поступали, пока не были коммиттером. В случае портов нужно обращаться по адресу, указанному в строке `MAINTAINER` в файле [.filename]#Makefile#. Для других частей репозитория, в случае если вам не очевидно, кто ведет данный участок кода, может помочь исследование вывода команды `cvs log`. `{fenner}` написал отличный скрипт для определения разработчиков, наиболее активно производивших коммиты, выводящий для каждого из указанных файлов имя пользователя вместе с количеством произведенных им коммитов в данный файл. Скрипт можно найти на машине `freefall` в файле [.filename]#~fenner/bin/whodid#. Если найденная вами персона не отвечает на ваши вопросы или иным образом демонстрирует отсутствие интереса к проблеме, смело производите коммит самостоятельно. Если вы по каким-либо причинам не уверены в своих изменениях, предложите их для оценки в списке рассылки `-hackers` перед коммитом. Будет лучше, если вас обругают там и тогда, чем когда предлагаемое изменение уже будет частью репозитория. Если случилось так, что ваш коммит встретил сопротивление, возможно, стоит его откатить (back out) до тех пор, пока не будет достигнут консенсус. Помните - с помощью CVS всегда можно вернуться к предыдущему состоянию. Не принимайте в штыки мнения других разработчиков, с которыми вы не согласны. Если они предлагают иное решение проблемы чем вы, или даже иначе воспринимают проблему, это не значит, что они глупы, имеют сомнительное происхождение, хотят разрушить вашу работу, очернить ваше доброе имя, или развалить проект FreeBSD. Просто они смотрят на мир под иным углом. Различные взгляды - благо. Будьте честны в спорах. Оценивайте свою позицию по заслугам, честно относитесь к ее слабым сторонам и будьте готовы принять другие точки зрения и пути решения. Будьте открыты. Будьте терпимы, если вас поправляют. Все мы совершаем ошибки. Если вы ошиблись, извинитесь. Не обвиняйте ни себя, ни, тем более, других в ошибке. Не теряйте времени на смущение или упреки, просто исправьте ошибку и двигайтесь дальше. Спрашивайте и просите о помощи. Предлагайте ваши изменения для рассмотрения коллегам и рассматривайте их изменения. Одним из преимуществ программного обеспечения с открытыми исходными текстами является открытость разработки. Если никто не будет исследовать чужой код, это преимущество исчезнет. [[gnats]] == GNATS Для отслеживания ошибок и запросов на изменения проект FreeBSD использует GNATS. Если вы исправили ошибку или внесли изменения, описанные в одном из сообщений об ошибках (PR), не забудьте закрыть это сообщение, используя команду `edit-pr _pr-number_` на машине `freefall`. Хорошо будет, если вы потратите немного времени на поиск и закрытие других PR по этой теме. Вы и сами можете пользоваться man:send-pr[1] для предложения изменений, которые, по вашему мнению, могут потребовать более подробного обсуждения с коллегами. Более подробно о GNATS можно прочитать по адресам: * http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html[http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html] * link:https://www.FreeBSD.org/support/[http://www.FreeBSD.org/support/] * man:send-pr[1] Вы можете пользоваться локальной копией GNATS, поддерживая ее синхронность при помощи CVSup. При этом вы можете использовать команды GNATS локально, а также пользоваться другими интерфейсами, такими как `tkgnats`, что позволит вам работать с базой сообщений об ошибках без соединения с Интернет. [.procedure] .Procedure: Использование локальной копии GNATS . Если вы еще не поддерживаете зеркало дерева GNATS, добавьте в ваш [.filename]#supfile# строку + [.programlisting] .... gnats release=current prefix=/usr .... + Учтите, что эта строка должна предшествовать любым строкам, содержащим параметр "tag=", поскольку дерево GNATS не находится под управлением CVS и не имеет символьных меток. + После запуска cvsup в каталоге [.filename]#/usr/gnats# будет создана копия дерева GNATS FreeBSD. Вы можете использовать файл _refuse_ для копирования отдельных категорий. Например, если вас интересуют только сообщения категории `docs`, добавьте в файл [.filename]#/usr/local/etc/cvsup/sup/refuse# footnote:[Точный путь к файлу зависит от установок *default base в вашем файле supfile.] строку + [.programlisting] .... gnats/[a-ce-z]* .... + Прочие примеры в этом разделе подразумевают, что вы синхронизируете только категорию `docs`. . Установите порт GNATS из [.filename]#ports/databases/gnats#. После установки вы обнаружите различные служебные каталоги в дереве [.filename]#$PREFIX/shared/gnats#. . Создайте символьные ссылки на синхронизированные каталоги GNATS в служебный каталог GNATS: + [source,shell] .... # cd /usr/local/shared/gnats/gnats-db # ln -s /usr/gnats/docs .... + Проделайте эту операцию для всех синхронизируемых категорий. . Обновите служебный файл GNATS [.filename]#categories#, расположенный в каталоге [.filename]#$PREFIX/shared/gnats/gnats-db/gnats-adm#: + [.programlisting] .... # This category is mandatory pending:Category for faulty PRs:gnats-admin: # # FreeBSD categories # docs:Documentation Bug:freebsd-doc: .... . Запустите [.filename]#$PREFIX/libexec/gnats/gen-index# для создания индекса. Вывод этой команды должен быть перенаправлен в файл [.filename]#$PREFIX/shared/gnats/gnats-db/gnats-adm/index#. Эту операцию можно выполнять периодически при помощи man:cron[8] или запускать man:cvsup[1] из скрипта, который затем сгенерирует новый индекс: + [source,shell] .... # /usr/local/libexec/gnats/gen-index \ > /usr/local/shared/gnats/gnats-db/gnats-adm/index .... . Протестируйте созданную конфигурацию запросом к базе данных GNATS. Следующая команда выведет список открытых сообщений об ошибках в категории `docs`: + [source,shell] .... # query-pr -c docs -s open .... + Другие интерфейсы, например, порт package:databases/tkgnats[] также должны работать. . Выберите PR и закройте его. [NOTE] ==== Описанная процедура позволяет вам выбирать и просматривать сообщения об ошибках локально. Для редактирования или закрытия вам потребуется зайти на машину `freefall`. ==== [[people]] == Кто есть кто Помимо мастеров репозитория, существует еще несколько участников и групп проекта FreeBSD, с которыми вам как коммиттеру может потребоваться общаться. Краткий и ни в коем случае не полный список приводится ниже. `{jhb}`:: Джон возглавляет проект SMPng и отвечает за архитектуру, дизайн и реализацию перехода на многонитевое ядро. Джон также является редактором статьи "Архитектура SMPng". Если вы работаете с тонкими блокировками многопроцессорного ядра, координируйте свою работу с Джоном. `{doceng}`:: doceng - группа, отвечающая за инфраструктуру построения документации, прием новых коммиттеров документации и актуальность информации относительно CVS на веб-сайте и FTP-сайте FreeBSD. Эта группа не разбирает конфликты. Большая часть обсуждений, связанных с документацией, происходит в {freebsd-doc}. Дополнительную информацию о деятельности группы можно найти в ее http://www.FreeBSD.org/internal/doceng/[собственном документе]. Коммиттеры, заинтересованные в обновлении документации, должны ознакомиться с link:{fdp-primer}[Учебником по Проекту Документирования FreeBSD для новых участников]. `{ru}`:: Руслан великолепно знает тонкости man:mdoc[7]. Если вы пишете справочную страницу и нуждаетесь в совете по ее структуре или разметке, обратитесь к Руслану. `{bde}`:: Брюс занимается общим стилем кода проекта. Если ваш коммит мог бы быть лучше оформлен, Брюс укажет вам на это. Радуйтесь, что такой человек вообще есть. Брюс также является знатоком различных стандартов, применимых к FreeBSD. `{murray}`:: Таков состав группы `{re}`. Эта группа отвечает за сроки и процесс выпуска релизов. В период заморозки кода, выпускающие инженеры принимают окончательные решения по поводу всех изменений системы в ветви, готовящейся к очередному релизу. Если вы хотите интегрировать какие-либо изменения из FreeBSD-CURRENT в FreeBSD-STABLE (какими бы они ни были в данный конкретный момент), вам предстоит общаться с этой группой. + Хироки, кроме того, ведет раздел документации к релизам ([.filename]#src/release/doc/*#). Если ваши изменения стоят того, чтобы быть упомянутыми в информации о релизе, сообщите об этом Хироки. Еще лучше, если вы пошлете патч с предлагаемыми изменениями к документу. `{cperciva}`:: Колин - link:https://www.FreeBSD.org/security/[FreeBSD Security Officer] и отвечает за деятельность группы `{security-officer}`. `{wollman}`:: Если вам нужен совет по поводу темных мест сетевой части ядра, или вы не уверены в планируемом изменении сетевой подсистемы, мудрым решением будет обратиться к Гарретту. Помимо того, он хорошо разбирается в различных стандартах, применимых к FreeBSD. {cvs-src-desc}:: cvs-committers - адрес, используемый CVS для посылки сообщений о коммитах. Вы _никогда_ не должны посылать письма напрямую на этот адрес; следует лишь отвечать на него, когда вам нужно послать короткие комментарии, непосредственно относящиеся к коммиту. {developers-name}:: Все коммиттеры подписаны на список рассылки -developers. Этот список создан для обсуждения вопросов, касающихся "сообщества" коммиттеров FreeBSD, таких как выборы Правления, анонсы и т.п. + {developers-name} служит для только для использования FreeBSD коммиттерами. Коммиттеры должны иметь возможность публично обсуждать вещи, которые должны быть разрешены, перед тем, как они будут публично объявлены. Данные дискуссии не предназначены для широкой публики и могут нанести вред FreeBSD. + Все FreeBSD коммиттеры должны соблюдать авторские права оригинального автора или авторов писем из этого списка рассылки. Не публикуйте и не пересылайте сообщения из {developers-name} вне подписчиков данного списка рассылки без согласия всех авторов. + Нарушители авторских прав будут удалены из списка подписчиков {developers-name}, и будут приостановлены их коммиттерские привилегии. Повторяющиеся или вопиющие нарушения приведут к полному лишению коммиттерских прав. + Этот список _не_ предназначен для обсуждения кода, и _не является_ заменой списков {freebsd-arch}. На самом деле, такое его использование вредит проекту, поскольку открытые обсуждения вопросов, касающихся всего сообщества пользователей FreeBSD в закрытом списке недопустимы. И, наконец: __никогда, действительно никогда не пишите в {developers-name} с копией в другой список рассылки FreeBSD__. Никогда не пишите в какой-либо другой список рассылки с копией в {developers-name:}. Подобные действия серьезно подрывают смысл существования данного списка рассылки. [[ssh.guide]] == SSH: быстрый старт [.procedure] . Если вы используете FreeBSD версии 4.0 или более позднюю, OpenSSH включен в базовую поставку системы. Для более ранних версий обновите и установите OpenSSH из порта package:security/openssh[]. . Для тех, кто не хочет набирать свой пароль каждый раз при использовании man:ssh[1] и использует для авторизации ключи RSA или DSA, удобной будет утилита man:ssh-agent[1]. Если вы собираетесь использовать ее, убедитесь, что она запущена раньше прочих приложений. Пользователи X Window, например, обычно запускают ее из файлов [.filename]#.xsession# или [.filename]#.xinitrc#. Подробнее смотрите в справочной странице man:ssh-agent[1]. . Создайте пару ключей при помощи man:ssh-keygen[1]. Ключи появятся в каталоге [.filename]#$HOME/.ssh/#. . Пошлите ваш публичный ключ (содержимое файла [.filename]#$HOME/.ssh/id_dsa.pub# или [.filename]#$HOME/.ssh/id_rsa.pub#) вашему будущему ментору, чтобы он мог быть помещен в файл [.filename]#yourlogin# в каталоге [.filename]#/c/ssh-keys/# на машине `freefall`. Теперь вы можете пользоваться утилитой man:ssh-add[1] для авторизации один раз за сессию. Утилита запросит кодовую фразу для вашего секретного ключа и затем сохранит ее в агенте авторизации (man:ssh-agent[1]). Если вы хотите удалить сохраненный секретный ключ из агента, используйте команду `ssh-add -d`. Для теста используйте команду типа `ssh freefall.FreeBSD.org ls /usr`. За дополнительной информацией обращайтесь к package:security/openssh[], man:ssh[1], man:ssh-add[1], man:ssh-agent[1], man:ssh-keygen[1] и man:scp[1]. [[rules]] == Большой Список Правил Коммиттера FreeBSD . Уважайте других коммиттеров. . Уважайте других участников проекта. . Обсудите любые значимые изменения _до_ коммита. . Уважайте существующих мейнтейнеров (указанных в поле `MAINTAINER` файлов [.filename]#Makefile# или в файле [.filename]#MAINTAINER# в корневом каталоге репозитория). . Любое спорное изменение необходимо откатить (back out) в ожидании решения, если того требует мейнтейнер. Вопросы безопасности могут перекрывать мнение мейнтейнера, если так решит Security Officer. . Изменения вносятся в ветвь FreeBSD-CURRENT до FreeBSD-STABLE, за исключением случаев, прямо разрешенных выпускающими инженерами или неприменимости изменения к FreeBSD-CURRENT. Любое нетривиальное и не срочное изменение должно быть выдержано в FreeBSD-CURRENT в течение по крайней мере 3 дней перед переносом, чтобы его могли адекватно протестировать. Выпускающие инженеры обладают той же властью в ветви FreeBSD-STABLE, что и мейнтейнеры (см. правило 5). . Не пререкайтесь с другими коммиттерами публично: это дурно выглядит. Если вам необходимо с чем-либо "категорически не согласиться", делайте это личной почтой. . Соблюдайте все периоды заморозки кода (core freeze), а также своевременно читайте списки рассылки `committers` и `developers`, чтобы быть в курсе расписания таких периодов. . Если вы сомневаетесь в какой-либо процедуре, сначала спросите! . Тестируйте свои изменения перед коммитом. . Не производите коммит в деревья [.filename]#src/contrib#, [.filename]#src/crypto# и [.filename]#src/sys/contrib# без _прямого_ разрешения (approval) соответствующего мейнтейнера(ов). Невыполнение этих правил может служить основанием для приостановки или, в случае рецидивов, полного лишения коммиттерских прав. Члены Правления (Core) имеют право временно приостановить права коммиттера до момента, когда Правление в целом сможет решить вопрос. В "аварийном" случае (коммиттер разрушает репозиторий) такие права имеют также ответственные за репозиторий. Для приостановки прав коммиттера более чем на неделю или для полного лишения таковых прав требуется квалифицированное большинство (2/3) голосов Правления. Это правило существует не потому, что Правление состоит из злобных диктаторов, разбрасывающихся коммиттерами словно банками из-под колы, но ради предоставления проекту аварийного выключателя. Если кто-то выходит из-под контроля, важно иметь возможность справиться с ситуацией немедленно, а не быть втянутыми в дебаты. В любом случае, коммиттер, чьи права приостановлены, имеет право на "слушания Правления", на которых определяется срок приостановки или лишения коммиттерских прав. Коммиттер, права которого приостановлены может запросить пересмотр своего вопроса через 30 дней и каждые последующие 30 дней (если общий период приостановки превышает 30 дней). Коммиттер, полностью лишенный прав, может запросить пересмотр по истечении 6 месяцев. Правила пересмотра являются _полностью неформальными_ и во всех случаях Правление имеет право отвергнуть запрос на пересмотр, если считает свое первоначальное решение верным. Во всех прочих аспектах деятельности проекта, Правление является подмножеством коммиттеров и ограничено __теми же правилами__. Само по себе членство в Правлении не дает права преступать описанные правила. Правление обладает "особой силой" только в случае деятельность как целое, а не на индивидуальной основе. Члены Правления - в первую очередь коммиттеры. === Подробности [[respect]] . Уважайте других коммиттеров. + Вы должны относиться к другим коммиттерам как к коллегам по разработке (кем они и являются). Несмотря на возникающие временами попытки утверждать обратное, никто не стал коммиттером по своей или чьей-либо еще глупости, и мало что обижает сильнее, чем подобные обвинения от коллег. Вне зависимости от того, всегда ли мы чувствуем уважение друг к другу или нет (у каждого бывают не лучшие дни), мы всегда должны _выказывать_ уважение к другим коммиттерам, как в публичных форумах, так и в личной почте. + Способность совместной работы в течение длительного времени - одно из главных достижений проекта, много более важное, чем любой набор изменений в коде, и никакие аргументы относительно кода не стоят потерь в возможности гармонично работать вместе. + Чтобы не противоречить этому правилу, никогда не посылайте писем, когда вы злы или каким-либо иным образом можете спровоцировать других на конфронтацию. Сначала успокойтесь, затем подумайте о том, как наиболее эффективно убедить оппонента(ов) в правильности ваших аргументов; не подливайте масла в огонь ради краткого мига злорадства, если ценой будет долгая ругань. Это не просто крайне "энергетически неэффективно": повторяющиеся прецеденты публичной агрессии, влияющие на нашу способность работать вместе, будут всерьез рассмотрены лидерами проекта, и могут привести к приостановке или потере прав коммиттера. Во внимание будут приниматься как публичные высказывания, так и личная переписка; это не означает, что Правление будет требовать раскрытия тайны переписки, однако, все предоставленные затронутыми коммиттерами материалы будут рассмотрены. + Описанные процедуры никого не могут порадовать даже в малом, однако "целостность проекта превыше всего". Никакой объем кода не стоит потери целостности. . Уважайте других участников проекта. + Вы не всегда были коммиттером. В свое время вы были простым сторонним участником (contributor). Помните об этом все время. Помните, сколь важно было добиться внимания и помощи. Не забывайте, насколько ваше участие было важным для вас. Помните свои ощущения. Не препятствуйте другим участникам и не унижайте их. Относитесь к ним с уважением. Возможно, они наши будущие коммиттеры, и они настолько же важны для проекта, как и коммиттеры. Их вклад в проект настолько же ценен и важен, как и ваш. В конце концов, вам пришлось приложить немало усилий для проекта, чтобы стать коммиттером. Всегда помните об этом. + Обдумайте первое правило <> и применяйте его и к другим участникам проекта. . Обсудите любые значимые изменения _до_ коммита. + Репозиторий CVS - не место для анонса изменений или обсуждения их. Все изменения должны обсуждаться в списках рассылки, и лишь после достижения консенсуса вносится в репозиторий. Это не означает, что вы должны спрашивать разрешения на исправление очевидной синтаксической ошибки в коде или опечатки в странице справочника. Вы должны ощутить, когда предполагаемое изменение требует предварительного обсуждения и обратной связи. Как правило, никто не станет возражать против обширных изменений, если результат очевидно лучше предыдущего состояния, однако никто не любит, когда эти изменения __неожиданны__. Лучший способ убедиться, что вы на правильном пути - дать ваш код просмотреть кому-либо еще из коммиттеров. + Если вы сомневаетесь, просите отзыва! . Уважайте существующих мейнтейнеров. + Многие части кода FreeBSD не являются чьей-либо "собственностью": ситуация, когда некто подпрыгнет и завопит, если вы внесете изменения в "его" код, редка; однако, всегда стоит предварительно проверить. Одним из используемых соглашений было добавление строки MAINTAINER в файл [.filename]#Makefile# пакета или части дерева, которая активно поддерживается одним или несколькими коммиттерами; см. также соответствующий раздел link:{developers-handbook}#policies[Source Tree Guidelines and Policies]. В случае, если какой-то участок системы имеет несколько мейнтейнеров, изменение его одним из них должно быть одобрено по крайней мере одним из других. В случаях, когда "принадлежность" кода неясна, вы можете взглянуть на историю коммитов, чтобы понять, кто наиболее активно либо в последнее время работал в этой области. + Отдельные области FreeBSD попадают под контроль коммиттеров, занимающихся поддержкой целых категорий на пути эволюции FreeBSD, таких как локализация или сетевая подсистема. Для дополнительной информации смотрите link:{contributors}#staff-who/[http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/staff-who] . Любое спорное изменение необходимо откатить в ожидании решения, если того требует мейнтейнер. Вопросы безопасности могут перекрывать мнение мейнтейнера, если так решит Security Officer. + Это может быть нелегко, особенно в период конфликта (когда каждый участник уверен, что прав именно он). К счастью, CVS дает возможность, вместо того чтобы вести бушующую перебранку, просто откатить внесенные изменения, успокоиться всем участникам конфликта, а затем попробовать найти взаимоприемлемый путь. Если в конце концов окажется, что изменение стоит того, оно может быть легко применено вновь. В противном случае, пользователям не придется жить с неправильным состоянием дерева исходных текстов, пока стороны заняты выяснением отношений. Запросы на откаты возникают _крайне_ редко, поскольку обсуждение обычно выявляет неверные или спорные моменты до коммита; однако, если такой запрос все же возник, он должен быть безусловно удовлетворен, чтобы мы могли спокойно выяснить, было изменение неверным или нет. . Изменения вносятся в ветвь FreeBSD-CURRENT до FreeBSD-STABLE, за исключением случаев, прямо разрешенных выпускающими инженерами или неприменимости изменения к FreeBSD-CURRENT. Любое нетривиальное и не срочное изменение должно быть выдержано в FreeBSD-CURRENT в течение по крайней мере 3 дней перед переносом, чтобы его могли адекватно протестировать. Выпускающие инженеры обладают той же властью в ветви FreeBSD-STABLE, что и мейнтейнеры (см. правило 5). + Это еще одно "не обсуждаемое" правило: выпускающий инженер безусловно отвечает за последствия, если выясняется что внесенные изменения неверны. Уважайте эти права, и помогайте группе выпуска релизов в работе с ветвью FreeBSD-STABLE. На первый взгляд может показаться, что ветвь FreeBSD-STABLE развивается чересчур консервативно. Не забывайте, однако, что разумный консерватизм - отличительное свойство FreeBSD-STABLE, и что эта ветвь развивается по законам, отличным от законов FreeBSD-CURRENT. Кроме того, нет смысла тестировать изменения в FreeBSD-CURRENT, если они немедленно переносятся в FreeBSD-STABLE. Разработчики FreeBSD-CURRENT должны иметь возможность протестировать внесенные изменения, так что оставьте время для такого тестирования, если только речь не идет о критическом исправлении или о чем-либо очевидно не требующем тестирования (например, исправления опечаток в страницах справочника, очевидных ошибок или опечаток в исходных текстах и т.п.) Иными словами, исходите из соображений здравого смысла. + Изменения в ветви поддержки безопасности (security branches, например, `RELENG_6_0`) должны быть одобрены членом группы `{security-officer}` или, в некоторых случаях, одним из выпускающих инженеров (`{re}`). . Не пререкайтесь с другими коммиттерами публично: это дурно выглядит. Если вам необходимо с чем-либо "категорически не согласиться", делайте это личной почтой. + Для всех участников проекта очень важно поддержание его публичного образа; особенно это важно, если мы хотим продолжать привлекать новых участников. Случается, что, несмотря на все усилия по сохранению власти над собой, люди срываются и грубят друг другу. Лучшее, что здесь можно сделать - минимизировать эффект, пока все участники не успокоятся. Следовательно, вы не должны озвучивать свою ярость публично, а равно и пересылать частную переписку в общедоступные списки рассылки. Выражения, употребляющиеся в переписке один на один зачастую гораздо менее сдержанны, чем те, которые каждый участник употребил бы публично, так что подобной переписке нет места в публичных рассылках: это лишь усугубит и без того неприятную ситуацию. Если кто-либо, говорящий вам нелицеприятные слова, делает это в частной переписке, соблюдайте приличия и вы: отвечайте приватно. Если, по вашему мнению, кто-либо из разработчиков поступает с вами нечестно, и это настолько мучит вас, обратитесь к Правлению, а не выносите конфликт наружу. Правление приложит все силы к разрешению ситуации, выступая в роли третейского судьи. В случаях, когда спор затрагивает какие-либо части кода, и участники не могут прийти к взаимно приемлемому соглашению, Правление может привлечь независимого участника для разрешения вопроса. В этом случае все участники конфликта должны согласиться принять решение, вынесенное третьей стороной. . Соблюдайте все периоды заморозки кода (core freeze), а также своевременно читайте списки рассылки `committers` и `developers`, чтобы быть в курсе расписания таких периодов. + Внесение не одобренных изменений в период заморозки кода является довольно большой ошибкой. Коммиттеры должны быть в курсе событий, прежде чем внести 10 мегабайт изменений после долгого отсутствия. Нарушающие это правило будут подвергаться заморозке коммиттерского бита до прохождения курса в Счастливом Лагере Повышения Квалификации FreeBSD, который организован в Гренландии. . Если вы сомневаетесь в какой-либо процедуре, сначала спросите! + Множество ошибок совершается, когда кто-либо совершает поспешные действия, думая, что поступает правильно. Делая что-либо впервые, вы, скорее всего, не знаете принятых мелочей и тонкостей, и лучше всего будет сначала спросить, не то вы имеете шансы выставить себя не в лучшем свете. Не стоит стыдиться спросить "Как, черт возьми, это надо делать?" Мы и так знаем, что вы умны: иначе вы не стали бы коммиттером. . Тестируйте свои изменения перед коммитом. + Это правило может показаться очевидным. Впрочем, если бы оно действительно было очевидно для всех, мы не так часто сталкивались со случаями явного его нарушения. Если ваши изменения затрагивают ядро, убедитесь, что после него нормально собираются ядра GENERIC и LINT. Если вы изменяете другую часть исходного кода, убедитесь, что код собирается (успешно завершается make buildworld). Если вы изменяете код в какой-либо ветви, убедитесь, что вы тестируете его на машине, которая работает именно на этой ветви кода. Если ваши изменения могут затронуть другие архитектуры, проверьте его на всех поддерживаемых архитектурах. Список доступных ресурсов можно найти на странице link:https://www.FreeBSD.org/internal/[www.FreeBSD.org/internal/]. По мере расширения списка поддерживаемых платформ в кластер будут добавляться соответствующие машины для тестирования. . Не производите коммит в деревья [.filename]#src/contrib#, [.filename]#src/crypto# и [.filename]#src/sys/contrib# без _прямого_ разрешения (approval) соответствующего мейнтейнера(ов). + Описанные деревья содержат исходный код сторонних производителей, который, как правило, импортируется в соответствующие ветви. Любой коммит, даже не выводящий файл из ветви производителя, может стать головной болью для ответственных за эту часть проекта разработчиков. Так что, если у вас нет _прямого_ разрешения от мейнтейнера, _ничего_ не делайте с этой частью репозитория (если, конечно, вы не поддерживаете этот код сами). + Отметим, что только что сказанное вовсе не означает, что вы не должны пытаться улучшить упомянутый код, наоборот, этому будут только рады. Лучше всего, если вы передадите ваши исправления вендору. Если изменения специфичны для FreeBSD, обсудите вопрос с мейнтейнером, возможно, он посчитает разумным применить их локально. Тем не менее, что бы вы ни делали, _не_ производите коммит сами! + Если вы хотите стать ответственным за "ничей" участок дерева исходников, свяжитесь с {core}. === Правила работы с различными архитектурами Начиная с версии 5.0 проект FreeBSD начал поддерживать несколько новых вычислительных архитектур, и более не является "i386(TM)-центричным". Для упрощения поддержки FreeBSD на базе всех этих платформ Правлением было сформулировано следующее заявление: [.blockquote] Основной 32-битной платформой разработки является i386; основная 64-битная платформа - Sparc64. Крупные изменения в дизайне (в том числе основные изменения в API и ABI) до попадания в репозиторий должны быть отлажены по крайней мере на одной 32 и одной 64-битной платформе, желательно на основных поддерживаемых платформах. Платформы i386 и Sparc64 были выбраны по причине широкой распространенности доступности для разработчиков; кроме того, они представляют принципиально разные подходы к дизайну процессора и системы в целом: порядок байт в слове, организация регистров, реализация DMA, кэша, страничной адресации и т.д. Процессор Alpha, конечно, является 64-битным, однако он представляет более традиционный дизайн и потому не может служить достаточно хорошей тестовой платформой для отработки тонкостей, с которыми разработчик может столкнуться на других 64-битных платформах. Платформа ia64 во многом сложна так же, как и Sparc64, однако ее доступность для разработчиков пока оставляет желать лучшего. Мы будем переформулировать эти правила по мере того, как будут меняться цены и доступность 64-битных платформ. Кроме того, разработчики должны быть в курсе наших правил классов поддержки (Tier Policy) различных аппаратных архитектур. Эти правила предназначены для общего описание процесса разработки, и потому отличаются от вышеописанных требований к возможностям и архитектурам. Правила классов поддержки на период выпуска релизов много жестче, чем ограничения на изменения в процессе разработки. === Другие рекомендации Перед коммитом в области документации используйте какие-либо средства проверки орфографии. Для документов SGML, кроме того, при помощи команды `make lint` следует проверить корректность форматирования. Для страниц справочника, при помощи утилиты из коллекции портов `manck` проверяйте корректность перекрестных ссылок и ссылок на файлы, а также наличие всех необходимых ссылок на синонимы (переменная `MLINK`). Не смешивайте функциональные изменения со стилистическими (не изменяющими функциональных свойств кода). Такое смешивание затрудняет вычленение изменений при использовании команды `cvs diff` и, таким образом, может скрыть появившиеся ошибки. Не смешивайте в коммите в деревья [.filename]#doc/# и [.filename]#www/# изменения текста и переформатирование: это затрудняет работу переводчиков. Производите все стилистические изменения или переформатирования отдельными коммитами, и четко обозначайте их как таковые в журнальных сообщениях к коммиту. === Удаление возможностей При необходимости удаления какой-либо функциональной возможности из утилит базовой системы следует использовать следующую схему действий: . В странице справочника и, возможно, в комментариях к релизу опция, утилита или интерфейс объявляются устаревающими и не рекомендованными к использованию (deprecated); их использование выводит предупреждение. . Опция, утилита или интерфейс сохраняются до очередного основного релиза (релиз X.0). . Опция, утилита или интерфейс удаляются, в том числе из документации: теперь они являются устаревшими. Как правило, об этом стоит упомянуть в комментариях к релизу. [[archs]] == Поддержка различных архитектур FreeBSD является хорошо портируемой операционной системой и предназначена для работы на самых разнообразных аппаратных архитектурах. Важной частью процесса обеспечения гибкости в поддержке современных тенденций развития оборудования является деление кода на машинно-зависимый (Machine Dependent, MD) и машинно-независимый (Machine Independent, MI), а также, по возможности, минимизация машинно-зависимой части кода. Каждая новая аппаратная архитектура, которую начинает поддерживать FreeBSD, ощутимо увеличивает работу по поддержке кода, инструментария и процесса выпуска релизов. Кроме того, становится значительно сложнее эффективно тестировать изменения в коде ядра. Все это делает необходимым введение различных классов поддержки для различных архитектур, при сохранении максимальной стабильности малого числа "основных платформ". === Основные намерения Проект FreeBSD предназначен для работы на рабочих станциях, серверах и высокопроизводительных встроенных системах. Сохраняя ориентир на малое количество архитектур в интересах таких систем, проект FreeBSD остается способен поддерживать высокий уровень надежности, стабильности и производительности, а также уменьшить нагрузку на различные группы поддержки проекта, такие как группы поддержки портов, документации, безопасности и выпуска релизов. Разнообразие поддерживаемых аппаратных платформ расширяет область применимости FreeBSD за счет поддержки новых возможностей (например, поддержка 64-битных процессоров, использование во встроенных системах и т.п.); тем не менее, расширение этого списка всегда должно быть тщательно оценено с позиций увеличения затрат на поддержку дополнительной аппаратной платформы. Проект FreeBSD делит различные аппаратные платформы на 4 класса. Для каждого класса описывается набор требований, необходимых для присвоения платформе данного класса, и обязательства разработчиков по отношению к платформе. Кроме того, определяется порядок смены класса для архитектуры. === Класс 1: Полностью поддерживаемые архитектуры Платформы 1 класса полностью поддерживаются группой безопасности, группой выпуска релизов и мейнтейнерами инструментария. Новые возможности, добавляемые в код системы, должны быть полностью функциональны для всех архитектур первого класса для каждого из релизов (исключением могут быть архитектурно-зависимые возможности, такие как драйвера аппаратуры). Как правило, все платформы 1 класса должны поддерживаться системами сборки либо расположенными непосредственно в кластере FreeBSD.org, либо легко доступными для всех разработчиков. Архитектуры первого класса должны быть готовыми к эксплуатации под управлением FreeBSD во всех аспектах, включая процесс установки и среду разработки. В настоящее время платформами 1 класса являются i386, Sparc64, AMD64, and PC98. === Класс 2: Архитектуры для разработчиков Платформы 2 класса не поддерживаются группами безопасности и выпуска релизов. Поддержка инструментария оставляется на усмотрение его мейнтейнеров. Новые возможности, реализуемые в FreeBSD, должны быть реализуемы на этих платформах, однако непосредственная реализация на момент добавления кода в дерево исходных текстов не требуется. Реализация порта на архитектуру 2 класса может быть добавлена в репозиторий, если она не входит в противоречие с текущим состоянием систем первого класса и не влияет в существенной степени на прочие платформы 2 класса. Для добавления архитектуры 2 класса в дерево исходных текстов FreeBSD система должна быть способна загрузиться хотя бы в однопользовательский режим на реальной аппаратуре. Некоторые исключения из последнего правила могут быть сделаны для новой аппаратуры, находящейся в состоянии разработки и временно не доступной для проекта. Обычно архитектурами 2 класса являются те, которые планируются к переходу в 1 класс, но пока находятся в состоянии разработки. Также во втором классе могут находится платформы, перешедшие из 1 класса по причине потери актуальности, по мере того как уменьшается количество ресурсов, доступных для поддержки системы в состоянии готовности к промышленной эксплуатации. В настоящее время платформами 2 класса являются PowerPC и ia64. === Класс 3: Экспериментальные архитектуры Платформы 3 класса не поддерживаются группами безопасности и выпуска релизов. Поддержка инструментария оставляется на усмотрение его мейнтейнеров. Архитектурами третьего класса могут быть: те, для которых нет и в ближайшее время не предвидится доступного проекту оборудования; имеющие менее трех активных разработчиков; не способные загрузиться в однопользовательский режим на реальной аппаратуре (или под управлением эмулятора, если реальная аппаратура недоступна); наконец, системы, которые оцениваются как исчезающие, чья дальнейшая распространенность сомнительна. Поддержка систем 3 класса не вносится в основное дерево исходных текстов FreeBSD, однако работа над такими архитектурами может производиться в репозитории Perforce FreeBSD, для облегчения контроля версий и дальнейшей интеграции с основной массой кода. В настоящее время единственной платформой 3 класса является S/390(R). === Класс 4: не поддерживаемые архитектуры Системы 4 класса никак не поддерживаются проектом. К 4 классу относятся все архитектуры, не перечисленные выше. === Правила смены класса для архитектуры Для переноса платформы из класса в класс требуется решение, утвержденное Правлением, которое, в свою очередь, согласует его с группами безопасности, выпуска релизов и поддержки инструментария. [[ports]] == FAQ по работе с портами .Добавление нового порта === Как добавить новый порт? Для начала прочитайте раздел, посвященный репозиторному копированию. Самым простым будет использовать скрипт `addport` на машине `freefall`. Он добавит порт из указанного вами каталоге, определив нужную категорию из файла [.filename]#Makefile#, добавит строку в файл [.filename]#CVSROOT/modules# и в файл [.filename]#Makefile# для нужной категории. Скрипт был написан `{mharo}` и `{will}`; вопросы и исправления по поводу `addport` следует отправлять Уиллу, как текущему мейнтейнеру. === Что еще следует сделать, добавляя новый порт? Проверьте его. Желательно убедиться в том, что порт и соответствующий пакет корректно собираются. Рекомендуемая последовательность действий такова: [source,shell] .... # make install # make package # make deinstall # pkg_add имя собранного пакета # make deinstall # make reinstall # make package .... Более подробные инструкции можно найти в link:{porters-handbook}[Руководстве FreeBSD по созданию портов]. Пользуйтесь man:portlint[1] для проверки корректности порта. Не обязательно добиваться полного отсутствия предупреждений, но по крайней мере исправьте простейшие из них. Если новый порт прислал человек, еще не упомянутый в link:{contributors}#contrib-additional[Списке прочих участников], добавьте его имя туда. Закройте PR, если новый порт пришел в виде PR. Для этого воспользуйтесь командой `edit-pr _PR#_` на машине `freefall` и измените значение в строке `state` с `open` на `closed`. Затем опишите причину смены статуса, и на этом работа закончена. [[perks]] == Пряники и прочие льготы Увы, льгот, возникающих от того, что вы являетесь коммиттером, не так уж много. Пожалуй, единственным несомненным долговременным преимуществом будет признание вас как компетентного специалиста. Тем не менее, кое-какие льготы все же существуют: Прямой доступ к машине `cvsup-master`:: Будучи коммиттером, вы можете обратиться к `{kuriyama}`, чтобы получить доступ к машине `cvsup-master.FreeBSD.org`, приложив вывод команды `cvpasswd _yourusername_@FreeBSD.org freefall.FreeBSD.org`. Обратите внимание: в командной строке вы должны указать `freefall.FreeBSD.org`, хотя реальным сервером будет `cvsup-master`. Доступом к `cvsup-master` не следует злоупотреблять: это весьма загруженная машина. Бесплатная подписка на комплект из 4 CD или DVD:: Компания http://www.freebsdmall.com[FreeBSD Mall, Inc.] предоставляет для всех коммиттеров FreeBSD возможность бесплатной подписки на выпуски FreeBSD. Порядок подписки появляется в списке рассылки mailto:developers@FreeBSD.org[developers@FreeBSD.org] после каждого релиза. [[misc]] == Прочие вопросы === Почему не следует вносить малозначимые изменения в ветви разработчика (vendor branches)? * После этого действия каждый новый релиз от разработчика требует ручного приложения и объединения патчей. * Что хуже, каждый новый релиз от разработчика требует ручной _проверки_ приложенных патчей. * Опция CVS `-J` не всегда хорошо работает. Можете спросить `{obrien}`, он расскажет вам жутких историй. === Как мне добавить файл в ветвь CVS? Для добавления файла в ветви просто обновите исходные файлы до нужной ветви, а затем используйте команду `cvs add`. Например, если мы хотите перенести файл [.filename]#src/sys/alpha/include/smp.h# из ветви HEAD в ветвь RELENG_6, в которой он пока не существует, можно использовать следующую последовательность действий: .MFC для нового файла [example] ==== [source,shell] .... % cd sys/alpha/include % cvs update -rRELENG_6 cvs update: Updating . U clockvar.h U console.h ... % cvs update -kk -Ap smp.h > smp.h =================================================================== Checking out smp.h RCS: /usr/cvs/src/sys/alpha/include/smp.h,v VERS: 1.1 *************** % cvs add smp.h cvs add: scheduling file `smp.h' for addition on branch `RELENG_6' cvs add: use 'cvs commit' to add this file permanently % cvs commit .... ==== === Какую мета-информацию я должен включать в сообщения для коммита? Помимо информативного описания содержания коммита вам может потребоваться включить в сообщение дополнительную информацию. Она состоит из одной или нескольких строк вида: ключевое слово или словосочетание, двоеточие, табуляции для форматирования, собственно дополнительная информация. Ключевыми словами могут быть: [.informaltable] [cols="1,1", frame="none"] |=== |`PR:` |Идентификатор сообщения об ошибке, затрагиваемого (как правило, закрываемого) данным коммитом. |`Submitted by:` |Имя и e-mail адрес приславшего исправление; для коммиттеров - просто имя пользователя в кластере FreeBSD. |`Reviewed by:` |Имя и e-mail адрес того или тех, кто рецензировал изменения; для коммиттеров - имя пользователя в кластере FreeBSD. Если изменения были посланы в список рассылки на рецензию и получили одобрение, имя списка рассылки. |`Approved by:` |Имя и e-mail адрес того или тех, кто одобрил изменение; как и прежде, для коммиттеров просто имя пользователя в кластере. Обычной практикой является получение одобрения для коммитов в новые для вас области дерева. Кроме того, в период перед каждым релизом все коммиты _должны_ быть одобрены группой выпускающих инженеров. В случае ваших первых коммитов вы должны получить одобрение на них у вашего ментора, и упомянуть его в виде "_username-of-mentor_`(mentor)`". |`Obtained from:` |Имя проекта, из исходного кода которого было взято изменение. |`MFC after:` |Если вы хотите получать по почте напоминания об MFC, укажите число дней, недель или месяцев с момента изначального коммита, через которое вы планируете произвести MFC. |`Security:` |Если ваши изменения затрагивают вопросы безопасности или исправляют какие-либо уязвимости, укажите ссылки на опубликованные отчеты или описание проблемы. |=== .Сообщение для коммита, основанного на PR [example] ==== Вы собираетесь внести коммит, основанный на PR, присланном John Smith и содержащим патч для исправления проблемы. Ваше сообщение должно заканчиваться примерно такими строками: [.programlisting] .... ... PR: foo/12345 Submitted by: John Smith .... ==== .Сообщение для коммита, требующего рецензии [example] ==== Вы собираетесь изменить подсистему работы с виртуальной памятью. Вы опубликовали предполагаемые изменения в соответствующем списке рассылки (в данном случае `freebsd-arch`), и изменения были одобрены. [.programlisting] .... ... Reviewed by: -arch .... ==== .Сообщение для коммита, требующего одобрения [example] ==== Вы намерены произвести коммит в область дерева, для которой определен ведущий (MAINTAINER). Вы скоординировали усилия с мейнтейнером, и он отреагировал "Отлично. Производи коммит." [.programlisting] .... ... Approved by: abc .... Где _abc_ имя пользователя, одобрившего ваш коммит. ==== .Сообщение для коммита, использующего код OpenBSD [example] ==== Вы собираетесь внести изменение, основанное на коде, использованном проектом OpenBSD. [.programlisting] .... ... Obtained from: OpenBSD .... ==== .Сообщение для коммита, планирующего интеграцию из FreeBSD-CURRENT в FreeBSD-STABLE через некоторое время [example] ==== Вы хотите внести изменения, которые должны быть интегрированы из FreeBSD-CURRENT в ветвь FreeBSD-STABLE через две недели. [.programlisting] .... ... MFC after: 2 weeks .... Где _2_ является количеством дней, недель или месяцев, через которое вы планируете интегрировать (MFC) в FreeBSD-STABLE. В качестве _weeks_ может быть использовано `week`, `weeks`, `month`, `months`, либо этот параметр может быть опущен (при этом подразумевается _X_ дней). ==== В отдельных случаях вам потребуется комбинировать приведенные примеры. Рассмотрим ситуацию, когда некто прислал сообщение об ошибке, содержащее код из проекта NetBSD. Вы заинтересовались этим случаем, но он расположен в той части дерева, в которой вы обычно не работаете, так что вы решаете выдать изменения на рассмотрение списка рассылки `arch`. Поскольку изменения были достаточно сложны, вы решаете интегрировать их (MFC) через месяц, чтобы обеспечить адекватное время для тестирования. В описанном случае сообщения для коммита может выглядеть примерно так: [.programlisting] .... PR: foo/54321 Submitted by: John Smith Reviewed by: -arch Obtained from: NetBSD MFC after: 1 month .... === Как мне получить доступ к people.FreeBSD.org для того чтобы разместить там персональную информацию или информацию о моих проектах? `people.FreeBSD.org` - синоним для `freefall.FreeBSD.org`. Просто создайте каталог [.filename]#public_html#. Все, что вы разместите в нем, будет автоматически доступно по адресу http://people.FreeBSD.org/[http://people.FreeBSD.org/]. === Где расположены архивы списков рассылки? Списки рассылки архивируются в иерархию каталогов [.filename]#/g/mail#, видимую на всех машинах кластера как [.filename]#/hub/g/mail# (см. man:pwd[1]). === Мне бы хотелось стать ментором для нового коммиттера. Какого технологического процесса я должен придерживаться? Обратитесь к документу http://www.freebsd.org/internal/new-account/[Процедура создания нового аккаунта]. diff --git a/documentation/content/ru/articles/contributing/_index.adoc b/documentation/content/ru/articles/contributing/_index.adoc index 0e13620842..6a3a59c72a 100644 --- a/documentation/content/ru/articles/contributing/_index.adoc +++ b/documentation/content/ru/articles/contributing/_index.adoc @@ -1,215 +1,227 @@ --- title: Участие в проекте FreeBSD authors: - author: Джордан Хаббард releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "ieee", "general"] --- = Участие в проекте FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример +ifeval::["{backend}" == "html5"] include::shared/ru/mailing-lists.adoc[lines=9..-1] include::shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] +endif::[] [.abstract-title] Аннотация В этой статье описаны различные способы, которыми отдельные лица и организаций могут принять участие в Проекте FreeBSD. ''' toc::[] Итак, вы хотите внести свой вклад во FreeBSD? Это великолепно! Жизнеспособность FreeBSD _основана_ на помощи её пользователей. Ваша помощь не только принимается, она жизненно необходима для продолжения роста FreeBSD. Несмотря на уверения некоторых людей, вам не нужно быть гениальным программистом или персоной, лично связанной с руководящей группой FreeBSD, чтобы ваша помощь была принята. FreeBSD разрабатывает большое и увеличивающееся количество участников со всего мира, самого разного возраста и разных областей технической экспертизы. Работы, которую необходимо сделать, всегда больше, чем разработчиков, могущих её выполнить, и дополнительная помощь всегда приветствуется. Проект FreeBSD занимается операционной системой в целом, а не только ядром или несколькими отдельными утилитами. Таким образом, в нашем [.filename]#TODO#-списке широкий спектр задач: от документации, бета-тестирования и презентаций до программы установки системы и специфических разработок уровня ядра. Люди любого уровня практически в любой области определённо смогут помочь проекту. Коммерческие структуры, связанные с использованием FreeBSD, также приглашаются к диалогу. Нужны ли вам особые расширения, для работы вашего продукта? Вы увидите, что мы отвечаем на ваши запросы, если они не слишком необычны. Вы работаете над дополнительными продуктами? Дайте нам знать! Мы сможем работать вместе над некоторыми его аспектами. Мир свободного программного обеспечения ставит под сомнение многие существующие представления о том, как программного обеспечение разрабатывается, продаётся и поддерживается, и мы настоятельно просим вас посмотреть на него ещё раз. [[contrib-what]] == Что нужно В следующем перечне представлены задачи и подпроекты, являющиеся некоторым отражением различных списков [.filename]#TODO# и запросов пользователей. [[non-programmer-tasks]] === Текущие задачи не для программистов Многие люди, связанные с FreeBSD, не являются программистами. В Проекте участвуют создатели документации, Web-дизайнеры и специалисты по поддержке пользователей. Все, что им нужно для участия, это своё время и желание учиться. . Периодически читайте FAQ и Руководство. Если что-то описано плохо, устарело или даже полностью неправильно, дайте нам знать. Ещё лучше, если вы пришлёте нам исправление (выучить Docbook не так сложно, но и против посланий в формате ASCII никто возражать не будет). . Помогите перевести документацию FreeBSD на ваш родной язык. Если документация на вашем языке уже существует, вы можете помочь перевести дополнительные документы или проверить, не устарели ли переводы. Первым делом взгляните на link:{fdp-primer}#translations[FAQ по переводам] в Учебнике проекта документирования FreeBSD. Вас не призывают перевести все документы FreeBSD - как доброволец, вы можете делать столько переводов, сколько захотите. Если кто-то начал перевод, другие всегда присоединятся. Если у вас есть время и желание перевести одну часть документации, пожалуйста, переведите инструкции по установке. . Время от времени (или даже регулярно) читайте {freebsd-questions} и news:comp.unix.bsd.freebsd.misc. Вам может понравиться делиться своим опытом и помогать людям решать их проблемы; иногда вы сможете узнать для себя что-то новое! Эти форумы могут также стать источником идей, над которыми вам стоит поработать. [[ongoing-programmer-tasks]] === Текущие задачи для программистов Большинство задач, перечисленных здесь, требуют либо значительных затрат времени, либо глубоких знаний ядра FreeBSD, либо того и другого. Однако имеется также много полезных задач, которые подойдут для "воскресных хакеров". . Если вы работаете с FreeBSD-CURRENT и обладаете хорошим подключением к Internet, то существует машина `current.FreeBSD.org`, которая строит полный релиз ежедневно-сейчас и всегда. Попробуйте установить самый последний релиз с этой машины и сообщите обо всех обнаруженных при этом ошибках. . Читайте {freebsd-bugs}. Здесь может встретиться проблема, которую вы сможете конструктивно прокомментировать или патчи, которые вы можете протестировать. Либо вы можете даже попытаться исправить какую-то проблему самостоятельно. . Если вы знаете о существовании каких-либо исправлений ошибок, успешно применённых к -CURRENT, но ещё не перенесённых в -STABLE после достаточно большого интервала времени (обычно несколько недель), направьте коммиттеру вежливое напоминание. . Перенос стороннего программного обеспечения в каталог [.filename]#src/contrib# дерева исходных текстов. . Проверка актуальности кода в каталоге [.filename]#src/contrib#. . Построение из дерева исходных текстов (или её части) с включением режима дополнительных предупреждений, избавление от них. . Исправление предупреждений от портов, которые используют недопустимые вызовы типа `gets()` или включают файл объявлений [.filename]#malloc.h#. . Если вы создавали порты и вам приходилось делать специфичные для FreeBSD исправления, пошлите ваши патчи авторам оригинального программного обеспечения (это упростит вам жизнь при выпуске следующей версии). . Найдите копии официальных стандартов, например, POSIX(R). Вы можете найти несколько ссылок на них на странице Web-сайта link:https://www.FreeBSD.org/projects/c99/[Проекта соответствия FreeBSD стандартам C99 & POSIX]. Сравните поведение FreeBSD с тем, что определено стандартом. Если реакция отличается, особенно в незначительных или непонятных разделах спецификации, направьте об этом PR. Если можете, найдите, как исправить это и включите в PR патч. Если вы полагаете, что в стандарте есть ошибка, направьте запрос его разработчикам. . Предложите дополнительные задачи для этого списка! === Работа с базой сообщений об ошибках PR http://www.FreeBSD.org/cgi/query-pr-summary.cgi[Список сообщений об ошибках FreeBSD] содержит все актуальные сообщения о проблемах и запросы на улучшения, которые были посланы пользователями FreeBSD. База данных PR содержит задачи как для программистов, так и не для них. Просмотрите открытые PR, найдите те, что привлекут ваше внимание. Некоторые из них могут быть очень простыми, требующими лишь ещё одной пары глаз, чтобы посмотреть и подтвердить, что предлагаемое в PR исправление достаточно. Другие могут быть гораздо сложнее и даже вовсе не содержать исправления. Начните с тех PR, которые никому ещё не назначены. Если PR уже за кем-то закреплено, но содержит проблему, которую вы можете решить, направьте по электронной почте письмо человеку, которому назначено это PR, и спросите, можете ли вы поработать над ней-у них уже может готов патч для тестирования или какие-то идеи, которые можно вместе обсудить. === Выберите один из пунктов со странички "идей" http://wiki.freebsd.org/IdeasPage[Список проектов и идей для добровольцев] также доступен для людей, желающих помочь проекту FreeBSD. Список постоянно обновляется и содержит пункты, как для программистов, так и для не программистов, с информацией о каждом проекте. [[contrib-how]] == Как принять участие в работе Характер участия в работе над системой обычно подпадает под одну или несколько из следующих 5 категорий: [[contrib-general]] === Сообщения об ошибках и отзывы общего характера Идеи или пожелания _общего_ технического характера должны направляться по электронной почте в адрес {freebsd-hackers}. Подобным же образом тот, кто интересуется такими вещами (и устойчив к _большому_ потоку почты!) может подписаться на список рассылки {freebsd-hackers}. Обратитесь к link:{handbook}#eresources-mail[Руководству FreeBSD] для получения дополнительной информации об этом и других списках рассылки. Если вы нашли ошибку или предлагаете внести какое-то конкретное исправление, пожалуйста, отправьте сообщение при помощи программы man:send-pr[1] или её link:https://www.FreeBSD.org/send-pr/[Web-эквивалента]. Постарайтесь заполнить все поля в сообщении об ошибке. Если его размер оно не превышает 65 Кбайт, включите все патчи непосредственно в сообщение. Если патч предназначен для дерева исходных текстов, поместите `[PATCH]` в теме сообщения. При включении патчей _не используйте_ технику cut-and-paste, потому что при этом символы табуляции преобразуются в пробелы и патч становится непригодным к использованию. Если объём патчей превышает 20 Кбайт, лучше включать их в сообщение в сжатом виде, для чего упакуйте их (например, при помощи man:gzip[1] или man:bzip2[1]) и обработайте архив утилитой man:uuencode[1]. После отправки сообщения вы должны получить подтверждение и номер для отслеживания. Сохраните этот номер, чтобы использовать его в дальнейшем при направлении подробностей о проблеме по электронной почте на адрес {bugfollowup}. Используйте номер в качестве темы письма, например, `"Re: kern/3377"`. Дополнительная информация о любом сообщении об ошибке должна направляться этим способом. Если вы не получили подтверждения в течение разумного периода времени (от 3 дней до недели, в зависимости от вашего подключения к электронной почты) или по какой-то причине не можете воспользоваться командой man:send-pr[1], то можете попросить кого-нибудь направить сообщение за вас на адрес {freebsd-bugs}. Прочтите также link:{problem-reports}[эту статью], чтобы узнать, как писать хорошие сообщения о проблемах. === Изменения в документации Изменения в документации обсуждаются в {freebsd-doc}. Пожалуйста, посмотрите link:{fdp-primer}[Учебник Проекта документирования FreeBSD] для получения полных инструкций. Посылайте свои пожелания и изменения (принимаются даже самые небольшие!) при помощи man:send-pr[1], как это описано в разделе о <>. === Изменения к имеющемуся исходному коду Добавление нового исходного кода или внесение изменений в существующий является не такой простой задачей, и зависит во многом от того, насколько вы далеки от текущего состояния разработок во FreeBSD. Существуют специальные промежуточные релизы FreeBSD, известные как "FreeBSD-CURRENT", которые доступны несколькими разными способами, удобными разработчикам, активно работающим над системой. Обратитесь к link:{handbook}#current-stable[Руководству FreeBSD] для получения дополнительной информации о получении и использовании FreeBSD-CURRENT. Если вы работаете с несколько устаревшими исходными текстами, то ваши изменения иногда могут оказаться уже ненужными или слишком большими, чтобы повторно интегрировать их во FreeBSD. Уменьшить такой риск можно, подписавшись на списки рассылки {freebsd-announce} и {freebsd-current}, в которых обсуждается текущее состояние системы. Предположим, что вы смогли получить актуальные исходные тексты, на базе которых делали свои изменения. Тогда следующим шагом является создание набора файлов, отражающих ваши изменения для их посылки тем, кто отвечает за поддержку FreeBSD. Это делается при помощи команды man:diff[1]. Предпочтительным форматом man:diff[1] для посылки патчей является унифицированная выдача, создаваемая командой `diff -u`. К примеру: [source,shell] .... % diff -u oldfile newfile .... или [source,shell] .... % diff -u -r -N olddir newdir .... создаст набор патчей в унифицированном формате для конкретного файла с исходным текстом или для иерархии каталогов. Дополнительную информацию можно найти в man:diff[1]. После того, как вы получили набор diff-файлов (которые вы можете протестировать командой man:patch[1]), вы должны прислать их для включения во FreeBSD. Воспользуйтесь программой man:send-pr[1], как это описано в разделе о <>. _Не посылайте_ diff-файлы в список рассылки {freebsd-hackers}, они будут потеряны! Нам очень нужна ваша помощь (это добровольный проект!); из-за нашей занятости мы не сможем рассмотреть его сразу, и он будет находиться в базе данных PR, пока мы не сделаем это. Укажите на вашу посылку, включив строку `[PATCH]` в тему сообщения. Если вы считаете, что это нужно (к примеру, вы добавляли, удаляли или переименовывали файлы), то объедините ваши изменения в `tar`-файл и обработайте его программой man:uuencode[1]. Принимаются также и архивы, созданные программой man:shar[1]. Если ваше изменение потенциально может оказаться сомнительным, например, вы не уверены в отсутствии лицензионных ограничений относительно его распространения, то вы должны послать его напрямую в список рассылки {core}, а не через man:send-pr[1]. В списке рассылки {core} участвует гораздо меньшее количество людей, которые выполняют основную ежедневную работу над FreeBSD. Заметьте, что эта группа также __очень занята__, так что сюда письма нужно посылать только в случае действительной необходимости. Пожалуйста, обратитесь к справке по man:intro[9] и man:style[9] для получения некоторой информации о стиле кодирования. Мы надеемся, что вы хотя бы примете эту информацию к сведению перед тем, как прислать нам свой код. === Новый код или большие дополнительные пакеты В случае значительного объёма присланного вами кода и соответствующей работы, либо добавления к FreeBSD важной новой функции, становится практически всегда необходимо посылать изменения в виде tar-файлов, обработанных uuencode, или передавать их на Web-сайт или FTP-сервер для получения другими людьми. Если у вас нет доступа к Web- или FTP-серверам, попросите в соответствующем списке рассылке FreeBSD кого-нибудь разместить изменения за вас. При работе с большим объёмом кода неизбежно возникает вопрос о соблюдении авторских прав. Допустимыми лицензионными соглашениями для кода, включаемого во FreeBSD, являются следующие: . Лицензионное соглашение BSD. Оно является самым предпочтительным из-за "отсутствия дополнительных условий" и общей привлекательности для коммерческих компаний. Проект FreeBSD далёк от того, чтобы выступать против коммерческого использования, но активно популяризирует такое пересечение коммерческих интересов, которое позволит постепенно запустить механизм инвестиций во FreeBSD. . GNU General Public License, или "GPL". Это лицензионное соглашение не очень популярно у нас из-за объёма требований, которые нужно выполнять всем, кто собирается использовать код в коммерческих целях. Однако, учитывая абсолютное превосходство объёма этого кода (компилятор, ассемблер, инструменты форматирования текста и так далее) было бы глупо отказываться от дополнительных разработок, подпадающих под действие этой лицензии. Код, распространяемый по условиям лицензионного соглашения GPL также размещается в отдельной части дерева исходных текстов, в [.filename]#/sys/gnu# или [.filename]#/usr/src/gnu#, и поэтому легко идентифицируется всяким, для кого GPL представляет проблему. Разработки, подпадающие под действие других типов лицензионных соглашений, должны быть тщательно просмотрены перед принятием решения об их включении во FreeBSD. Разработки, на которые распространяются жёсткие ограничения коммерческих лицензионных соглашений, обычно отвергаются, а авторам всегда предлагается распространять подобные изменения по собственным каналам. Для того, чтобы на вашу работу распространялись условия лицензионного ограничения "в стиле BSD", разместите следующий текст в самом начале каждого файла с исходными текстами, которые вы хотите защитить, заменив текст между `%%` соответствующей информацией: [.programlisting] .... Copyright (c) %%полные_номера_годов%% %%ваше_имя%%, %%ваш_штат%% %%ваш_почтовый_индекс%%. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. $FreeBSD$ .... Для вашего удобства копия этого текста размещена в файле [.filename]#/usr/shared/examples/etc/bsd-style-copyright#. === Деньги, оборудование или Internet-доступ Мы всегда с удовольствием примем материальную помощь, нужную для дальнейшего существования Проекта FreeBSD, а в добровольном проекте, типа нашего маленькая помощь может послужить долго! Безвозмездная передача вычислительной техники также очень важна для расширения списка поддерживаемого периферийного оборудования, так как обычно у нас нет средств для самостоятельного его приобретения. [[donations]] ==== Финансовая помощь The FreeBSD Foundation является некоммерческой организацией, освобождённой от уплаты налогов, созданной с целью реализации целей Проекта FreeBSD. Как организация типа 501(c)3, Фонд обычно освобождается от федерального налога США на прибыль. Суммы безвозмездных пожертвований таким организациям часто вычитаются из общей суммы налогооблагаемой прибыли. Финансовая помощь может быть направлена в виде чеков на адрес: [.address] **** The FreeBSD Foundation + P.O. Box 20247, + Boulder, + CO 80308 + USA **** The FreeBSD Foundation теперь может принимать помощь через Web по системе PayPal. Для направления помощи, пожалуйста, посетите http://www.freebsdfoundation.org[Web-сайт] Фонда. Дополнительную информацию о Фонде FreeBSD можно найти на странице, содержащей http://people.FreeBSD.org/~jdp/foundation/announcement.html[ вводную информации о Фонде FreeBSD]. Для того, чтобы обратиться в Фонд по электронной почте, напишите письмо на адрес mailto:bod@FreeBSDFoundation.org[bod@FreeBSDFoundation.org]. ==== Помощь в виде оборудования Проект FreeBSD с удовольствие примет помощь в виде оборудования, которому он найдёт хорошее применение. Если вы заинтересованы в передаче оборудования, пожалуйста, обратитесь к link:https://www.FreeBSD.org/donations/[Руководству Центра пожертвований]. diff --git a/documentation/content/ru/articles/freebsd-questions/_index.adoc b/documentation/content/ru/articles/freebsd-questions/_index.adoc index c12131d23d..a5e814377d 100644 --- a/documentation/content/ru/articles/freebsd-questions/_index.adoc +++ b/documentation/content/ru/articles/freebsd-questions/_index.adoc @@ -1,241 +1,253 @@ --- title: Как работать со списком рассылки FreeBSD-questions c максимальной отдачей authors: - author: Greg Lehey email: grog@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "microsoft", "opengroup", "qualcomm", "general"] --- = Как работать со списком рассылки FreeBSD-questions c максимальной отдачей :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример +ifeval::["{backend}" == "html5"] include::shared/ru/mailing-lists.adoc[lines=9..-1] include::shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] +endif::[] [.abstract-title] Аннотация В этом документе содержится информация, которая будет полезна тем, кто собирается отправить письмо в список рассылки FreeBSD-questions. Даются советы и рекомендации, которые максимально увеличат шанс на получение полезных ответов. Этот документ регулярно публикуется в списке рассылки FreeBSD-questions. ''' toc::[] == Введение `FreeBSD-questions` является списком рассылки, который поддерживается проектом FreeBSD для оказания помощи тем, у кого возникли вопросы по поводу использования FreeBSD в повседневной работе. В другом списке рассылки, `FreeBSD-hackers`, обсуждаются более сложные вопросы, такие, как направление будущей работы над системой. [NOTE] ==== Термин "хакер" не имеет ничего общего с проникновением на компьютеры других людей. Правильным термином для обозначения такой деятельности является "кракер", однако популярная пресса этого еще не поняла. Хакеры FreeBSD нарушением защиты не занимаются. Более полное описание хакеров находится в руководстве Эрика Рэймонда (Eric Raymond) http://www.catb.org/~esr/faqs/hacker-howto.html[Как стать хакером] ==== Данный регулярно рассылаемый документ предназначен для помощи как тем, кто ищет ответов на вопросы во FreeBSD-questions ("новички"), так и тем, кто на эти вопросы отвечает ("хакеры"). Несомненно, здесь существуют некоторые трения, которые проистекают из-за разных точек зрения этих двух групп. Новички обвиняют хакеров в высокомерии, заносчивости и несостоятельности в оказании помощи, когда как хакеры обвиняют начинающих в том, что последние глупы, не умеют читать по-английски и ждут, что им все будет преподнесено на блюдечке с голубой каемочкой. Конечно, есть элемент правды в обоих этих утверждениях, однако по большей части такие мнения появляются из-за чувства разочарования. В этом документе я постараюсь уменьшить это разочарование и помочь всем получить более хорошие результаты от FreeBSD-questions. В следующем разделе я дам рекомендации по посылке вопросов; после этого мы посмотрим, как нужно на них отвечать. == Как подписаться на FreeBSD-questions FreeBSD-questions является списком рассылки, распространяемым по электронной почте, поэтому вам нужен доступ к системе электронной почты. Зайдите через ваш WWW браузер на {freebsd-questions}. В разделе "Подписка на freebsd-questions" (Subscribing to freebsd-questions) заполните поле "Ваш адрес электронной почты" (Your email address); другие поля являются опциональными. [NOTE] ==== Поля для паролей в форме для подписки предоставляют только слабую защищённость, но должны предохранить других от путаницы с вашей подпиской. __Не используйте ценный пароль__, потому как он будет отослан вам по почте обратно в виде незашифрованного текста. ==== Вы получите подтверждающее письмо от mailman; следуйте включенным в него инструкциям для завершения процесса подписки. И наконец, когда вы получите приветственное письмо от mailman с подробной информацией о списке и с паролем, __пожалуйста, сохраните его__. Если вы когда-нибудь захотите покинуть список рассылки, вам нужна будет эта информация. За дополнительной информацией обращайтесь к следующему разделу. == Как отписаться от FreeBSD-questions Когда вы подписывались на список рассылки FreeBSD-questions, вы получили приглашающее сообщение от mailman. В этом сообщении, кроме всего прочего, вам рассказывалось о том, как отписаться. Вот типичное сообщение: .... Welcome to the freebsd-questions@freebsd.org mailing list! To post to this list, send your email to: freebsd-questions@freebsd.org General information about the mailing list is at: http://lists.freebsd.org/mailman/listinfo/freebsd-questions If you ever want to unsubscribe or change your options (e.g., switch to or from digest mode, change your password, etc.), visit your subscription page at: http://lists.freebsd.org/mailman/options/freebsd-questions/grog%40lemsi.de You can also make such adjustments via email by sending a message to: freebsd-questions-request@freebsd.org with the word `help' in the subject or body (don't include the quotes), and you will get back a message with instructions. You must know your password to change your options (including changing the password, itself) or to unsubscribe. It is: 12345 Normally, Mailman will remind you of your freebsd.org mailing list passwords once every month, although you can disable this if you prefer. This reminder will also include instructions on how to unsubscribe or change your account options. There is also a button on your options page that will email your current password to you. .... Используя URL, указанный в вашем приветственном сообщении, вы можете посетить "страничку по управлению учетной записью" и запросить "отписать" вас от списка рассылки FreeBSD-questions. Подтверждающее письмо будет выслано вам от mailman; следуйте включённым в него инструкциям для завершения процесса отписки. Если вы это сделали, и до сих пор не можете понять, что происходит, отправьте письмо на mailto:freebsd-questions-request@FreeBSD.org[freebsd-questions-request@FreeBSD.org], и они помогут вам разобраться. _Не_ посылайте сообщений во FreeBSD-questions: здесь вам помочь не смогут. == Нужно задавать вопросы в `-questions` или `-hackers`? Общим вопросам по FreeBSD посвящены два списка рассылки, `FreeBSD-questions` и `FreeBSD-hackers`. В некоторых случаях на самом деле не ясно, в каком списке нужно задавать вопрос. Следующий критерий, однако, должен помочь в 98% всех случаев: . Если вопрос является общим, спрашивайте во `FreeBSD-questions`. Примерами могут служить вопросы по установке FreeBSD или использованию конкретных утилит UNIX(R). . Если вы думаете, что вопрос относится к ошибке, но вы не уверены или не знаете, как ее исправить, пошлите сообщение во `FreeBSD-questions`. . Если вопрос относится к ошибке и вы __уверены__, что это ошибка (например, вы можете указать место в коде, где она происходит, и, может быть, у вас есть для нее исправление), то пошлите сообщение в список рассылки `FreeBSD-hackers`. . Если вопрос относится к усовершенствованию FreeBSD, и вы можете дать предложения по ее реализации, то посылайте сообщение во `FreeBSD-hackers`. Имеется также некоторое количество других link:{handbook}#eresources-mail[специализированных списков рассылки]. Здесь также подходит указанный выше критерий, и в ваших интересах следовать ему, потому что именно так можно получить результат. == Перед посылкой вопроса Вы можете (и должны) что-нибудь сделать сами перед тем, как задать вопрос в одном из списков рассылки: * Попытайтесь решить проблему самостоятельно. Если вы пошлёте вопрос, который покажет, что вы пытались решить проблему, ваш вопрос, как правило, привлечёт более положительное внимание со стороны людей, читающих его. Попытка решить проблему самостоятельно также увеличит уровень вашего понимания FreeBSD, и в конечном счёте позволит вам использовать ваши знания для помощи другим, отвечая на вопросы, посылаемые в списки рассылки. * Прочтите страницы справочника и документацию FreeBSD (установлена в [.filename]#/usr/doc# или доступна через WWW на http://www.FreeBSD.org[http://www.FreeBSD.org]), особенно link:{handbook}[Руководство пользователя] и link:{faq}[FAQ]. * Просмотрите и/или поищите в архивах списка рассылки, задавился ли ваш или схожий вопрос (и возможно отвечался) в списке. Вы можете просмотреть и/или поискать в архивах списков рассылки на http://www.FreeBSD.org/mail[http://www.FreeBSD.org/mail] и http://www.FreeBSD.org/search/#mailinglists[http://www.FreeBSD.org/search#mailinglists] соответственно. Это может быть сделано также и на других WWW сайтах, к примеру, на http://marc.theaimsgroup.com[http://marc.theaimsgroup.com]. * Используйте поисковик, например, http://www.google.com[Google] или http://www.yahoo.com[Yahoo] для поиска ответов на ваш вопрос. Google имеет даже http://www.google.com/bsd[BSD ориентированный поисковой интерфейс]. == Как посылать вопрос При посылке сообщения в список рассылки FreeBSD-questions, имейте в виду следующее: * Помните, что за ответы на вопросы о FreeBSD никто денег не получает. Все делают это в свободное время. Вы можете привлечь внимание, послав четко сформулированный вопрос, содержащий как можно больше относящейся к делу информации. Вы можете не получить внимания, послав неполный, непонятный или примитивный вопрос. В действительности можно посылать сообщение в список рассылки FreeBSD-questions и не получить ответа, даже если вы следуете этим правилам. Еще более вероятно не получить ответа, если вы им не следуете. В оставшейся части документа мы рассмотрим, как получить максимум от вопроса во FreeBSD-questions. * Не всякий человек, могущий ответить на вопрос о FreeBSD, читает все сообщения: обычно читается строка с темой письма и решается, представляет ли сообщение интерес. То есть в ваших интересах указать тему письма. "FreeBSD problem" или "Help" недостаточно. Если вы не укажете тему вообще, то многие даже не потрудятся прочесть сообщение. Если тема сообщения недостаточно конкретна, то люди, которые могут ответить, могут его не прочесть. * Оформляйте ваше сообщение так, чтобы оно было читабельно, и ПОЖАЛУЙСТА, НЕ КРИЧИТЕ!!!!!. Мы понимаем, что для многих английский не является родным языком, и не исключаем этого, однако действительно очень трудно и мучительно читать сообщение, полное опечаток или в котором отсутствуют разделители строк. + Не упускайте из виду эффект, который производит плохо отформатированное письмо, причем не только в списке рассылки FreeBSD-questions. По вашему почтовому сообщению люди составляют мнение о вас, и если сообщение плохо отформатировано, содержит по одной строке на абзац, неправильно разделено или полно ошибок, то о вас сложится плохое впечатление. + Множество плохо форматированных сообщений возникает из-за http://www.lemis.com/email.html[неправильно работающих или плохо настроенных почтовых программ]. Известно, что следующие почтовые программы могут посылать неправильно отформатированные сообщения без вашего ведома об этом: ** Eudora(R) ** exmh ** Microsoft(R) Exchange ** Microsoft(R) Outlook + Постарайтесь не использовать MIME: многие используют программы, которые не очень хорошо работают с MIME. * Проверьте правильность настроек времени и временной зоны. Это может выглядеть немножко глупо, потому что ваши сообщения все равно будут доставляться, однако многие люди получают несколько сотен сообщений в день. Зачастую они сортируют входящие сообщения по теме и дате, и если ваше сообщение не будет предшествовать первому ответу, то они могут предположить, что оно потерялось и даже не взглянут на него. * Не включайте не связанные друг с другом вопросы в одно и то же письмо. Во-первых, длинное сообщение отпугивает людей, а во-вторых, труднее найти людей, которые могут ответить на все вопросы, и прочитали такое сообщение. * Сообщите максимальное количество информации. Это трудно, и нужно пояснить, какую информацию нужно сообщать, а поначалу: ** Практически в любом случае важно знать версию FreeBSD, с которой вы работаете. Особенно, в частности, в случае FreeBSD-CURRENT вы должны также указать дату исходных текстов, хотя, конечно, вам не нужно посылать сообщения о -CURRENT в список рассылки FreeBSD-questions. ** В случае любой проблемы, которая _может_ быть связана с работой оборудования, расскажите о вашем аппаратном обеспечении. В случае сомнений предположите, что это, возможно, вина оборудования. Какой тип процессора используется? Насколько он быстр? Какая материнская плата? Сколько установлено памяти? Какое периферийное оборудование? + Конечно, это приговор, но вывод команды man:dmesg[8] зачастую может оказаться очень полезным, так как он говорит не только об оборудовании, с которым вы работаете, но также и о версии FreeBSD. ** Если выдаются сообщения об ошибках, недостаточно написать "I get error messages", напишите (например) "I get the error message 'No route to host'". ** Если ваша система завершает работу аварийно, не пишите "My system panicked", напишите (к примеру) "my system panicked with the message 'free vnode isn't'". ** Если у вас возникли трудности при установке FreeBSD, пожалуйста, опишите ваше оборудование. В частности, важно знать адреса ввода/вывода и IRQ адаптеров, установленных в вашей машине. ** Если у вас возникли трудности в настройке PPP, опишите настройку. Какую версию PPP вы используете? Какой тип аутентификации? У вас используется статическое или динамическое выделение адресов IP? Какие сообщения вы получили в файле протокола? * Основной объем информации, который вы должны дать, представляет собой вывод программ, таких, как man:dmesg[8], или консольные сообщения, которые обычно появляются в файле [.filename]#/var/log/messages#. Не пытайтесь скопировать эту информацию, набрав ее снова; это действительно трудно, и здесь легко сделать ошибку. Чтобы послать содержимое файлов протоколов, сделайте копию файла и воспользуйтесь редактором для того, чтобы обрезать информацию, оставив только относящуюся к делу, либо скопируйте и вставьте текст в ваше сообщение. В случае вывода программ, таких, как man:dmesg[8], перенаправьте вывод в файл и включите его в письмо. Например, + [source,shell] .... % dmesg > /tmp/dmesg.out .... + Эта команда перенаправляет информацию в файл [.filename]#/tmp/dmesg.out#. * Если вы все это сделали, и все же не можете получить ответа, этому могут быть другие причины. Например, проблема столь сложна, что никто не знает ответа, или тот, кто знает, отсутствовал. Если вы не получили ответа, скажем, в течении недели, может помочь повторная посылка сообщения. Если вы не получили ответа на свое второе послание, скорее всего, вы вовсе не получите его из этого списка рассылки. Повторная посылка того же самого сообщения снова и снова только повредит вашей репутации. Подводя итог, давайте предположим, что вы знаете ответ на следующий вопрос (да, это один и тот же вопрос). Выберите, на какой вопрос вы в большей степени готовы ответить: .Сообщение 1 [example] ==== .... Subject: HELP!!?!?? I just can't get hits damn silly FereBSD system to workd, and Im really good at this tsuff, but I have never seen anythign sho difficult to install, it jst wont work whatever I try so why don't you guys tell me what I doing wrong. .... ==== .Сообщение 2 [example] ==== .... Subject: Problems installing FreeBSD I've just got the FreeBSD 2.1.5 CDROM from Walnut Creek, and I'm having a lot of difficulty installing it. I have a 66 MHz 486 with 16 MB of memory and an Adaptec 1540A SCSI board, a 1.2GB Quantum Fireball disk and a Toshiba 3501XA CDROM drive. The installation works just fine, but when I try to reboot the system, I get the message Missing Operating System. .... ==== == Как дополнить вопрос Часто вам бывает нужно дать дополнительную информацию к вопросу, который вы уже отослали. Лучшим способом сделать это является ответ на первоначальное сообщение. Здесь есть три момента: . Вы включаете текст исходного сообщения, чтобы люди знали, о чем вы говорите. Однако не забудьте удалить ненужный текст. . Текст в строке с темой письма остается тем же самым (вы не забыли его указать, не правда ли?). Многие почтовые программы сортируют сообщения по теме письма. Это поможет при группировке сообщений. . Ссылочные номера сообщений в заголовке будут указывать на предыдущее сообщение. Некоторые почтовые программы, такие, как http://www.mutt.org/[mutt], могут _упорядочивать_ сообщения, показывая точную связь между ними. == Как отвечать на вопрос Перед тем, как отвечать на вопрос в списке рассылки FreeBSD-questions, имейте в виду: . Многие замечания, касающиеся посылки вопросов, относятся и к ответам на них. Прочтите эти замечания. . Ответил ли кто-либо на вопрос? Самым простым способом проверить это является сортировка входящей почты по темам писем: тогда (надеемся) вы увидите вопрос с последующими ответами все вместе. + Если кто-то уже ответил на вопрос, это вовсе не значит, что вы не должны посылать свой ответ. Но сначала имеет смысл прочитать все другие ответы. . Есть ли у вас что добавить сверх того, что уже было сказано? В общем случае ответы "Yeah, me too" сильно не помогут, хотя есть и исключения, например, когда кто-нибудь описывает свою проблему и не знает, его ли это ошибка, или что-то не так с аппаратным или программным обеспечением. Если вы посылаете сообщение "me too", включите также относящуюся к делу информацию. . Уверены ли вы, что поняли вопрос? Очень часто тот, кто задает вопрос, путается или не может все хорошо описать. Даже при самом полном понимании системы легко послать ответ, который не отвечает на вопрос. К сожалению, так вы никому не поможете, только ещё больше запутаете и разочаруете спрашивающего. Если никто больше не отвечает, или вы не очень уверены, то всегда можете запросить более подробную информацию. . Уверены ли вы, что ваш ответ корректен? Если нет, то подождите пару дней. Если никого больше не появится с лучшим ответом, чем ваш, то вы можете ответить и сказать, например, "I don't know if this is correct, but since nobody else has replied, why don't you try replacing your ATAPI CDROM with a frog?". . Если нет причин поступить как-то иначе, то ответьте отправителю и в список рассылки FreeBSD-questions. Многие подписчики FreeBSD-questions "таятся": они учатся на чтении сообщений, посланных и отвеченных другими. Если вы пошлете сообщение, представляющее интерес для всех, минуя список рассылки, то лишите этих людей их информации. Будьте внимательны при ответе всем; многие посылают сообщения с сотнями CC-адресатов. В таких случаях удалите лишние строки Cc:. . Из исходного сообщения включите текст, который относится к делу. Избегайте излишнего цитирования, но не переусердствуйте. Тот, кто не читал первоначального сообщения, должен понять, о чём же идёт речь. . Используйте приемы выделения текста, который взят из исходного сообщения и текста, который добавили вы. Лично я нахожу, что для первоначального текста лучше всего работает вставка символа "`>`". Вставка пробела после "`>`" и пустых строк между вашим и первоначальным текстами сделает результат более читабельным. . Поместите ваш ответ в правильном месте (после текста, на который вы отвечаете). Очень трудно читать набор ответов, когда каждый из них следует перед текстом, к которому относится. . Большинство почтовых программ меняют строку темы письма в ответе, предваряя ее текстом типа "Re: ". Если ваша почтовая программа не делает это автоматически, вы должны делать это вручную. . Если спрашивающий не следует соглашениям по форматированию текста (слишком длинные строки, неподходящая строка темы), __пожалуйста__, исправьте эти ошибки. В случае некорректной строки темы письма (типа "HELP!!??") измените её, например, так: "Re: Difficulties with sync PPP (was: HELP!!??)". В таком случае у других людей, пытающихся отследить обсуждение, будет меньше проблем. + В таких случаях хорошо сказать, что вы сделали и почему, но постарайтесь не грубить. Если вы чувствуете, что не можете ответить, не скатываясь на грубость, воздержитесь от ответа вообще. + Если вы хотите ответить на сообщение лишь потому, что оно плохо оформлено, ответьте только автору, но не в список. Если хотите, то в ответ можете просто послать ему эту статью. diff --git a/documentation/content/ru/articles/geom-class/_index.adoc b/documentation/content/ru/articles/geom-class/_index.adoc index 8ae7c22a71..38cb551ccd 100644 --- a/documentation/content/ru/articles/geom-class/_index.adoc +++ b/documentation/content/ru/articles/geom-class/_index.adoc @@ -1,348 +1,358 @@ --- title: Создание класса GEOM authors: - author: Ivan Voras email: ivoras@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "intel", "general"] --- = Создание класса GEOM :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример +ifeval::["{backend}" == "html5"] include::shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/ru/urls.adoc[] +endif::[] [.abstract-title] Аннотация Эта статья документирует некоторые начальные выкладки в разработке GEOM-классов, а также модулей ядра в общем. Предполагается, что читатель близко знаком с программированием на Си в контексте пространства пользовательских процессов (userland). ''' toc::[] [[intro]] == Вступление [[intro-docs]] === Документация Документация по программированию для ядра скудная, это одна из немногих областей программирования, где почти нет хороших учебных пособий, и совет "читай исходники!" - сохраняет свою справедливость. Однако, существует несколько статей и книг разной актуальности, которые рекомендуются к изучению перед тем, как начать программировать: * link:{developers-handbook}[Руководство FreeBSD для разработчиков] - часть Проекта Документации FreeBSD, ничего специфичного о программировании ядра в нем нет, зато есть немного общей полезной информации. * link:{arch-handbook}[Руководство по Архитектуре FreeBSD] - также является частью Проекта Документации FreeBSD, содержит описания некоторых низкоуровневых средств и процедур. Уделите внимание разделу номер 13 - link:{arch-handbook}#driverbasics[Написание драйверов устройств для FreeBSD]. * Несколько интересных статей об устройстве ядра можно найти на сайте http://www.freebsddiary.com[FreeBSD Diary]. * Страницы из раздела номер 9 системного справочника, содержат важную документацию по функциям ядра. * Страница справочника man:geom[4], а также http://phk.freebsd.dk/pubs/[слайды Пола-Хеннинга Кампа ] - общее представление о подсистеме GEOM. * Страницы справочника man:g_bio[9], man:g_event[9], man:g_data[9], man:g_geom[9], man:g_provider[9], man:g_consumer[9], man:g_access[9], а также другие, связанные с вышеупомянутыми и раскрывающие специфический функционал подсистемы GEOM. * Страница справочника man:style[9] - документирует соглашения о стиле оформления кода, которые обязаны быть соблюдены если вы планируете передать ваш код в Subversion репозиторий FreeBSD. [[prelim]] == Подготовка Для того, чтоб заниматься разработками для ядра, желательно иметь два отдельных компьютера. Один из них предназначен для среды разработки и исходных кодов, а второй - для запуска тестов отлаживаемого кода. Второму компьютеру для работы достаточно иметь возможность выполнять начальную загрузку по сети и монтирование файловых систем по сети. В этой ситуации, если отлаживаемый код содержит ошибки и вызовет аварийную остановку системы, то это не повлечет порчу или утерю исходного кода . Второму компьютеру даже не потребуется иметь свой монитор, достаточно будет соединения асинхронных портов кабелем RS-232 или соединения при помощи KVM-устройства. Но так как далеко не у каждого есть два или более компьютеров под рукой, есть пара способов подготовить иную "живую" систему для разработки кода для ядра. Один из них - это разработка в http://www.vmware.com/[VMWare] или http://www.qemu.org/[QEmu] виртуальной машине (это лучшее из доступного, после, конечно-же, выделенного для тестов компьютера). [[prelim-system]] === Настройка системы для разработки Прежде всего необходимо иметь в ядре поддержку `INVARIANTS`. Добавьте следующие строки в файл конфигурации ядра: [.programlisting] .... options INVARIANT_SUPPORT options INVARIANTS .... Для большей информативности при отладке включите поддержку WITNESS, которая будет предупреждать вас в случае возникновения взаимоблокировок: [.programlisting] .... options WITNESS_SUPPORT options WITNESS .... Также включите отладочные символы, если планируете выполнять отладку по дампам аварийных отказов [.programlisting] .... makeoptions DEBUG=-g .... Установка отладочного ядра обычным способом (`make installkernel`) не даст привычного результата: файл ядра будет называться [.filename]#kernel.debug# и будет находиться в [.filename]#/usr/obj/usr/src/sys/KERNELNAME/#. Для удобства, отладочное ядро необходимо скопировать в [.filename]#/boot/kernel/#. Также удобно иметь включенный отладчик ядра, так вы сможете исследовать паники сразу-же после их возникновения. Для включения отладчика добавьте следующие строки в файл конфигурации ядра: [.programlisting] .... options KDB options DDB options KDB_TRACE .... Для автоматического запуска отладчика ядра после возникновения паники может понадобиться установить переменную sysctl: [.programlisting] .... debug.debugger_on_panic=1 .... Паники системы будут происходить, поэтому уделите внимание кэшу файловой системы. Обычно, при включенном механизме softupdates, последняя версия файла может быть утеряна если паника произошла раньше сбрасывания кэша на устройство хранения. Выключение механизма softupdates (посредством монтирования файловой системы с опцией "sync") значительно сказывается на производительности и, опять-же, не гарантирует целостности данных. Как компромисс, можно сократить задержки сбрасывания кэша механизма softupdates. Есть три переменных sysctl, значения которых необходимо изменить (лучше всего - прописав их в [.filename]#/etc/sysctl.conf#): [.programlisting] .... kern.filedelay=5 kern.dirdelay=4 kern.metadelay=3 .... Значения этих переменных - секунды. Для отладки паник ядра необходимы дампы памяти. Так как паника ядра может "сломать" файловую систему, дамп сначала сохраняется в "сырой" раздел. Обычно, это своп-раздел. Поэтому, размер своп-раздела должен быть не меньше размера ОЗУ компьютера. При последующей загрузке дамп копируется в обычный файл. Это происходит сразу-же после проверки и монтирования файловых систем, но перед активированием раздела свопа. Такое поведение контролируется следующими переменными [.filename]#/etc/rc.conf#: [.programlisting] .... dumpdev="/dev/ad0s4b" dumpdir="/usr/core" .... Переменная `dumpdev` указывает на раздел подкачки, а `dumpdir` сообщает системе куда перемещать дамп ядра при следующей загрузке. Сохранение дампа ядра - процесс медленный, и, если у вашего компьютера много оперативной памяти (>256M) и если паники случаются часто, то ожидание сохранения дампов может начать раздражать (вспомним, что над дампом происходит две операции: сохранение в своп-файл и перемещение на файловую систему). В таком случае может оказаться удобным ограничивание объема используемой системой памяти путем установки переменной в [.filename]#/boot/loader.conf#: [.programlisting] .... hw.physmem="256M" .... Если паники случаются часто и размер файловых систем большой (или же вы просто не доверяете softupdates и фоновой проверке файловых систем), рекомендуется отключить фоновую проверку файловых систем посредством установки переменной в [.filename]#/etc/rc.conf#: [.programlisting] .... background_fsck="NO" .... В этом случае файловые системы будут проверяться только при необходимости. Также заметьте, что в случае использования фоновой проверки, новая паника может случиться в то время, когда проверяются диски. Другими словами, наиболее безопасный способ - не иметь много локальных файловых систем, а использовать второй компьютер в качестве NFS-сервера. [[prelim-starting]] === Начало проекта Для написания нового класса GEOM необходимо создать поддиректорию в любой доступной пользователю директории. Совсем не обязательно, чтоб ваш модуль изначально размещался в [.filename]#/usr/src#. [[prelim-makefile]] === Makefile Правилом хорошего тона является создание [.filename]#Makefile#-ов для каждого нетривиального проекта, примером которого конечно-же является создание модулей ядра. Создание [.filename]#Makefile# - дело не сложное благодаря исчерпывающему набору вспомогательных средств, предоставляемых системой. В вкратце, вот как должен выглядеть [.filename]#Makefile# для модуля ядра: [.programlisting] .... SRCS=g_journal.c KMOD=geom_journal .include .... Этот [.filename]#Makefile# (с измененными именами файлов) подойдет к любому модулю ядра. Класс GEOM может размещаться в одном единственном модуле ядра. Если для сборки вашего модуля требуется больше, чем один файл, то перечислите их имена, разделенные пробельными символами, в переменной `SRCS`. [[kernelprog]] == Программирование в ядре FreeBSD [[kernelprog-memalloc]] === Выделение памяти Прочитайте man:malloc[9] - выделение памяти лишь немного отличается от своего эквивалента, используемого в пространстве пользовательских процессов (userland). Наиболее приметно то, что `malloc`() и `free`() принимают дополнительные параметры, которые описаны в странице справочника. Тип "malloc_type" необходимо объявить в секции деклараций файла с исходным кодом, например: [.programlisting] .... static MALLOC_DEFINE(M_GJOURNAL, "gjournal data", "GEOM_JOURNAL Data"); .... Для того, чтобы можно было использовать этот макрос, необходимо включить следующие заголовочные файлы: [.filename]#sys/param.h#, [.filename]#sys/kernel.h# и [.filename]#sys/malloc.h# Существует еще один механизм выделения памяти - UMA (Universal Memory Allocator), описанный в man:uma[9]. Это специфический метод, преимущественно предназначенный для быстрого выделения памяти под списки, состоящие из элементов одинакового размера (например, динамические массивы структур). [[kernelprog-lists]] === Очереди и списки Ознакомьтесь с man:queue[3] Во множестве случаев вам необходимо будет организовывать и управлять такой структурой данных, как списки. К счастью, эта структура данных реализована несколькими способами в виде макросов на Си, а также включена в систему. Наиболее гибкий и часто употребляемый тип списка - TAILQ. Этот тип списка также один из наиболее требовательных к памяти (его элементы - с двойными связями), а также - наиболее медленный (однако счет идет на несколько инструкций ЦПУ, поэтому последнее утверждение не следует воспринимать в всерьез). Если важна скорость получения данных, то возьмите на вооружение man:tree[3] и man:hashinit[9]. [[kernelprog-bios]] === BIOs Структура `bio` используется для всех операций ввода/вывода, касающихся GEOM. Она содержит информацию о том, какое устройство ('поставщик geom') должно ответить на запрос, тип запроса, смещение, длину и указатель на буфер, а также набор "определенных пользователем" флагов и полей . Важным моментом является то, что `bio` обрабатываются асинхронно. Это значит, что во многих частях кода нет аналога к man:read[2] и man:write[2] функциям из пространства пользовательских процессов, которые не возвращают управление пока не выполнится системный вызов. Скорее, по завершении обработки запроса (или в случае ошибки при обработке) как извещение вызывается определенная пользователем функция. Асинхронная модель программирования в чем-то сложней, нежели чаще используемая императивная модель, используемая в пространстве пользовательских процессов; в любом случае, привыкание займет некоторое время. В некоторых случаях могут быть использованы вспомогательные функции `g_write_data`() и `g_read_data`(), но __далеко не всегда__. В частности, эти функции не могут использоваться когда захвачен мьютекс; например, мьютекс GEOM-топологии или внутренний мьютекс, удерживаемый в ходе выполнения `.start`() или `.stop`(). [[geom]] == Программирование в системе GEOM [[geom-ggate]] === Ggate Если максимальная производительность не требуется, то более простой способ совершать преобразования данных - это выполнять их в пространстве пользовательских процессов посредством ggate (GEOM gate). К недостаткам следует отнести невозможность простого переноса кода в ядро. [[geom-class]] === Класс GEOM Класс GEOM выполняет преобразования данных. Эти преобразования могут быть скомпонованы друг с другом в виде дерева. Экземпляр класса GEOM называют __geom__. В каждом классе GEOM есть несколько "методов класса", которые вызываются когда экземпляра класса нет в наличии (или же они не привязаны к конкретному экземпляру класса). * `.init` вызывается тогда, когда системе GEOM становится известно о классе GEOM (например, когда загружается модуль ядра). * `.fini` будет вызван в случае отказа GEOM системы от класса (например, при выгрузке модуля). * `.taste` вызывается, когда в системе появляется новый класс или поставщик geom ("provider"). Если соответствие найдено, то эта функция обычно создает и запускает экземпляр geom. * `.destroy_geom` вызывается при необходимости разрушить экземпляр geom. * `.ctlconf` будет вызван, когда пользователь запросит изменение конфигурации существующего экземпляра geom Также определены функции событий GEOM, которые копируются в экземпляр geom. Поле `.geom` в структуре `g_class` - это список (LIST) экземпляров geom, реализованных из класса. Эти функции вызываются из g_event потока ядра. [[geom-softc]] === Softc "softc" - это устаревший термин для "приватных данных драйвера" ("driver private data"). Название вероятней всего происходит от устаревшего термина "software control block". В системе GEOM softc это структура (точнее: указатель на структуру) которая может быть присоединена к экземпляру geom и может содержать приватные данные экземпляра. У большинства классов GEOM есть следующие члены: * `struct g_provider *provider` : "поставщик geom" предоставляемый данным экземпляром geom * `uint16_t n_disks` : Количество потребителей geom ("consumer"), обслуживаемых данным экземпляром geom * `struct g_consumer \**disks` : Массив `struct g_consumer*`. (Невозможно обойтись одинарным указателем, потому что система GEOM создает для нас структуры struct g_consumer) Структура `softc` содержит состояние экземпляра geom. У каждого экземпляра есть свой softc. [[geom-metadata]] === Метаданные Формат метаданных в той или иной мере зависит от конкретного класса, но _обязан_ начинаться с: * 16-байтного буфера для подписи - строки с завершающим нулем (обычно это имя класса) * uint32 идентификатора версии Подразумевается, что классы geom знают как обращаться с метаданными с идентификаторами версий ниже, чем их собственные. Метаданные размещаются в последнем секторе поставщика geom (поэтому обязаны целиком умещаться в нем). (Все это зависит от реализации, но весь существующий код работает подобно описанному и поддерживается библиотеками.) [[geom-creating]] === Маркирование/создание экземпляра geom Последовательность событий следующая: * пользователь запускает служебную программу man:geom[8] * программа решает каким классом geom ей придется управлять и ищет библиотеку [.filename]#geom_CLASSNAME.so# (которая обычно находится в [.filename]#/lib/geom#). * она открывает библиотеку при помощи man:dlopen[3], извлекает вспомогательные функции и определения параметров командной строки. Вот так происходит создание/маркирование нового экземпляра geom: * man:geom[8] ищет команду в аргументах командной строки (обычно это `label`) и вызывает вспомогательную функцию. * Вспомогательная функция проверяет параметры и собирает метаданные, которые записываются во все вовлеченные поставщики geom. * Это "повреждает (spoil)" существующие экземпляры geom (если они были) и порождает новый виток "тестирования" поставщиков geom. Целевой класс geom опознает метаданные и активирует экземпляр geom. (Приведенная выше последовательность событий зависит от конкретной реализации, но весь существующий код работает подобно описанному и поддерживается библиотеками.) [[geom-command]] === Структура команд geom Вспомогательная библиотека [.filename]#geom_CLASSNAME.so# экспортирует структуру `class_commands`, которая является массивом элементов `struct g_command`. Эти команды одинакового формата и выглядят следующим образом: [.programlisting] .... команда [-опции] имя_geom [другие] .... Общими командами являются: * label - записать метаданные в устройства, чтобы они могли быть опознаны в процессе тестирования и использованы в соответствующих экземплярах geom * destroy - разрушить метаданные, за которым последует разрушение экземпляров geom Общие опции: * `-v` : детальный вывод * `-f` : принудить Некоторые операции, к примеру маркирование метаданными и разрушение метаданных могут быть выполнены из пространства пользовательских процессов. Для этого, структура `g_command` содержит поле `gc_func`, которое может быть установлено на функцию (в том-же [.filename]#.so#), которая будет вызвана для обработки команды. В случае, когда `gc_func` равно NULL, команда будет передана модулю ядра: функции `.ctlreq` класса GEOM. [[geom-geoms]] === Экземпляры geom У экземпляров классов GEOM есть внутренние данные, которые хранятся в структурах softc, а также есть некоторые функции, посредством которых они реагируют на внешние события. Функции событий: * `.access` : просчитывает права доступа (чтение/запись/исключительный доступ) * `.dumpconf` : возвращает информацию о экземпляре geom; формат XML * `.orphan` : вызывается, когда отсоединяется любой из низлежащих поставщиков geom * `.spoiled` : вызывается, когда производится запись в низлежащий поставщик geom * `.start` : обрабатывает ввод/вывод Эти функции вызываются из ядерного потока `g_down` и в этом контексте не может быть блокировок (поищите определение "блокировка" в других источниках), что немного ограничивает свободу действий, но способствует быстроте обработки. Из вышеупомянутых, наиболее важной и выполняющей полезную работу функцией является `.start`(), которая вызывается всякий раз, когда поставщику geom, управляемому экземпляром класса, приходит запрос BIO. [[geom-threads]] === Потоки выполнения системы geom Системой GEOM в ядре ОС создаются и используются три потока выполнения (kernel threads): * `g_down` : Обрабатывает запросы, приходящие от высокоуровневых сущностей (таких, как запросы из пространства пользовательских процессов) на пути к физическим устройствам * `g_up` : Обрабатывает ответы от драйверов устройств на запросы, выполненные высокоуровневыми сущностями * `g_event` : Отрабатывает в остальных случаях, как-то создание экземпляра geom, просчитывание прав доступа, события "повреждения" и т.п. Когда пользовательский процесс запрашивает "прочитать данные X по смещению Y файла", происходит следующее: * Файловая система преобразует запрос в экземпляр структуры bio и передает его системе GEOM. Файловая система "знает", что экземпляр geom должен обработать запрос, так как файловые системы размещаются непосредственно над экземпляром geom. * Запрос завершается вызовом функции `.start`() в потоке g_down и достигает верхнего экземпляра geom. * Верхний экземпляр geom (например, это секционировщик разделов (partition slicer)) определяет, что запрос должен быть переадресован нижестоящему экземпляру geom (к примеру, драйверу диска). Вышестоящий экземпляр geom создает копию запроса bio (запросы bio _ВСЕГДА_ копируются при передаче между экземплярами geom при помощи `g_clone_bio`()!), изменяет поля смещения и целевого поставщика geom и запускает на обработку копию при помощи функции `g_io_request`() * Драйвер диска также получает запрос bio, как вызов функции `.start`() в потоке `g_down`. Драйвер обращается к контроллеру диска, получает блок данных и вызывает функцию `g_io_deliver`() используя копию запроса bio * Теперь, извещение о завершении bio "всплывает" в потоке `g_up`. Сначала в потоке `g_up` вызывается функция `.done`() секционировщика разделов, последний использует полученную информацию, разрушает клонированный экземпляр структуры bio посредством `g_destroy_bio`() и вызывает `g_io_deliver`() используя первоначальный запрос * Файловая система получает данные и передает их пользовательскому процессу За информацией о том, как данные передаются в структуре `bio` между экземплярами geom, смотрите man:g_bio[9] (обратите внимание на использование полей `bio_parent` и `bio_children`). Важный момент в том, что __НЕЛЬЗЯ ДОПУСКАТЬ БЛОКИРОВОК В ПОТОКАХ G_UP И G_DOWN__. Вот неполный перечень того, что нельзя делать в этих потоках: * Вызывать функции `msleep`() или `tsleep`(). * Использовать функции `g_write_data`() и `g_read_data`(), так как они блокируются в момент обмена данными с потребителями geom. * Ожидать ввод/вывод. * Вызывать man:malloc[9] и `uma_zalloc`() с установленным флагом `M_WAITOK`. * Использовать man:sx[9] Это ограничение на код GEOM призвано избежать от "засорения" пути запроса ввода/вывода, так как блокировки обычно не имеют четких временных границ, и нет гарантий на занимаемое время (также на то есть и другие технические причины). Это также значит, что в вышеупомянутых потоках сколь-нибудь сложные операции выполнить нельзя, например: любое сложное преобразование требует выделения памяти. К счастью решение есть: создание дополнительных ядерных потоков. [[geom-kernelthreads]] === Ядерные потоки выполнения, предназначенные для использования в коде geom Ядерные потоки выполнения создаются функцией man:kthread_create[9], в своем поведении они схожи с потоками, созданными в пространстве пользовательских процессов, но есть одно отличие: они не могут известить вызвавший их поток о своем завершении; по завершению - необходимо вызывать man:kthread_exit[9] В коде GEOM обычное назначение этих потоков - разгрузить поток `g_down` (функцию `.start`() ) от обработки запросов. Эти потоки подобны "обработчикам событий" ("event handlers"): у них есть очередь событий (которая наполняется событиями от разных функций из разных потоков; очередь необходимо защищать мьютексом), события из очереди выбираются одно за другим и обрабатываются в большом блоке `switch`(). Основное преимущество использования отдельного потока, который обрабатывает запросы ввода/вывода, то, что он может блокироваться по мере необходимости. Это, несомненно, привлекательно, но должно быть хорошо обдумано. Блокирование - хорошо и удобно, но может существенно снизить производительность преобразований данных в системе GEOM. Особо требовательные к производительности классы могут делать всю работу в функции `.start`(), уделяя особое внимание ошибкам при работе с памятью. Еще одно преимущество потока "обработчика событий" это сериализация всех запросов и ответов, приходящих с разных потоков geom в один поток. Это также удобно, но может быть медленным. В большинстве случаев, обработка запросов функцией `.done`() может быть оставлена потоку `g_up`. У мьютексов в ядре FreeBSD (man:mutex[9]) есть одно различие с их аналогами из пространства пользовательских процессов - во время удержания мьютекса в коде не должно быть блокировки. Если в коде необходимо блокирование, то лучше использовать man:sx[9]. С другой стороны, если вся ваша работа выполняется в одном потоке, вы можете обойтись вообще без мьютексов. diff --git a/documentation/content/ru/articles/gjournal-desktop/_index.adoc b/documentation/content/ru/articles/gjournal-desktop/_index.adoc index cdff660fdf..521fa7c8e0 100644 --- a/documentation/content/ru/articles/gjournal-desktop/_index.adoc +++ b/documentation/content/ru/articles/gjournal-desktop/_index.adoc @@ -1,438 +1,444 @@ --- title: Настройка журналирования UFS для настольного компьютера. authors: - author: Manolis Kiagias email: manolis@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "general"] --- = Настройка журналирования UFS для настольного компьютера. :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример + +ifeval::["{backend}" == "html3"] include::shared/authors.adoc[] include::shared/ru/mailing-lists.adoc[lines=9..-1] include::shared/ru/urls.adoc[] - -ifeval::["{backend}" == "html5"] :imagesdir: ../../../images/articles/gjournal-desktop/ endif::[] ifeval::["{backend}" == "pdf"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] :imagesdir: ../../../../static/images/articles/gjournal-desktop/ endif::[] ifeval::["{backend}" == "epub3"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] :imagesdir: ../../../../static/images/articles/gjournal-desktop/ endif::[] [.abstract-title] Аннотация Журналируемая файловая система использует лог для записи всех транзакций, происходящих в файловой системе, который также сохраняет ее целостность в случае краха системы или пропадания питания. Несмотря на то, что всё еще возможна потеря несохранённых изменений файлов, журналирование почти полностью исключает возможность повреждения структуры файловой системы, вызванное непредвиденным остановом работы. Журналирование также сокращает до минимума время, необходимое для проверки файловой системы после отказа. Несмотря на то, что в используемой FreeBSD файловой системе UFS нет поддержки журналирования, новый класс системы GEOM в FreeBSD 7._X_ может быть использован для для ведения независимого от файловой системы журналирования. Эта статья объясняет, как реализовать журналирование UFS для типичного настольного компьютера. ''' toc::[] [[introduction]] == Вступление Серверное оборудование обычно хорошо защищено от потери питания. Настольный компьютер часто подвержен неожиданным пропаданиям питания, случайным нажатиям кнопки Reset и другим происшествиям (часто связанным с неосторожностью пользователей), которые могут привести к непредвиденным выключениям. Механизм Soft Updates, как правило, достаточно эффективно защищает файловую систему в таких случаях, однако в последствии требуется длительная фоновая проверка. В очень редких случаях повреждения файловой системы достигают того уровня, при котором становится необходимым вмешательство пользователя и данные могут быть утерянными. Новая возможность журналирования, предоставленная системой GEOM, может существенно выручить в подобных случаях, исключая время, необходимое для проверки файловых систем и удостовериваясь, что файловая система быстро восстановлена в целостное состояние. Эта статья описывает порядок действий, необходимых для конфигурирования журналирования UFS на типичном настольном компьютере, в котором один жесткий диск используется для размещения как операционной системы, так и данных. В статье подразумевается установка FreeBSD "с нуля". Шаги достаточно просты и не требуют чрезмерно сложных манипуляций с командной строкой После прочтения данной статьи вы будете знать: * Как зарезервировать место для журнала во время новой установки FreeBSD. * Как загрузить модуль `geom_journal` (или включить поддержку журналирования в специализированном ядре системы). * Как преобразовать существующую файловую систему, в систему, использующую журналирование, и какие опции монтирования использовать в [.filename]#/etc/fstab#. * Как реализовать журналирование на новых (пустых) разделах. * Как диагностировать неполадки, связанные с журналированием. Перед прочтением этой статьи вам необходимо: * Понимать базовые концепции таких операционных систем, как UNIX(R) и FreeBSD. * Быть знакомым с процедурой установки FreeBSD, а также с программой Sysinstall. [WARNING] ==== Процедура, описанная здесь, подразумевает подготовку к новой установке, в которой на дисках еще нет пользовательских данных. Так как эту процедуру можно модифицировать и расширить на системы, которые уже используются, вам настоятельно рекомендуется сделать _резервную копию_ всех ценных данных. Путаница в низкоуровневых операциях с дисками и разделами может привести к фатальным ошибкам и потере данных. ==== [[understanding-journaling]] == Реализация журналирования в FreeBSD Журналирование, предоставляемое системой GEOM в FreeBSD 7._X_, не является особенностью файловой системы (в отличие от, например, файловой системы ext3 в Linux(R)), оно функционирует на блочном уровне. А это значит, что оно может быть применено к разным типам файловых систем, однако для FreeBSD 7.0-RELEASE журналирование может быть применено только для UFS2. Возможность журналирования обеспечивается загрузкой модуля [.filename]#geom_journal.ko# в ядро (или сборкой собственного ядра с активированием соответствующих опций) и использованием команды `gjournal` для конфигурирования файловой системы. В общем, вы предпочтете журналировать файловые системы большого размера, к примеру - [.filename]#/usr#. Однако, вам придется зарезервировать некоторое количество свободного места (см. следующий раздел). Когда файловая система журналируется, некоторая часть дискового пространства требуется для хранения самого журнала. Дисковое пространство, содержащее данные, называется __поставщиком данных (data provider)__, а часть пространства, содержащая журнал, называется __поставщиком журнала (journal provider)__. Поставщики данных и журнала должны быть на разных разделах, если журналирование достраивается к содержащему данные разделу. А если журналирование включается для нового раздела, у вас есть возможность использовать один поставщик для данных и журнала. В любом из двух вышеупомянутых случаев команда `gjournal` задействует поставщики и создаст конечную журналируемую файловую систему. Например: * Вы намереваетесь журналировать файловую систему [.filename]#/usr#, размещенную на [.filename]#/dev/ad0s1f#, файловая система уже содержит данные. * Вы зарезервировали часть дискового пространства на разделе [.filename]#/dev/ad0s1g#. * Используя команду `gjournal`, создаем новый файл устройства [.filename]#/dev/ad0s1f.journal#, для которого [.filename]#/dev/ad0s1f# является поставщиком данных, а [.filename]#/dev/ad0s1g# - поставщик журнала. Это новое устройство необходимо использовать во всех последующих операциях. Размер дискового пространства, отводимого под поставщик журнала, зависит от нагруженности файловой системы, а не от размера самого поставщика данных. Например, для типичного настольного компьютера достаточно отвести 1 Гб под поставщик журнала для файловой системы [.filename]#/usr#, в то время как компьютеру, имеющему интенсивный дисковый ввод/вывод (например, редактирование видео) может потребоваться больше. Если свободное место на поставщике журнала заканчивается раньше, чем происходит сброс журнала на диск, - вы получите панику ядра. [NOTE] ==== Очень маловероятно то, что размеры журнала, предложенные здесь, станут причиной проблем с обычным настольным компьютером (на котором вы просматриваете веб-страницы, обрабатываете текст или проигрываете мультимедийные файлы). Если работа вашего компьютера подразумевает интенсивную дисковую активность, то для обеспечения стабильности следует придерживаться следующего правила: размер ОЗУ должен уместиться в 30% размера, отведенного под журнал. Например, если в вашем компьютере установлен 1 Гб ОЗУ, создайте под поставщик журнала раздел размером около 3.3 Гб. (Умножьте размер ОЗУ в 3.3 раза, чтоб получить размер журнала). ==== Для получения дополнительной информации о журналировании, пожалуйста, прочитайте страницу справочника, посвященную man:gjournal[8]. [[reserve-space]] == Действия, необходимые во время установки FreeBSD === Выделение места под журналирование Типичный настольный компьютер обычно имеет один жесткий диск, на котором хранится как операционная система, так и пользовательские данные. Вероятно, что схема разбития винчестера (по умолчанию), выбранная в меню Sysinstall, является более или менее подходящей: настольному компьютеру не требуется большой раздел [.filename]#/var#, в то время, как для раздела [.filename]#/usr# выделяется значительный объем дискового пространства, ввиду того, что пользовательские данные и множество пэкэджей хранятся именно в поддиректориях [.filename]#/usr#. Разбиение по умолчанию (получаемое при нажатии kbd:[A] в редакторе разделов FreeBSD, называемом Disklabel) не оставляет свободного места. Каждый подлежащий журналированию раздел требует отдельного раздела для журнала. Ввиду того, что раздел [.filename]#/usr# - наибольший, есть смысл немного уменьшить его размер, чтобы получить пространство, необходимое для журнала. В нашем примере используется жесткий диск размером 80 Гб. Следующий скриншот показывает результаты разбиения по умолчанию, выполненного при помощи Disklabel в процессе установки операционной системы: image::disklabel1.png[] Если это разбиение более или менее вас устраивает, то его легко модифицировать для журналирования. Используйте клавиши со стрелками для того, чтобы выделить раздел, отведенный под [.filename]#/usr#, потом нажмите kbd:[D] чтобы удалить его. Теперь переведите подсвечивание к имени диска, находящемуся вверху экрана, и нажмите kbd:[C] - создайте новый раздел [.filename]#/usr#. Новый раздел должен быть меньше на 1 Гб (если вы собираетесь журналировать только [.filename]#/usr#) или на 2 Гб (если журналированию подлежат как [.filename]#/usr#, так и [.filename]#/var#). Во всплывающем окне выберите "создать файловую систему" и укажите [.filename]#/usr# точкой монтирования. [NOTE] ==== Следует ли журналировать [.filename]#/var# раздел? Обычно есть смысл журналировать большие разделы. Вы можете решить не журналировать [.filename]#/var#, однако журналирование на обычном настольном компьютере не причинит вреда. Если файловая система не нагружена (что типично для настольной системы), то можно выделить меньше дискового пространства под журнал. В этом примере подразумевается журналирование двух файловых систем: [.filename]#/usr# и [.filename]#/var#. Естественно, вы можете подкорректировать процедуру под свои задачи. ==== Чтобы не усложнять описываемую методику, для создания разделов, необходимых для размещения журналов, мы будем использовать утилиту Sysinstall. Однако, во время установки утилита Sysinstall требует указания точек монтирования для каждого созданного вами раздела. Но разделы, содержащие журналы, вам никогда и никуда монтировать не придется. Чтобы избежать вопросов о точках монтирования, мы создадим разделы под журналы и установим их тип в swap. Раздел, предназначенный для свопа, никогда и никуда не монтируется, плюс к тому, утилита Sysinstall позволяет создавать столько разделов под своп, сколько необходимо. После первой перезагрузки необходимо подредактировать файл [.filename]#/etc/fstab#, удалив в нём лишние записи о своп-разделах. Для создания своп-раздела, используя клавиши со стрелками, перемещайте подсвечивание к верхней части экрана в утилите Disklabel так, чтобы стало подсвеченным имя диска. Потом, нажмите kbd:[N], введите необходимый размер раздела (_1024M_), а после - выберите во всплывшем окне "swap space". Повторите эти шаги для всех оставшихся журналов. В этом примере мы создаем два раздела, на которых будут размещаться журналы для [.filename]#/usr# и [.filename]#/var#. Конечный результат показан на следующем скриншоте: image::disklabel2.png[] По завершении создания разделов мы рекомендуем вам записать на бумагу названия разделов и их точек монтирования: с этой информацией вы будете сверяться во время конфигурирования. Это также поможет уменьшить количество ошибок, приводящих к повреждению установки. Следующая табличка отображает наши заметки, сделанные для данного примера: .Разделы и журналы [cols="1,1,1", options="header"] |=== | Раздел | Точка монтирования | Журнал |ad0s1d |/var |ad0s1h |ad0s1f |/usr |ad0s1g |=== Дальше продолжайте обычную установку. Однако, мы рекомендуем вам отложить инсталляцию приложений сторонних разработчиков (пакетов) до полной настройки журналирования. [[first-boot]] === Первая загрузка Ваша система загрузится нормально, однако вам необходимо будет подредактировать [.filename]#/etc/fstab# и удалить те лишние своп-разделы, которые вы создавали под журналы. Как правило, в названии файла устройства, созданного автоматически утилитой Sysinstall, присутствует суффикс "b" (в нашем примере это ad0s1b). Удалите другие записи о своп-разделах и перезагрузите компьютер, после чего FreeBSD перестанет их использовать. После второй перезагрузки, компьютер будет готов к конфигурированию журналирования. [[configure-journal]] == Настройка журналирования [[running-gjournal]] === Работа с командой `gjournal` Подготовив необходимые разделы, перейдем к конфигурированию журналирования. Нам будет необходимо загрузиться в однопользовательском режиме, для этого залогинимся пользователем `root` и напечатаем: [source,shell] .... # shutdown now .... Нажмите kbd:[Enter] для получения приглашения командного интерпретатора. Нам необходимо будет размонтировать разделы, которые подлежат журналированию, в нашем примере это [.filename]#/usr# и [.filename]#/var#. [source,shell] .... # umount /usr /var .... Загрузите модуль ядра, необходимый для журналирования: [source,shell] .... # gjournal load .... На данном этапе сверьтесь со своими записями и определите, какие разделы будут использоваться под какой журнал. В нашем примере [.filename]#/usr# располагается на [.filename]#ad0s1f#, а его журнал будет располагаться на [.filename]#ad0s1g#, и, по аналогии, для [.filename]#/var#: файловая система располагается на [.filename]#ad0s1d#, а ее журнал - на [.filename]#ad0s1h#. Наберите следующие команды: [source,shell] .... # gjournal label ad0s1f ad0s1g GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data. GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal. # gjournal label ad0s1d ad0s1h GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data. GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal. .... [NOTE] ==== Если последний сектор любого из двух разделов (поставщиков данных) используется, команда `gjournal` возвратит ошибку. Вам необходимо будет использовать флаг `-F` для принудительной перезаписи, например: [source,shell] .... # gjournal label -f ad0s1d ad0s1h .... Так как это - новая установка, очень маловероятен факт, что что-нибудь будет действительно переписано. ==== На данном этапе созданы два устройства: [.filename]#ad0s1d.journal# и [.filename]#ad0s1f.journal#. Они представляют [.filename]#/var# и [.filename]#/usr# соответственно. Перед монтированием, нам необходимо установить флаг журналирования и снять флаг механизма Soft Updates: [source,shell] .... # tunefs -J enable -n disable ad0s1d.journal tunefs: gjournal set tunefs: soft updates cleared # tunefs -J enable -n disable ad0s1f.journal tunefs: gjournal set tunefs: soft updates cleared .... Теперь, смонтируйте новые устройства в соответствующие места файловой системы (обратите внимание на то, что мы можем использовать опцию монтирования `async`): [source,shell] .... # mount -o async /dev/ad0s1d.journal /var # mount -o async /dev/ad0s1f.journal /usr .... Откройте [.filename]#/etc/fstab# и исправьте записи для следующих файловых систем: [.filename]#/usr# и [.filename]#/var#: [.programlisting] .... /dev/ad0s1f.journal /usr ufs rw,async 2 2 /dev/ad0s1d.journal /var ufs rw,async 2 2 .... [WARNING] ==== Убедитесь, что упомянутые выше записи правильные, иначе старт системы будет проблематичным после перезагрузки! ==== И напоследок, подредактируйте [.filename]#/boot/loader.conf#: добавьте следующую строку и модуль man:gjournal[8] будет загружаться автоматически при старте системы: [.programlisting] .... geom_journal_load="YES" .... Поздравляем! Журналирование успешно сконфигурировано. Вам необходимо лишь набрать `exit` для возвращения в многопользовательский режим или перезагрузить систему, чтобы полностью проверить вашу конфигурацию (рекомендуется). Во время загрузки вы увидите сообщения, подобные следующим: [source,shell] .... ad0: 76293MB XEC XE800JD-00HBC0 08.02D08 at ata0-master SATA150 GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal. GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal. GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data. GEOM_JOURNAL: Journal ad0s1d clean. GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data. GEOM_JOURNAL: Journal ad0s1f clean. .... После непредвиденного останова работы системы сообщения будут немного отличаться, например: [source,shell] .... GEOM_JOURNAL: Journal ad0s1d consistent. .... Это обычно значит, что man:gjournal[8] воспользовался информацией в журнале для возвращения файловой системы к целостному состоянию. [[gjournal-new]] === Журналирование новых разделов Процедура, описанная выше, необходима для подключения журналирования разделов, содержащих данные. Журналирование пустых разделов немного проще, ввиду того, что поставщик данных и поставщик журнала могут быть размещены на одном и том же разделе. Например, предположим, что был установлен новый жесткий диск и был создан новый раздел [.filename]#/dev/ad1s1d#. Создание журнала не сложнее набора: [source,shell] .... # gjournal label ad1s1d .... Размер журнала - 1 Гб по умолчанию. Однако, вы можете изменить это значение используя ключ `-s`. Значение можно задавать в байтах, в килобайтах, мегабайтах или гигабайтах (используя суффикс `K`, `M` или `G`). Имейте ввиду, что команда `gjournal` не позволит вам создать журнал недопустимо малого размера. К примеру, чтобы создать журнал размером в 2Гб, можно использовать следующую команду: [source,shell] .... # gjournal label -s 2G ad1s1d .... Далее, вы можете создать файловую систему на новом разделе, а также разрешить журналирование ключом `-J`: [source,shell] .... # newfs -J /dev/ad1s1d.journal .... [[configure-kernel]] === Встраивание журналирования в специализированное ядро Если вы не желаете загружать `geom_journal` как модуль, то можно встроить его функции прямо в ваше специализированное ядро. Редактируя конфигурационный файл ядра, убедитесь, что в нем находятся следующие две строки: [.programlisting] .... options UFS_GJOURNAL # Прим.: Это включено в GENERIC options GEOM_JOURNAL # А эту строку необходимо добавить .... Соберите и установите новое ядро следуя указаниям link:{handbook}#kernelconfig[Руководства FreeBSD.] И не забудьте удалить соответствующую строку загрузки модуля ("load") из [.filename]#/boot/loader.conf# (если на предыдущем этапе она была туда внесена). [[troubleshooting-gjournal]] == Устранение неполадок с журналированием Этот раздел содержит часто задаваемые вопросы касательно неполадок, связанных с журналированием. === Я получаю паники ядра во время высокой дисковой активности. Как это связано с журналированием? Вероятно, что журнал заполняется раньше, чем происходит сброс его на диск. Помните, размер журнала зависит от загруженности диска, а не от размера поставщика данных. Если загрузка диска высокая, вам потребуется раздел большего размера для журнала. См. замечания в разделе <> === Я допустил некоторые ошибки во время конфигурирования, теперь система не загружается. Можно это как-нибудь исправить? Вы либо забыли внести запись (опечатались) в [.filename]#/boot/loader.conf#, либо есть ошибки в файле [.filename]#/etc/fstab#. Это легко исправить. Нажмите kbd:[Enter], чтобы получить приглашение командного интерпретатора в однопользовательском режиме. Потом, проверьте возможные варианты: [source,shell] .... # cat /boot/loader.conf .... Если отсутствует запись `geom_journal_load`, или она содержит ошибки, журналируемые устройства не создадутся. Загрузите модуль вручную, примонтируйте все разделы и переходите в многопользовательский режим (продолжайте загрузку). [source,shell] .... # gjournal load GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal. GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal. GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data. GEOM_JOURNAL: Journal ad0s1d clean. GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data. GEOM_JOURNAL: Journal ad0s1f clean. # mount -a # exit (boot continues) .... Если же запись о `geom_journal_load` верна, то проверьте [.filename]#/etc/fstab#. Вероятней всего, что вы обнаружите опечатку или отсутствие необходимой записи. В этом случае смонтируйте вручную оставшиеся разделы и продолжите загрузку в многопользовательский режим. === Возможно ли отказаться от журналирования и вернуться к моей привычной файловой системе с механизмом Soft Updates? Несомненно. Используйте приведенную ниже последовательность действий, которая обращает изменения. Разделы, созданные для поставщиков журналов, могут позже быть использованы для других целей. Залогиньтесь `root` и переведите систему в однопользовательский режим: [source,shell] .... # shutdown now .... Размонтируйте журналируемые разделы: [source,shell] .... # umount /usr /var .... Синхронизируйте журналы: [source,shell] .... # gjournal sync .... Остановите поставщиков журналов: [source,shell] .... # gjournal stop ad0s1d.journal # gjournal stop ad0s1f.journal .... Удалите метаданные журналирования со всех задействованных устройств: [source,shell] .... # gjournal clear ad0s1d # gjournal clear ad0s1f # gjournal clear ad0s1g # gjournal clear ad0s1h .... Снимите флаг журналирования и установите флаг механизма Soft Updates: [source,shell] .... # tunefs -J disable -n enable ad0s1d tunefs: gjournal cleared tunefs: soft updates set # tunefs -J disable -n enable ad0s1f tunefs: gjournal cleared tunefs: soft updates set .... Смонтируйте вручную старые (первоначальные) устройства: [source,shell] .... # mount -o rw /dev/ad0s1d /var # mount -o rw /dev/ad0s1f /usr .... Откройте файл [.filename]#/etc/fstab# и приведите его к изначальному виду: [.programlisting] .... /dev/ad0s1f /usr ufs rw 2 2 /dev/ad0s1d /var ufs rw 2 2 .... И напоследок, удалите строку, загружающую модуль `geom_journal`, из файла [.filename]#/boot/loader.conf# и перезагрузите операционную систему. [[further-reading]] == Для дальнейшего ознакомления Журналирование - относительно новая функциональная возможность FreeBSD, и как такова, она еще недостаточно документирована. Однако, вы можете сочти полезными следующие источники: * Новый link:{handbook}#geom-gjournal[раздел Руководства FreeBSD], посвященный журналированию. * http://lists.freebsd.org/pipermail/freebsd-current/2006-June/064043.html[Этот пост] в списке рассылки {freebsd-current}, написанный `{pjd}` - автором man:gjournal[8]. * http://lists.freebsd.org/pipermail/freebsd-questions/2008-April/173501.html[Этот пост] от `{ivoras}` в списке рассылки {freebsd-questions}. * Страницы справочника man:gjournal[8] и man:geom[8]. diff --git a/documentation/content/ru/articles/hubs/_index.adoc b/documentation/content/ru/articles/hubs/_index.adoc index 93bd14b127..c4b0b25c04 100644 --- a/documentation/content/ru/articles/hubs/_index.adoc +++ b/documentation/content/ru/articles/hubs/_index.adoc @@ -1,280 +1,294 @@ --- title: Поддержка зеркал FreeBSD authors: - author: Jun Kuriyama email: kuriyama@FreeBSD.org - author: Valentino Vaschetto email: logo@FreeBSD.org - author: Daniel Lang email: dl@leo.org - author: Ken Smith email: kensmith@FreeBSD.org - author: Дмитрий Морозовский releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "general"] --- = Поддержка зеркал FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример +ifeval::["{backend}" == "html5"] include::shared/ru/mailing-lists.adoc[lines=9..-1] include::shared/ru/urls.adoc[] include::shared/releases.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] +include::../../../../shared/releases.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] +include::../../../../shared/releases.adoc[] +endif::[] [.abstract-title] Аннотация Рабочий вариант статьи, описывающей процесс создания и поддержки зеркала FreeBSD и адресованной администраторам зеркал. ''' toc::[] [NOTE] ==== На текущий момент заявки на подключение новых зеркал не принимаются. ==== [[mirror-contact]] == Контактная информация Координаторы системы зеркал доступны по электронной почте по адресу mailto:mirror-admin@FreeBSD.org[mirror-admin@FreeBSD.org]. Помимо этого, существует {freebsd-hubs}. [[mirror-requirements]] == Требования к зеркалам FreeBSD [[mirror-diskspace]] === Дисковое пространство Одним из наиболее важных требований является дисковое пространство. В зависимости от набора релизов, архитектур и степени полноты зеркала вам может потребоваться огромный объем диска. Не лишним будет помнить, что _официальное_ зеркало, скорее всего, должно быть полным. Веб-страницы всегда должны зеркалироваться полностью. Кроме того, учтите, что приводимые оценки объема относятся к состоянию на момент последнего редактирования данной статьи ({rel112-current}-RELEASE/{rel120-current}-RELEASE). Дальнейший процесс разработки и последующие релизы только увеличат требуемый объем. Кроме того, разумно будет зарезервировать некоторое (10-20%) дополнительное пространство спокойствия ради. Вот некоторые оценки объема: * Полное зеркало FTP: 1.4 TB * Комплект изменений CTM: 10 GB * Веб-страницы: 1 GB Текущее использование диска зеркалом FTP можно посмотреть на link:ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes[ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes]. [[mirror-bandwidth]] === Требования к сетевой связности и пропускной способности Разумеется, у вас должно быть подключение к интернет. Требуемая пропускная способность ваших каналов зависит от предполагаемого профиля использования вашего зеркала. Если вы собираетесь копировать некоторые части FreeBSD для локального использования на вашей машине или в интранете, требования могут быть много мягче, чем для публичного зеркала. Для официального зеркала необходимая пропускная способность увеличивается еще больше. Мы можем дать лишь очень грубые оценки: * Зеркало для локального доступа: фактически минимум не определен, но канал шириной менее 2 Mbps может сделать процесс обновления мучительно медленным. * Неофициальное публичное зеркало: 34 Mbps выглядит неплохо для начала. * Официальное зеркало: рекомендуется канал шириной более 100 Mbps; кроме того, ваша машина должна стоять как можно ближе к граничным маршрутизаторам вашей сети. [[mirror-system]] === Системные требования, процессор и память Эти требования в первую очередь определяются максимальным ожидаемым количеством клиентов (устанавливается администратором сервера). Также, на требуемые ресурсы влияет список сервисов, которые вы будете предоставлять. Зеркала FTP и/или HTTP не требуют особенно много ресурсов. Будьте на чеку, если планируете предоставлять rsync. Выбор rsync может иметь огромное влияние на требования к аппаратным ресурсам, поскольку rsync признан "прожорливым" по памяти. Вот некоторые советы по конфигурации аппаратной части сервера: Для умеренно посещаемого сайта, предоставляющего rsync, можно использовать процессор с частотой 800MHz - 1 GHz и по крайней мере 512MB памяти. Скорее всего, данная конфигурация может считаться минимальной для _официального_ зеркала. Для регулярно посещаемого сайта вам потребуется больше памяти (хорошим стартом будет 2GB) и больше процессорной мощности, что может означать требование многопроцессорной (SMP) платформы. Кроме того, вам потребуется быстрая дисковая подсистема, в первую очередь, для работы с репозиторием SVN (крайне рекомендуем RAID). Контроллер SCSI, оборудованный собственной памятью, также может ощутимо ускорить процесс, поскольку большая часть сервисов связана с большим количеством дисковых запросов небольшого размера. [[mirror-services]] === Предоставляемые сервисы Всякое зеркало должно предоставлять набор основных сервисов. Помимо требуемого минимального набора, существуют дополнительные сервисы, которые администратор сервера может пожелать предоставлять. Этот раздел описывает, какие сервисы вы можете предоставлять, и какие действия для этого потребуются от вас. [[mirror-serv-ftp]] ==== FTP (требуется для FTP зеркала) Это один из наиболее базовых сервисов; его предоставление требуется для каждого зеркала, распространяющего файлы FreeBSD по FTP. Доступ по FTP должен быть анонимным, и не должны применяться какие-либо ограничения по соотношению объема передано/принято (что вообще является, на наш взгляд, странным подходом). Закачка (upload) файлов на сервер не требуется (и _должна_ быть запрещена в разделе FreeBSD). Кроме того, архив файлов FreeBSD должен быть доступен с путем [.filename]#/pub/FreeBSD#. Для предоставления анонимного FTP доступа может быть использован целый ряд программ (перечислены в алфавитном порядке): * `/usr/libexec/ftpd`: базовый FTP-даемон FreeBSD. Не забудьте прочитать man:ftpd[8]. * package:ftp/ncftpd[]: коммерческий пакет, свободен для использования в учебных целях. * package:ftp/oftpd[]: FTP-даемон, написанный в основном с точки зрения защищенности. * package:ftp/proftpd[]: Модульный и очень гибкий FTP-даемон. * package:ftp/pure-ftpd[]: Еще один FTP-даемон, разработанный с позиций защищенности. * package:ftp/twoftpd[]: См. предыдущий пункт. * package:ftp/vsftpd[]: "очень защищенный" ("very secure") ftpd. ftpd, proftpd и, возможно, ncftpd являются наиболее часто встречающимися FTP серверами. Прочие распространены среди существующих зеркал в существенно меньшей степени. Дополнительным поводом для рассмотрения может являться возможность гибко ограничивать количество одновременных соединений, что поможет вам удержать в нужных рамках потребление пропускной способности ваших каналов и машинные ресурсы. [[mirror-serv-rsync]] ==== Rsync (необязательный сервис для FTP зеркала) rsync часто используется для предоставления доступа к FTP-области FreeBSD, чтобы другие зеркала могли синхронизироваться по вашему. Протокол rsync во многом отличается от FTP, в частности, он гораздо гуманнее с точки зрения пропускной способности каналов, поскольку не требует передачи измененного файла целиком (передаются лишь различия). Взамен rsync требует значительных объемов памяти. Размер каждого процесса зависит от размера синхронизируемого модуля (в основном от количества директорий и файлов). rsync может использовать в качестве транспортного протокола `rsh` или `ssh` (по умолчанию); также, может использоваться внутренний протокол rsync (этот метод предпочтителен для публичных rsync-серверов). Поддерживается авторизация клиентов и различные ограничения. Для протокола rsync существует единственный пакет: * package:net/rsync[] [[mirror-serv-http]] ==== HTTP (требуется для веб-страниц, дополнителен для FTP зеркал) Если вы хотите поддерживать зеркало веб-страниц FreeBSD, вам потребуется установить веб-сервер. Дополнительно, вы можете предоставлять HTTP доступ к FTP-набору файлов FreeBSD. Выбор веб-сервера остается на усмотрение администратора зеркала. Некоторые из наиболее популярных веб-серверов перечислены ниже. * package:www/apache13[]: Apache - самый широко распространённый в Интернете веб-сервер, активно используемый проектом FreeBSD. Вы можете также использовать веб-сервер Apache следующего поколения, доступный в коллекции портов как package:www/apache22[]. * package:www/thttpd[]: Для обслуживания большого количества запросов к статическим документам сервер thttpd может оказаться более эффективным, чем Apache. thttpd отлично оптимизирован по производительности при работе под FreeBSD. * package:www/boa[]: Boa - еще одна альтернатива thttpd и Apache. Этот сервер должен быть ощутимо более высокопроизводительным, чем Apache, для полностью статических страниц. На время написания данного документа, впрочем, он не так хорошо оптимизирован под FreeBSD, как thttpd. * package:www/nginx[]: Nginx - высокопроизводительный веб-сервер, отличающийся низкими требованиями к объему оперативной памяти и обладающий ключевыми функциональными возможностями для построения современной веб-инфраструктуры. Функциональные возможности включают следующее: HTTP-сервер, обратный прокси для HTTP, почтовый прокси сервер, кеширование, балансировка нагрузки, сжатие, ограничение количества запросов, мультиплексирование и повторное использование соединений, поддержка разгрузки SSL (SSL offload) и вещания медиапотоков (media streaming). [[mirror-howto]] == Как вести зеркало FreeBSD Теперь вам известно, какая потребуется машина и как предоставлять сервисы, но не как получить их самому. :-) В этом разделе описывается процесс ведения зеркала и поддержания его в актуальном состоянии, в том числе какие инструменты использовать и какие сайты выбирать в качестве источников для синхронизации. [[mirror-ftp-rsync]] === Зеркалирование FTP-области Файлы, доступные по FTP, составляют большую часть зеркала. Они включают __дистрибутивные наборы__, необходимые для установки по сети, __ветви (branches)__, в которых отражено текущее состояние исходных текстов, _образы ISO_ для записи компакт-дисков с дистрибутивами для установки, образами "живых" файловых систем и пакетами, дерево портов, исходные дистрибутивы для сборки портов и кучу готовых пакетов. И, разумеется, все вышеописанное - для разных версий FreeBSD и различных архитектур. Наиболее эффективным будет синхронизация FTP-области при помощи rsync. Для этого следует установить пакет package:net/rsync[], который был описан в разделе <>. Поскольку доступ по протоколу rsync не является обязательным, выбранный вами сайт может его не поддерживать. Возможно, вам придется немного поискать в сетевой окрестности зеркало, поддерживающее rsync. [NOTE] ==== Поскольку от количества клиентов rsync ощутимо зависит загрузка сервера, большинство администраторов вводят ограничения доступа. Для поддержания зеркала вам следует связаться с администратором сайта, с которым вы будете синхронизироваться, для уточнения локальных правил и, возможно, для внесения в них исключения для вас (поскольку вы также поддерживаете зеркало). ==== Строка для синхронизации FreeBSD по rsync выглядит примерно так: [source,shell] .... % rsync -vaHz --delete rsync://ftp4.de.FreeBSD.org/FreeBSD/ /pub/FreeBSD/ .... Загляните в документацию по rsync, также доступную по адресу http://rsync.samba.org/[http://rsync.samba.org/] за дополнительной информацией по различным опциям rsync. Обратите внимание, что в случае синхронизации модуля целиком (а не отдельного каталога) необходимо явно указать результирующий каталог, потому что каталог с именем модуля (в данном случае "FreeBSD") не создается. Для поддержания актуальности вам потребуется создать скрипт для запуска подобной команды из man:cron[8]. [[mirror-www]] === Зеркалирование страниц WWW Веб-сайт FreeBSD следует зеркалировать исключительно при помощи rsync. Командная строка для синхронизации веб-сайта FreeBSD выглядит примерно так: [source,shell] .... % rsync -vaHz --delete rsync://bit0.us-west.freebsd.org/FreeBSD-www-data/ /usr/local/www/ .... [[mirror-how-often]] === Как часто синхронизироваться? Каждое зеркало должно регулярно обновляться. Вам потребуется какой-то набор скриптов, выполняемых посредством man:cron[8]. Поскольку каждый администратор, как правило, пишет такие скрипты сам и на свой лад, мы не можем выдать конкретных указаний. Общие же советы выглядят так: [.procedure] . Создайте скрипт с командой, которая запустит нужное приложение для обновления зеркала. Рекомендуем использовать скрипт на языке обычного `/bin/sh`. . Добавьте команд перенаправления вывода, чтобы записать диагностику работы в файл. . Попробуйте, как ваш скрипт работает. По завершении проверьте логи. . При помощи утилиты man:crontab[1] добавьте ваш скрипт в таблицу регулярных заданий man:crontab[5] соответствующего пользователя. Это должен быть пользователь, отличный от пользователя FTP-даемона, чтобы файлы в FTP-области без атрибута "чтение для всех" не были доступны анонимным FTP-пользователям. Данное свойство используется для тестирования перед выходом новых релизов, для того чтобы удостовериться, что все официальные зеркала содержат все необходимые файлы к моменту официального объявления релиза. Некоторые рекомендуемые установки частоты обновления: * FTP-набор: раз в сутки * WWW-страницы: раз в сутки [[mirror-where]] == С какого сервера синхронизироваться Это важный вопрос, так что мы попытаемся пояснить, откуда берутся ответы. Для начала повторим еще несколько раз: _никогда не синхронизируйтесь с ftp.FreeBSD.org_. [[mirror-where-organization]] === Организация системы зеркал Зеркала организуются по странам. Имена хостов всех официальных зеркал построены по принципу `ftpN.CC.FreeBSD.org`, где _CC_ (country code) - домен верхнего уровня страны, где расположено зеркало, _N_ - номер зеркала в данной стране. Этот же принцип применим к именам хостов `wwwN.CC.FreeBSD.org` и т.п. Кроме того, есть зеркала без доменной части, обозначающей страну. Все они имеют очень хорошие внешние каналы и обслуживают большое число одновременных соединений. Имя `ftp.FreeBSD.org` на самом деле указывает на две машины, одна из которых в настоящее время находится в Дании, а другая в США. Ни одна из этих машин _НЕ_ является основным сайтом, и потому не должна использоваться для синхронизации. Масса документации для "живых" пользователей указывает на `ftp.FreeBSD.org`, так что автоматическим системам ведения зеркал следует выбирать другие источники синхронизации. Кроме того, существует иерархия зеркал в терминах их удаленности от центра, или __слоях__. Основные сайты могут быть описаны как __Зеркала нулевого слоя__. Зеркала, синхронизирующиеся по ним, считаются __слоем 1__, следующие - _слоем 2_ и т.д. Официальные сайты приглашаются на низкие слои, однако следует помнить, что чем меньше номер слоя, тем выше требования к зеркалу, как было описано в <>. Помимо того, доступ к зеркалам 1 слоя может быть ограничен; безусловно ограничен доступ к основным сайтам. Иерархия _слоев_ не отражается в DNS и, вообще говоря, нигде (кроме мастер-сайтов) не документирована. Тем не менее, официальные зеркала с малыми (1-4, как правило) номерами обычно представляют первый слой. (Это грубая оценка, и ни в коем случае не правило). [[mirror-where-where]] === Так откуда же мне синхронизироваться? Главное - НЕ с `ftp.FreeBSD.org`. Короткий ответ: с зеркала, которое расположено недалеко от вас в терминах Интернет, и/или доступ к которому наилучший. [[mirror-where-simple]] ==== Я хочу получить копию зеркала хоть откуда-нибудь! Если у вас нет каких-либо специальных предпочтений или требований, см. <>. Это означает: [.procedure] . Выберите те из них, с которыми вам работать быстрее всего (меньшее число промежуточных узлов и время отклика), и которые предоставляют нужные вам сервисы (такие как rsync). . Свяжитесь с администраторами выбранного сервера, опишите ваши запросы и уточните их правила. . Сконфигурируйте ваше зеркало, как описывалось выше. [[mirror-where-official]] ==== Я поддерживаю официальное зеркало, какой сайт мне выбрать? В основном, правила, описанные в <>, применимы. Дополнительно можно убедиться, что выбранный сайт принадлежит низкому слою. Другие соображения относительно _официальных_ зеркал описаны в <>. [[mirror-where-master]] ==== Мне нужен доступ к основным сайтам! При наличии достаточных причин вы можете получить доступ к одному из основных сайтов. Доступ к ним ограничен; существуют специальные правила их использования. Наличие у вас статуса _официального_ зеркала, безусловно, является хорошим подспорьем. В противном случае убедитесь, что ваша страна действительно нуждается еще в одном зеркале. Если их уже три или более, сначала свяжитесь с администратором соответствующей зоны DNS (mailto:hostmaster@CC.FreeBSD.org[hostmaster@CC.FreeBSD.org]) или напишите в {freebsd-hubs}. Доступ к одному из мастер-сайтов или подходящему зеркалу 1 уровня вам помогут обеспечить те же, кто помогал вам получить статус _официального_ зеркала. В случае неудачи свяжитесь с mailto:mirror-admin@FreeBSD.org[mirror-admin@FreeBSD.org] и попросите помощи у них. Существует один основной сайт для синхронизации набора файлов FTP. [[mirror-where-master-ftp]] ===== ftp-master.FreeBSD.org Это основной сервер для синхронизации FTP набора. В дополнение к FTP, `ftp-master.FreeBSD.org` поддерживает доступ по rsync. Использование этих протоколов описано в <>. Приветствуется предоставление зеркалами _1 уровня_ доступа к FTP-области по протоколу rsync. [[mirror-official]] == Официальные зеркала Официальные зеркала обладают следующим свойствами: * a) имеют запись в домене `FreeBSD.org` (обычно типа CNAME). * b) присутствуют в списке официальных зеркал в Руководстве по FreeBSD и другой документации. На настоящий момент это все, что отличает их от прочих зеркал. Официальные зеркала не обязательно принадлежат к __Первому уровню__, однако, вряд ли можно найти зеркало __уровня 1__, не являющееся официальным. [[mirror-official-requirements]] === Отдельные требования к официальным зеркалам 1 уровня Описать требования для всех официальных зеркал не так просто, поскольку проект FreeBSD достаточно мягок в этом отношении. Несколько проще указать, что требуется от __официальных зеркал уровня 1__. Прочие официальные зеркала должны рассматривать этот список как __настойчивые пожелания__. Зеркала 1 уровня должны: * поддерживать полный список файлов * предоставлять доступ для других зеркал * обеспечивать доступ по протоколам ftp и rsync. Кроме того, администратор такого зеркала должен быть подписан на {freebsd-hubs}. См. link:{handbook}#eresources-mail[здесь] для дополнительной информации о подписке. [IMPORTANT] ==== Администраторы зеркал, в особенности 1 уровня, должны _очень_ внимательно следить за http://www.FreeBSD.org/releng/[графиком релизов]. Это поможет подготовиться к крупным всплескам нагрузки на зеркало, которые всегда происходят после очередного релиза. Кроме того, важно поддерживать актуальность зеркал (в особенности зеркал уровня 1). Если Зеркало1 не синхронизировалось в течение длительного времени, то зеркала следующего уровня будут синхронизироваться по устаревшей информации и т.д. Поддерживайте актуальность ваших зеркал! ==== [[mirror-official-become]] === Как стать официальным зеркалом? На текущий момент заявки на подключение новых зеркал не принимаются. [[mirror-statpages]] == Статистика некоторых зеркал Вот несколько ссылок на статистику использования зеркал [[mirror-statpagesftp]] === Статистика FTP сайтов * ftp.is.FreeBSD.org - mailto:hostmaster@is.FreeBSD.org[hostmaster@is.FreeBSD.org] - http://www.rhnet.is/status/draupnir/draupnir.html[ (загрузка канала)] http://www.rhnet.is/status/ftp/ftp-notendur.html[(FTP процессы)] http://www.rhnet.is/status/ftp/http-notendur.html[(HTTP процессы)] * ftp.cz.FreeBSD.org - mailto:cejkar@fit.vutbr.cz[cejkar@fit.vutbr.cz] - http://www.cz.FreeBSD.org/stats/mrtg/net.html[(загрузка канала)] http://www.freebsd.cz/stats/mrtg/ftpd.html[(FTP процессы)] http://www.freebsd.cz/stats/mrtg/rsyncd.html[(rsync процессы)] * ftp2.ru.FreeBSD.org - mailto:mirror@macomnet.ru[mirror@macomnet.ru] - http://mirror.macomnet.net/mrtg/mirror.macomnet.net_195.128.64.25.html[(Bandwidth)] http://mirror.macomnet.net/mrtg/mirror.macomnet.net_proc.html[(HTTP and FTP users)] diff --git a/documentation/content/ru/articles/ipsec-must/_index.adoc b/documentation/content/ru/articles/ipsec-must/_index.adoc index 43d6ebe49b..450de8c6d5 100644 --- a/documentation/content/ru/articles/ipsec-must/_index.adoc +++ b/documentation/content/ru/articles/ipsec-must/_index.adoc @@ -1,262 +1,272 @@ --- title: Независимое исследование работы IPsec во FreeBSD authors: - author: David Honig email: honig@sprynet.com releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "opengroup", "general"] --- = Независимое исследование работы IPsec во FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример +ifeval::["{backend}" == "html5"] include::shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/ru/urls.adoc[] +endif::[] [.abstract-title] Аннотация Вы только что установили и настроили IPsec, и оно, кажется, заработало. Как это можно проверить? Я опишу метод экспериментальной проверки правильного функционирования IPsec. ''' toc::[] [[problem]] == Постановка задачи Для начала предположим, что Вы <>. Как Вы узнаете, что IPsec <>? Несомненно, соединения не будет, если Вы неверно его сконфигурировали. И оно, конечно, появится в выводе команды man:netstat[1], когда Вы всё сделаете верно. Но можно ли как-то подтвердить сам факт функционирования IPsec? [[solution]] == Решение Для начала немножко криптографической теории: . Шифрованные данные равномерно распределены по области определения, то есть каждый символ имеет максимальную энтропию; . "Сырые" и несжатые данные как правило избыточны, то есть их энтропия меньше максимально возможной. Предположим, что у Вас имеется возможность измерить энтропию входящего и исходящего трафика на сетевом интерфейсе. В этом случае Вы сможете легко отличить зашифрованные данные от открытых, причём даже в том случае, когда часть данных в "режиме шифрования" передаётся в открытом виде, к примеру внешние заголовки IP, которые используются для маршрутизации. [[MUST]] === MUST "Универсальный Статистический Тест для Генераторов Случайных Чисел" Уэли Маурера (Ueli Maurer's Universal Statistical Test for Random Bit Generators), сокращённо http://www.geocities.com/SiliconValley/Code/4704/universal.pdf[MUST] позволяет быстро измерить энтропию последовательного набора данных. Используемый алгоритм похож на алгоритм сжатия. <> приведён исходный код, позволяющий измерять энтропию последовательных кусков данных размером около четверти мегабайта. [[tcpdump]] === Tcpdump Ещё нам нужен способ сохранения информации, проходящей через интерфейс. Программа man:tcpdump[1] позволяет сделать это в случае, если Вы <> с поддержкой __Пакетного Фильтра Беркли (Berkeley Packet Filter)__. Команда [source,shell] .... tcpdump -c 4000 -s 10000 -w dumpfile.bin .... сохранит 4000 пакетов в файл _dumpfile.bin_. В данном примере объём записываемой информации в каждом пакете не может превышать 10,000 байтов. [[experiment]] == Эксперимент Повторите следующие шаги эксперимента: [.procedure] . Откройте два окна терминала и свяжитесь в одном из них с каким-нибудь компьютером через канал IPsec, а в другом - с обычным, "незащищённым" компьютером. . Теперь начните <>. . В "шифрованном" окне запустите команду UNIX(R) man:yes[1], которая будет выдавать бесконечный поток символов `y`. Немножко подождите и завершите её. Затем переключитесь в обычное окно (не использующее канал IPsec) и сделайте то же самое. . Заключительный этап: запустите <>, передав ему для обработки только что сохранённые пакеты через командную строку. Вы должны увидеть что-то вроде изображённого чуть ниже. Заметьте, что безопасное соединение имеет 93% (6,7) от ожидаемого значения (7,18), а обычное соединение - всего лишь 29% (2,1). + [source,shell] .... % tcpdump -c 4000 -s 10000 -w ipsecdemo.bin % uliscan ipsecdemo.bin Uliscan 21 Dec 98 L=8 256 258560 Measuring file ipsecdemo.bin Init done Expected value for L=8 is 7.1836656 6.9396 -------------------------------------------------------- 6.6177 ----------------------------------------------------- 6.4100 --------------------------------------------------- 2.1101 ----------------- 2.0838 ----------------- 2.0983 ----------------- .... [[caveat]] == Замечание Этот эксперимент показывает, что IPsec _действительно_ распределяет передаваемые байты по области определения __равномерно__, как и любое другое шифрование. Однако этот метод _не может_ обнаружить множество других изъянов в системе (хотя я таковых не знаю). Для примера можно привести плохие алгоритмы генерации или обмена ключами, нарушение конфиденциальности данных или ключей, использование слабых в криптографическом смысле алгоритмов, взлом ядра и т. д. Изучайте исходный код, узнавайте, что там происходит. [[IPsec]] == Определение IPsec IPsec представляет собой протокол безопасного обмена информацией по Internet. Существует в виде расширения к IPv4; является неотъемлемой частью IPv6. Содержит в себе протокол шифрования и аутентификации на уровне IP (межмашинное "host-to-host" взаимодействие). SSL защищает только лишь конкретный прикладной сокет; SSH защищает вход на машину; PGP защищает определённый файл или письмо. IPsec шифрует всю информацию, передаваемую между двумя машинами. [[ipsec-install]] == Установка IPsec Большинство современных версий FreeBSD уже имеют поддержку IPsec. Вероятно, Вы должны будете лишь добавить опцию `IPSEC` в конфигурационный файл ядра, и после сборки и инсталляции нового ядра, сконфигурировать соединение IPsec с помощью команды man:setkey[8]. Более подробно о том, как запустить IPsec во FreeBSD можно прочесть в link:{handbook}#ipsec[Руководстве пользователя]. [[kernel]] == src/sys/i386/conf/KERNELNAME Для того, чтобы захватывать сетевой трафик при помощи man:tcpdump[1], следующие строки должны присутствовать в конфигурационном файле ядра. Не забудьте после модификации запустить man:config[8], и, как обычно, пересобрать и установить новое ядро. [.programlisting] .... device bpf .... [[code]] == Универсальный Статистический Тест Маурера (размер блока - 8 бит) Оригинал нижеприведённого кода находится по http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt[ этому адресу]. [.programlisting] .... /* ULISCAN.c ---blocksize of 8 1 Oct 98 1 Dec 98 21 Dec 98 uliscan.c derived from ueli8.c This version has // comments removed for Sun cc This implements Ueli M Maurer's "Universal Statistical Test for Random Bit Generators" using L=8 Accepts a filename on the command line; writes its results, with other info, to stdout. Handles input file exhaustion gracefully. Ref: J. Cryptology v 5 no 2, 1992 pp 89-105 also on the web somewhere, which is where I found it. -David Honig honig@sprynet.com Usage: ULISCAN filename outputs to stdout */ #define L 8 #define V (1< #include int main(argc, argv) int argc; char **argv; { FILE *fptr; int i,j; int b, c; int table[V]; double sum = 0.0; int iproduct = 1; int run; extern double log(/* double x */); printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP); if (argc < 2) { printf("Usage: Uliscan filename\n"); exit(-1); } else { printf("Measuring file %s\n", argv[1]); } fptr = fopen(argv[1],"rb"); if (fptr == NULL) { printf("Can't find %s\n", argv[1]); exit(-1); } for (i = 0; i < V; i++) { table[i] = 0; } for (i = 0; i < Q; i++) { b = fgetc(fptr); table[b] = i; } printf("Init done\n"); printf("Expected value for L=8 is 7.1836656\n"); run = 1; while (run) { sum = 0.0; iproduct = 1; if (run) for (i = Q; run && i < Q + K; i++) { j = i; b = fgetc(fptr); if (b < 0) run = 0; if (run) { if (table[b] > j) j += K; sum += log((double)(j-table[b])); table[b] = i; } } if (!run) printf("Premature end of file; read %d blocks.\n", i - Q); sum = (sum/((double)(i - Q))) / log(2.0); printf("%4.4f ", sum); for (i = 0; i < (int)(sum*8.0 + 0.50); i++) printf("-"); printf("\n"); /* refill initial table */ if (0) { for (i = 0; i < Q; i++) { b = fgetc(fptr); if (b < 0) { run = 0; } else { table[b] = i; } } } } } .... diff --git a/documentation/content/ru/articles/mailing-list-faq/_index.adoc b/documentation/content/ru/articles/mailing-list-faq/_index.adoc index bd093c1fe4..59dd9ed70a 100644 --- a/documentation/content/ru/articles/mailing-list-faq/_index.adoc +++ b/documentation/content/ru/articles/mailing-list-faq/_index.adoc @@ -1,165 +1,179 @@ --- title: Часто задаваемые вопросы по спискам рассылки FreeBSD authors: - author: The FreeBSD Documentation Project copyright: 2004-2005 The FreeBSD Documentation Project releaseinfo: "$FreeBSD$" --- = Часто задаваемые вопросы по спискам рассылки FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример +ifeval::["{backend}" == "html5"] include::shared/authors.adoc[] include::shared/ru/mailing-lists.adoc[lines=9..-1] include::shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] +endif::[] [.abstract-title] Аннотация Эта статья посвящена часто задаваемым вопросам (FAQ) по спискам рассылки FreeBSD. Если вы хотите помочь поддерживать данный документ, напишите письмо в {freebsd-doc}. Последняя версия данного документа доступна на link:.[WWW сервере FreeBSD]. Вы можете получить данную статью в виде одного большого link:.[HTML] файла, используя HTTP протокол или в виде простого текста, форматов PostScript, PDF, и других с link:ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/[FTP сервера FreeBSD]. Возможно вы захотите link:https://www.FreeBSD.org/search/[Найти FAQ]. ''' toc::[] [[introduction]] == Введение Цель этого документа ответить на часто задаваемые вопросы, касающиеся списков рассылки FreeBSD. Хотя FAQ задумывались для снижения количества задаваемых повторяющихся вопросов, они стали восприниматься, как ценные источники информации. Этот документ - попытка представить консенсус всего сообщества, и поэтому он не может считаться __официальным__. Если вы найдете технические неточности в данном документе или у вас есть предложения по добавлению новых пунктов, пожалуйста отправьте PR или напишите в {freebsd-doc}. Спасибо. === Зачем вообще нужны списки рассылки по FreeBSD? Списки рассылки по FreeBSD служат, как первичное средство связи FreeBSD сообщества, они покрывают множество различных тем. === Кто пользуется этими списками рассылки? Это зависит от темы обсуждения каждого конкретного списка рассылки. Некоторые списки больше ориентированны на разработчиков, некоторые на всё сообщество FreeBSD в целом. Список существующих на сегодняшний день списков рассылки доступен http://lists.FreeBSD.org/mailman/listinfo[здесь]. === Доступны ли списки рассылки по FreeBSD для каждого? Повторюсь, это зависит от характера обсуждаемых тем в каждом конкретном листе. Пожалуйста прочтите устав списка рассылки перед отправлением в него письма и соблюдайте его при каждом отправлении. Это будет полезно каждому получить больше опыта по работе со списками рассылки. Если после просмотра выше расположенного списка, вы до сих пор не знаете в какой список рассылки направить письмо, то вам наверняка подойдёт freebsd-questions (но прежде прочтите ниже). Заметьте, что для отправки письма в список рассылки необязательно быть подписанным на него. Это поможет легче присоединиться к сообществу FreeBSD и способствует открытому обмену идей. Но, из-за небрежности некоторых людей некоторые списки проводят политику предварительного ручного просмотра сообщений от не подписанных пользователей, чтобы убедиться в их целесообразности. === Как я могу подписаться? Вы можете использовать http://lists.FreeBSD.org/mailman/listinfo[web интерфейс Mailman] для подписки на любой из открытых списков рассылки. === Как мне отписаться? Вы можете использовать вышеупомянутый интерфейс или следовать инструкциям, находящимся в конце каждого письма, отправленного в этот список рассылки. Пожалуйста, не посылайте письма с отказом от подписки в сами публичные списки. Во-первых, вы так не отпишитесь, а во-вторых, вызовете раздражение подписчиков, и вероятно получите неприятные высказывания в свой адрес. Это классическая ошибка при работе со списками рассылки; старайтесь не повторять её. === Доступны ли архивы? Да. Архивы доступны http://docs.FreeBSD.org/mail/[здесь]. === Доступны ли списки рассылки в дайджест формате? Да. Посмотрите http://lists.FreeBSD.org/mailman/listinfo[web интерфейс Mailman]. [[etiquette]] == Этикет списков рассылки Участие в любом списке рассылки, как и в любом другом сообществе требует общего базиса для общения. Пожалуйста, отправляйте только подходящие сообщения и следуйте общепринятым нормам этикета. === Что я должен сделать перед отправлением письма? Вы уже сделали важный шаг, решив прочитать эту статью. Если вы новичок во FreeBSD, то сначала ознакомьтесь с программным обеспечением и связанной с нею документацией, включающей множество link:https://www.FreeBSD.org/docs/[книг и статьей]. Могут быть интересными: link:{faq}[Часто задаваемые вопросы по FreeBSD (FAQ)], link:{handbook}[Руководство по FreeBSD], и статьи link:{freebsd-questions-article}[Как работать со списком рассылки FreeBSD-questions с максимальной отдачей], link:{explaining-bsd}[Что такое BSD], и link:{new-users}[Пособие для новичков во FreeBSD]. Вы можете получить нелицеприятные высказывания в свой адрес, если зададите вопрос, ответ на который есть в приведённой выше документации. Это не потому что добровольцы, работающие над данным проектом очень плохие люди, а после многократного ответа на одни и те же вопросы - раздражение берёт своё. Это особенно справедливо, если уже существует и доступен ответ на вопрос. Не забывайте, что вся работа по улучшению FreeBSD выполняется добровольцами, и что мы только люди. === Что считается несоответствующим письмом? * Письма должны соответствовать уставу списка рассылки. * Избегайте личных оскорблений. Как хорошие жители сети, мы должны держать себя по высоким стандартам поведения. * Спам не разрешён. Нарушители данного правила будут забаненны. === Что считается хорошим этикетом при посылке писем в списки рассылки? * Пожалуйста, составляйте строки длиной примерно в 75 символов, так так не каждый использует модную почтовую программу с графическим интерфейсом. * Пожалуйста, обращайте внимание на тот факт, что пропускная способность ограничена. Не каждый читает почту через высокоскоростное соединение. Если вы отправляете содержимое какого-нибудь файла, например [.filename]#config.log# или объёмную трассировку стека, то, пожалуйста, размещайте его на каком-нибудь веб-сайте и присылайте просто ссылку на на него. Помните, что такие сообщения будут заархивированны, и это просто добавит ненужные байты к архиву. * Оформляйте ваше сообщение, чтобы оно было читабельно и ПОЖАЛУЙСТА, НЕ КРИЧИТЕ!!!!!. Не упускайте из виду эффект, которое производит плохо отформатированное письмо, причём не только в списках рассылки FreeBSD. Ваше сообщение будет просмотрено другими людьми, и если оно плохо отформатировано, имеет множество ошибок и/или восклицательных знаков, то это создаст нехорошее впечатление о вас. * Пожалуйста, используйте подходящий язык общения для конкретного списка рассылки. link:https://www.FreeBSD.org/community/mailinglists/[ Существует] много не англоязычных рассылок. + Мы понимаем, что для многих английский не родной язык и поэтому мы пытаемся сделать некие пособия. Считается плохим тоном критиковать людей не говорящих по-английски за лексические и грамматические ошибки. FreeBSD имеет отличные продвижения в этом отношении. Пожалуйста, помогайте сохранять нам эту традицию. * Пожалуйста, используйте совместимый со стандартами почтовый клиент (MUA). Много плохо отформатированных сообщений исходят от http://www.lemis.com/grog/email/email.php[неправильно работающих или плохо сконфигурированных почтовых клиентов]. Известно, что следующие почтовые программы могут посылать неправильно отформатированные сообщения без вашего ведома: ** exmh ** Microsoft(R) Exchange ** Microsoft(R) Outlook(R) + Постарайтесь не использовать MIME: многие используют программы, которые не очень хорошо работают с MIME. * Проверьте правильность настроек времени и временной зоны. Это может выглядеть немножко глупо, потому что ваши сообщения все равно будут доставляться, однако многие люди получают несколько сотен сообщений в день. Зачастую они сортируют входящие сообщения по теме и дате, и если ваше сообщение не будет предшествовать первому ответу, то они могут предположить, что оно потерялось и даже не взглянут на него. * Основной объем информации, который вы должны предоставить, представляет собой вывод программ, таких, как man:dmesg[8], или консольные сообщения, которые обычно появляются в файле [.filename]#/var/log/messages#. Не пытайтесь скопировать эту информацию, набрав ее снова; это действительно трудно, и здесь легко сделать ошибку. Чтобы послать содержимое файлов протоколов, сделайте копию файла и воспользуйтесь редактором для того, чтобы обрезать информацию, оставив только относящуюся к делу, либо скопируйте и вставьте текст в ваше сообщение. В случае вывода программ, таких, как `dmesg`, перенаправьте вывод в файл и включите его в письмо. Например, + [source,shell] .... % dmesg > /tmp/dmesg.out .... + Данная команда перенаправит информацию в файл [.filename]#/tmp/dmesg.out#. * При использовании операций копирования и вставки учтите, что некоторые такие операции отрицательно сказываются на формате строк. Особенно это стоит учесть при посылке содержимого файлов [.filename]#Makefile#, где `tab` является важным символом. Это довольно часто встречающаяся проблема в link:https://www.FreeBSD.org/support/[ базе данных сообщений об ошибках]. В [.filename]#Makefile# символы tab меняются на пробелы, или раздражающие `=3B` escape последовательности. === Каких правил этикета стоит придерживаться при ответе на уже существующее сообщение? * Пожалуйста, включайте относящийся к теме текст из исходного письма. Сокращайте его до минимума, но не переусердствуйте. Любой, кто не читал исходное сообщение должен суметь понять о чём идёт речь. + Это особенно важно для ответов, где исходное сообщение составляло сотни строчек. * Отделяйте текст исходного сообщения от текста, добавляемого вами. Чаще всего строчки исходного сообщения предваряются "`>`" и пробелом. Отделяйте ваш текст от текста исходного сообщения пустыми строчками. Эти правила помогут сделать ваши сообщения более читабельными. * Пожалуйста, убедитесь, что присваивания текста, который вы цитируйте корректны. Люди могут обидеться, если вы присвоите им слова, которые они не писали. * Пожалуйста, не пишите `ответ в начале`. Это значит, что при ответе на сообщения, вставляйте ваши ответы в конец, после текста, копируемого из исходного сообщения. + ** A: Потому что это не соответствует логическому ходу обсуждения. ** Q: Почему верхнее сообщение осуждает это? + (Спасибо Рэнди Бушу (Randy Bush) за шутку.) [[recurring]] == Повторяющиеся темы в списках рассылки Участие в списках рассылки, как и участие в любом сообществе требует общего базиса для общения. Большое количество рассылок предполагают знание истории Проекта. В частности, существует несколько тем обсуждения, которые возникают у новичков. Обязанность каждого участника не создавать дискуссии на эти темы, тем самым помочь спискам рассылки не отрываться от обсуждаемых тем и обезопасить себя от разгорячённых бесед. Лучший способ предотвратить это - ознакомиться с http://docs.FreeBSD.org/mail/[архивами списков рассылки], чтобы понять, что происходило до этого. В этом случае, незаменимым окажется http://www.FreeBSD.org/search/#mailinglists[ интерфейс поиска по спискам рассылки]. (Если этот способ не принёс результатов, воспользуйтесь вашей любимой поисковой системой). Познакомившись с архивами, вы не только будете знать какие темы обсуждались до этого, а также узнаете какие тенденции общения существуют в данной рассылке, кто является участниками и какова конечная аудитория. Эти вещи довольно хорошо знать перед отправкой письма в любую рассылку, и это касается не только списков рассылки FreeBSD. Нет сомнения, что архивы довольно объёмные и некоторые вопросы повторяются гораздо чаще чем другие, иногда в виде откликов (followups), где тема сообщения уже не соответствует новому положению дел. Тем не менее, старайтесь избегать повторяющихся тем. [[bikeshed]] == Что такое велосипедный навес ("Bikeshed")? В литературной нотации, `велосипедный навес` - это маленький внешний кожух, в который можно поместить один вид двухколёсного транспорта. Тем не менее, на языке FreeBSD, этот термин ("bikeshed") относится к темам, которые достаточно просты, и на которые (почти) каждый может предложить собственное мнение, и часто (почти) каждый его и предлагает. Детали происхождения данного термина более подробно рассмотрены link:{faq}#BIKESHED-PAINTING[здесь]. У вас должно иметься представление о данном понятии перед отправкой письма в любой список рассылки FreeBSD. Bikeshed - это тема разговора, которая будет иметь тенденцию порождать немедленные мета-дискуссии и флэйм. Пожалуйста, помогайте сохранять списки рассылки настолько полезными для многих людей, насколько это возможно путём предотвращения bikeshed. Спасибо. [[acknowledgments]] == Благодарности `{grog}`:: Первоначальный автор большинства материала по этикету списков рассылки, взятого из статьи link:{freebsd-questions-article}[Как работать со списком рассылки FreeBSD-questions с максимальной отдачей]. `{linimon}`:: Создание черновой версии данного FAQ. diff --git a/documentation/content/ru/articles/pr-guidelines/_index.adoc b/documentation/content/ru/articles/pr-guidelines/_index.adoc index 060b607e10..b2bc4aeb6a 100644 --- a/documentation/content/ru/articles/pr-guidelines/_index.adoc +++ b/documentation/content/ru/articles/pr-guidelines/_index.adoc @@ -1,573 +1,585 @@ --- title: Рекомендации по работе с сообщениями о проблемах authors: - author: Dag-Erling Smørgrav - author: Hiten Pandya releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "opengroup", "general"] --- = Рекомендации по работе с сообщениями о проблемах :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример +ifeval::["{backend}" == "html5"] include::shared/ru/mailing-lists.adoc[lines=9..-1] include::shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/ru/mailing-lists.adoc[lines=9..-1] +include::../../../../shared/ru/urls.adoc[] +endif::[] [.abstract-title] Аннотация Это руководство описывает рекомендуемую практику обработки сообщений об ошибках FreeBSD (Problem Reports - PR). Хотя эти рекомендации предназначены для Группы поддержки базы данных сообщений о проблемах FreeBSD (PR Database Maintenance Team) mailto:freebsd-bugbusters@FreeBSD.org[freebsd-bugbusters@FreeBSD.org], им должны следовать все, кто работает с этими сообщениями. ''' toc::[] [[intro]] == Введение GNATS является системой управления неисправностями (сообщениями об ошибках), которая используется в Проекте FreeBSD. Так как тщательное отслеживание заметных изъянов в программном обеспечении важно для обеспечения качества FreeBSD, правильное использование GNATS необходимо для дальнейшего развития Проекта. Доступ к GNATS даётся разработчикам FreeBSD, а также более широкому сообществу. Для того, чтобы поддерживать целостность базы данных и единства работы с пользователями, были выработаны рекомендации, покрывающие общие вопросы управления проблемами, такие, как написание отклика, обработку уже закрытых вопросов и так далее. [[pr-lifecycle]] == Жизненный цикл сообщения о проблеме * Респондент посылает PR при помощи утилиты man:send-pr[1] и получает подтверждающее сообщение. * Среднестатистический коммиттер (Вася) проявляет интерес к PR и назначает его самому себе, или другой любитель ошибок (Петя) решает, что лучше всех с описанной проблемой справится именно Вася, и назначает её Васе. * Вася связывается с Респондентом (при этом вся переписка должна фиксироваться) и выясняет причину появления проблемы. Затем он документирует причину в журнале аудита, и переводит PR в состояние "analyzed" (проанализировано). * Вася проводит бессонную ночь и выпускает патч, который, по его мнению, решает означенную проблему, и затем посылает её ответом, прося Респондента протестировать его. Затем он переводит PR в состояние "feedback". * Через несколько таких итераций Вася и Респондент удовлетворяются получающимся патчем, и Вася переносит его в дерево `-CURRENT` (или непосредственно в `-STABLE`, если этой проблемы в `-CURRENT` не наблюдается), при этом при выполнении коммита в сопутствующем сообщении делается ссылка на сообщение о проблеме (а также упоминается Респондент, если он предоставил весь или часть патча), и, если это нужно, начинается отсчёт для MFC. * Если патчу не нужно выполнение MFC, Вася закрывает PR. * Если патч требует выполнения MFC, Вася оставляет Сообщение о проблеме в состоянии "patched" до выполнения операции MFC, а затем закрывает его. [NOTE] ==== Многие PR присылаются с очень слабым описанием проблемы, а некоторые из них либо очень сложно решить, либо являются вершиной айсберга другой, более широкой проблемы; в этих случаях очень важно получить всю информацию, требуемую для решения проблемы. Если описанная проблема не может быть решена, или проявится снова, необходимо повторно открыть PR. ==== [NOTE] ==== Адрес "электронной почты" может оказаться недоступным. В этом случае ответьте на PR обычным образом и попросите Респондента (в своём сообщении) предоставить рабочий адрес электронной почты. Обычно это происходит в случаях использования man:send-pr[1] в системах с выключенной или неустановленной почтовой системой. ==== [[pr-states]] == Состояние сообщений о проблемах При выполнении некоторых действий очень важно обновлять состояние PR. Это состояние должно в точности отражать текущее состояние работы над PR. .Маленький пример того, когда именно нужно менять состояние PR [example] ==== Когда PR находится в работе и ответственный разработчик(и) удовлетворён получающимся решением, то он отвечает на PR и меняет его состояние на "feedback". В этот момент Респондент должен изучить исправление в своей ситуации и ответить, действительно ли был устранён дефект. ==== Сообщение о проблеме может находится в одном из следующих состояний: [.glosslist] open:: Начальное состояние; проблема была поставлена и её необходимо рассмотреть. analyzed:: Проблема была рассмотрена, ищется её решение. feedback:: Дальнейшая работа требует дополнительной информации от Респондента или сообщества; возможно помещение информации о предлагаемом решении. patched:: Патч был перенесён в дерево исходных текстов, но что-то (выполнение MFC или, возможно, подтверждение Респондента) ещё требуется доделать. suspended:: Работа над проблемой была остановлена из-за отсутствия информации или необходимых ресурсов. Это первый кандидат для тех, кто ищет проект для работы над ним. Если проблема вообще не может быть решена, она будет закрыта, а не приостановлена. Проект создания документации использует suspended для желательных нововведений, которые требуют значительной работы, для которой ни у кого пока нет времени. repocopy (устаревшее):: Решение проблемы зависит от завершения операции копирования репозитория (внутренние операции репозитория CVS). closed:: Сообщение о проблеме было закрыто, когда все изменения были перенесены, задокументированы и протестированы, либо когда исправление проблемы было отвергнуто. [NOTE] ==== Состояние "patched" напрямую связано с предлагаемыми решениями, так что вы можете перейти сразу к состоянию "closed", если Респондент не может протестировать патч, либо на ваших тестовых прогонах он работает. ==== [[pr-types]] == Типы сообщений о проблемах При обработке сообщений об ошибках, либо в качестве разработчика, имеющего непосредственный доступ к базе данных GNATS, либо в качестве контрибутора, который просматривает базу данных и посылает свои отклики с патчами, комментариями, пожеланиями или запросами на изменение, вы будете иметь дело с несколькими различными типами PR. * <> * <> * <> * <> * <> В последующих разделах описывается, для чего предназначены те или иные типы PR, условия отнесения PR к одному из этих типов, и какую обработку требует каждый из этих типов. [[pr-unassigned]] == Неназначенные PR По прибытии сообщениям о проблемах устанавливаются общие назначения (generic assignee). Они всегда предваряются префиксом `freebsd-`. Точное название назначения (assignee) зависит от категории и в большинстве случаев оно соответствует определенному списку рассылки FreeBSD. Далее следует текущий перечень назначений (assignee), составленный в порядке от общих к частным: [[default-assignees-common]] .Назначения по умолчанию - наиболее общие [cols="1,1,1", options="header"] |=== | Тип | Категория | Назначение по умолчанию |базовая система |bin, conf, gnu, kern, misc |freebsd-bugs |специфичные для архитектуры |alpha, amd64, arm, i386, ia64, powerpc, sparc64 |freebsd-_arch_ |коллекция портов |ports |freebsd-ports-bugs |документация, поставляемая с системой |docs |freebsd-doc |страницы сайта FreeBSD (за исключением документации) |www |freebsd-www |=== [[default-assignees-other]] .Назначения по умолчанию - остальные [cols="1,1,1", options="header"] |=== | Тип | Категория | Назначение по умолчанию |в защиту FreeBSD (advocacy efforts) |advocacy |freebsd-advocacy |проблемы с Java Virtual Machine(TM) |java |freebsd-java |соответствие стандартам |standards |freebsd-standards |тредовые библиотеки |threads |freebsd-threads |подсистема man:usb[4] |usb |freebsd-usb |=== Не удивляйтесь, если обнаружите, что автор PR присвоил ему неправильную категорию. Если вы исправите категорию, то не забудьте также подправить и назначение. (В частности, для посылающих PR является трудностью понять, что если проблема возникает на системе с архитектурой i386, то она также может быть общей для всех архитектур FreeBSD, и поэтому более подходящей будет категория `kern`. Несомненно, обратное также справедливо). Назначения некоторых PR могут быть переопределены из общих любым лицом, имеющим соответствующие привилегии. Существует несколько типов назначений: специализированные списки рассылки; почтовые алиасы (расширяемые в списки электронных адресов заинтересованных людей) и назначения отдельным лицам. Если назначением является список рассылки, пожалуйста, выполняя переназначение, используйте длинную форму (например, `freebsd-foo` вместо `foo`); благодаря этому сообщение, посылаемое в список рассылки, не будет дублироваться. [NOTE] ==== Так как список лиц добровольно согласившихся принимать назначения для некоторых типов PR изменяется часто, то наиболее подходящим местом для его размещения является http://wiki.freebsd.org/AssigningPRs[FreeBSD wiki]. ==== Ниже приведен (возможно, неполный) перечень назначений. [[common-assignees-base]] .Общие назначения - базовая система [cols="1,1,1,1", options="header"] |=== | Тип | Предполагаемая категория | Предполагаемое назначение | Тип назначения |проблема, специфичная для архитектуры ARM(R) |arm |freebsd-arm |список рассылки |проблема, специфичная для архитектуры MIPS(R) |kern |freebsd-mips |список рассылки |проблема, специфичная для архитектуры PowerPC(R) |kern |freebsd-ppc |список рассылки |проблема с Advanced Configuration and Power Management (man:acpi[4]) |kern |freebsd-acpi |список рассылки |проблема с драйверами ATM |kern |freebsd-atm |список рассылки |проблема с встраиваемой системой или минимальным дистрибутивом FreeBSD (например, NanoBSD/PicoBSD/FreeBSD-arm) |kern |freebsd-embedded |список рассылки |проблема с драйверами FireWire(R) |kern |freebsd-firewire |список рассылки |проблема в исходном коде файловой системы |kern |freebsd-fs |список рассылки |проблема с подсистемой man:geom[4] |kern |freebsd-geom |список рассылки |проблема с подсистемой man:ipfw[4] |kern |freebsd-ipfw |список рассылки |проблема с драйверами ISDN |kern |freebsd-isdn |список рассылки |подсистема man:jail[8] |kern |freebsd-jail |список рассылки |проблема с эмуляцией Linux(R) или SVR4 |kern |freebsd-emulation |список рассылки |проблема с сетевым стеком |kern |freebsd-net |список рассылки |проблема с подсистемой man:pf[4] |kern |freebsd-pf |список рассылки |проблема с подсистемой man:scsi[4] |kern |freebsd-scsi |список рассылки |проблема с звуковой подсистемой (man:sound[4]) |kern |freebsd-multimedia |список рассылки |проблема с подсистемой man:wlan[4] или с драйвером беспроводного устройства |kern |freebsd-wireless |список рассылки |проблема с man:sysinstall[8] или с man:bsdinstall[8] |bin |freebsd-sysinstall |список рассылки |проблема с системными стартовыми скриптами (man:rc[8]) |kern |freebsd-rc |список рассылки |проблемы в работе VIMAGE, VNET, или проблемы в их коде |kern |freebsd-virtualization |список рассылки |проблема с эмуляцией Xen |kern |freebsd-xen |список рассылки |=== [[common-assignees-ports]] .Общие назначения - коллекция портов [cols="1,1,1,1", options="header"] |=== | Тип | Предполагаемая категория | Предполагаемое назначение | Тип назначения |проблема с инфраструктурой системы портов (__не__ с конкретным портом!) |ports |portmgr |алиас |порт, у которого мейнтейнер apache@FreeBSD.org |ports |apache |список рассылки |порт, у которого мейнтейнер autotools@FreeBSD.org |ports |autotools |алиас |порт, у которого мейнтейнер doceng@FreeBSD.org |ports |doceng |алиас |порт, у которого мейнтейнер eclipse@FreeBSD.org |ports |freebsd-eclipse |список рассылки |порт, у которого мейнтейнер gecko@FreeBSD.org |ports |gecko |список рассылки |порт, у которого мейнтейнер gnome@FreeBSD.org |ports |gnome |список рассылки |порт, у которого мейнтейнер hamradio@FreeBSD.org |ports |hamradio |алиас |порт, у которого мейнтейнер haskell@FreeBSD.org |ports |haskell |алиас |порт, у которого мейнтейнер java@FreeBSD.org |ports |freebsd-java |список рассылки |порт, у которого мейнтейнер kde@FreeBSD.org |ports |kde |список рассылки |порт, у которого мейнтейнер mono@FreeBSD.org |ports |mono |список рассылки |порт, у которого мейнтейнер office@FreeBSD.org |ports |freebsd-office |список рассылки |порт, у которого мейнтейнер perl@FreeBSD.org |ports |perl |список рассылки |порт, у которого мейнтейнер python@FreeBSD.org |ports |freebsd-python |список рассылки |порт, у которого мейнтейнер ruby@FreeBSD.org |ports |freebsd-ruby |список рассылки |порт, у которого мейнтейнер secteam@FreeBSD.org |ports |secteam |алиас |порт, у которого мейнтейнер box@FreeBSD.org |ports |vbox |алиас |порт, у которого мейнтейнер x11@FreeBSD.org |ports |freebsd-x11 |список рассылки |=== PR для портов, у которых мейнтейнером является коммиттер порта, могут быть переназначены любым лицом (только учтите, что не каждый FreeBSD коммиттер в обязательном порядке является коммиттером портов, поэтому вы не должны судить только по почтовому адресу). Для остальных PR, пожалуйста не переназначайте их другим людям (за исключением себя), если вы не уверены, что человек действительно будет работать над ними. Это поможет избежать ситуации, когда решение проблемы игнорируется другими людьми, так как подразумевается, что некто уже над ней работает. [[common-assignees-other]] .Общие назначения - остальные [cols="1,1,1,1", options="header"] |=== | Тип | Предполагаемая категория | Предполагаемое назначение | Тип назначения |неполадки с самой GNATS(man:send-pr[1]) |bin |bugmeister |алиас |неполадки с веб интерфейсом GNATS |www |bugmeister |алиас |=== [[pr-assigned]] == Назначение PR Если в PR в заполненном поле `responsible` указано имя разработчика FreeBSD, это значит, что PR взята этим человеком для дальнейшей работы. Уже назначенное PR не должно трогаться никем, кроме администраторов GNATS (bugmeister) и того, кому эта проблема назначена. Если у вас есть комментарии, напишите отклик. Если по какой-то причине вы думаете, что PR должна изменить своё состояние или её необходимо назначить кому-то другому, пошлите сообщение тому, кто назначен ответственным. Если этот человек не ответит в течение двух недель, смените назначение PR, а дальше действуйте по своему усмотрению. [[pr-dups]] == Повторные PR Если вы обнаружите, что один и тот же вопрос описывается более чем в одном PR, выберите то, что содержит максимальный объём полезной информации и закройте все остальные, чётко указав номер более полного PR. Если несколько PR содержат не пересекающуюся информацию, перенесите всю недостающую информацию в какой-либо отклик, включая ссылки на остальные PR; затем закройте другие PR (которые теперь полностью перекрыты). [[pr-stale]] == Просроченные PR PR считается простроченным, если оно не модифицировалось в течение более полугода. При обработке просроченных PR используйте следующую процедуру: * Если PR достаточно подробна, попытайтесь воспроизвести проблему в дереве `-CURRENT` и `-STABLE`. Если вам это удалось, напишите отклик, описывающий ваши изыскания и попытайтесь найти кого-то, кому эту проблему можно назначить. Если это подходит, измените состояние на "analyzed". * Если PR описывает проблему, которая, как вы знаете, является результатом неправильного использования (некорректная настройка или что-то ещё), напишите отклик, в котором опишите, что автор исходного сделал не так, а затем закройте PR с описанием "User error" или "Configuration error". * Если в PR описывается ошибка, которая, как вы знаете, была исправлена как в `-CURRENT`, так и `-STABLE`, закройте его с сообщением, указывающим на даты исправлений в каждой ветке. * Если PR описывает ошибку, которая, по вашим данным, была исправлена в `-CURRENT`, но не в `-STABLE`, попытайтесь выяснить, когда человек, исправивший эту ошибку, планирует выполнить MFC, либо попробуйте найти для этого кого-то ещё (может, это будете вы сами?). Измените состояние сообщения на "patched" и переназначьте его кому-либо, кто будет делать MFC. * В остальных случаях запросите у автора исходного сообщения подтверждения того, что проблема всё ещё присутствует в новых версиях. Если автор не отвечает в течение месяца, закройте PR с пометкой "Feedback timeout". [[pr-misfiled]] == Незаполненные PR GNATS требовательно подходит к формату присылаемых сообщений об ошибках. Вот почему много PR заканчивают жизнь в состоянии "misfiled", если посылающий забыл заполнить поле или ввёл неправильные данные в некоторые поля PR. Этот раздел поможет предоставить основной объём необходимых подробностей для разработчиков FreeBSD, который может помочь им закрыть или повторно заполнить эти PR. Если система GNATS не может понять, что делать с сообщением об ошибке, которое достигло базы данных, она определяет `gnats-admin` в качестве ответственного за PR и помещает сообщение в категорию `pending`. Теперь это PR в состоянии "misfiled" и оно не будет появляться в списках сообщений об ошибках, если только кто-то специально не запросит перечень всех незаполненных PR. Если у вас есть доступ к машинам в кластере FreeBSD, можете воспользоваться командой `query-pr` для просмотра списка PR, которые были некорректно сформированы: [source,shell] .... % query-pr -x -q -r gnats-admin 52458 gnats-ad open serious medium Re: declaration clash f 52510 gnats-ad open serious medium Re: lots of sockets in 52557 gnats-ad open serious medium 52570 gnats-ad open serious medium Jigdo maintainer update .... Как правило, PR вроде перечисленных выше оказываются незаполненными по одной из следующих причин: * Отклик на существующее PR, посланный по электронной почте, имеет неверный формат заголовка `Subject:`. * Автор PR отправил копию (Cc:) в список рассылки, а кто-нибудь ответил на этот пост вместо сообщения, сформированного GNATS. В копии, отосланной в список рассылки, нету тега категория/PRномер. (Вот почему мы рекомендуем посылающим _не_ делать подобных движений). * При заполнении шаблона man:send-pr[1] посылающий забыл указать правильное значение для категории или класса PR. * При заполнении шаблона man:send-pr[1] посылающий установил значение поля Confidential в `yes`. (Так как мы позволяем каждому зеркалировать GNATS при помощи rsync, информация о PR-ах является общедоступной. Сообщения, касающиеся безопасности, не следует слать через GNATS, их необходимо отправлять на адрес команды офицеров безопасности). * Это не реальное PR, а какое-то случайное сообщение, посланное на адрес mailto:bug-followup@FreeBSD.org[bug-followup@FreeBSD.org] или mailto:freebsd-gnats-submit@FreeBSD.org[freebsd-gnats-submit@FreeBSD.org]. [[pr-misfiled-followups]] == Отклики неправильно оформлены как новые PR К наиболее массовой категории неправильно оформленных PR относятся те, у которых неверна тема письма, и именно они на самом деле требует самых больших усилий от разработчиков. Это не настоящие PR, описывающие отдельные ошибки. Когда по одному из адресов, который "прослушивает" GNATS на предмет обработки входящих сообщений, принимается ответ на существующее PR, то тема ответа должна быть всегда в таком виде: [.programlisting] .... Subject: Re: category/number: старая тема .... Большинство почтовых программ, когда вы отвечаете на оригинальное почтовое сообщение с PR, будут добавлять часть "`Re:`". Часть "`category/number:`" является соглашением, специфичным для GNATS, которое вы должны выполнить, вручную поставив его в тему письма с откликом. Все разработчики FreeBSD, имеющие прямой доступ к базе данных GNATS, могут регулярно проверять наличие таких PR и перемещать заинтересовавшие их в отклики к оригинальному PR (послав корректный отклик на сообщение об ошибке на адрес {bugfollowup}). Затем неправильно оформленное PR может быть закрыто с примерно таким пояснением: [.programlisting] .... Your problem report was misfiled. Please use the format "Subject: category/number: original text" when following up to older, existing PRs. I've added the relevant bits from the body of this PR to kern/12345 .... Поиск по команде `query-pr` оригинального PR, на которое отвечает неправильно оформленный отклик, легко выполняется следующим образом: [source,shell] .... % query-pr -q -y "some text" .... После того, как вы обнаружили оригинальное PR и неправильно оформленный отклик на него, воспользуйтесь параметром `-F` команды `query-pr` для сохранения полного текста всех относящихся к делу PR в файле формата почтового ящика UNIX(R), то есть: [source,shell] .... % query-pr -F 52458 52474 > mbox .... Теперь вы можете использовать любую почтовую программу для просмотра всех PR, которые вы сохранили в файле [.filename]#mbox#. Скопируйте текст всех неверно оформленных PR в отклике на оригинальное сообщение о проблеме, и обязательно включите правильный заголовок `Subject:`. После этого закройте неверно оформленное PR. Когда вы закрываете такие PR, помните, что автор получает оповещение по почте о том, что его PR сменило состояние на "closed". В пояснении обязательно описывайте в подробностях, почему это состояние изменилось. Обычно подойдёт примерно следующий текст: [.programlisting] .... Followup to ports/45364 misfiled as a new PR. This was misfiled because the subject did not have the format: Re: ports/45364: ... .... В этом случае автор неправильно оформленного PR будет знать, чего необходимо избегать при отправке отклика на существующее PR. [[pr-misfiled-format]] == Некорректные PR с отсутствующими полями Ко второму типу неправильно оформленных PR обычно относят те, что являются результатом забывчивости авторов, которые не заполнили все необходимые поля при написании первоначального PR. Отсутствие или ошибочное задание полей "category" или "class" может привести к появлению некорректного сообщения. Разработчики могут использовать man:edit-pr[1] для смены значений категории или класса этих неправильно оформленных PR на более подходящие и сохранить PR. Другой распространённой причиной появления неправильно оформленных PR являются вопросы форматирования, квотирование, изменение или удаление шаблона `send-pr`, как по вине пользователя, редактирующего шаблон, так и почтовых программ, которые проделывают странные вещи с обычными текстовыми сообщениями. Это изредка случается и может быть исправлено программой `edit-pr`, что требует некоторых усилий со стороны разработчика, корректирующего PR, однако в большинстве случаев это можно сделать относительно легко. [[pr-misfiled-notpr]] == Неправильные PR, которые на самом деле не являются сообщениями об ошибках Иногда пользователь желает сообщить об ошибке и посылает GNATS по электронной почте обычное сообщение. Скрипты GNATS работает с сообщениями об ошибках, которые форматированы при помощи шаблона man:send-pr[1]. Они не могут обрабатывать любые сообщения электронной почты. Вот почему сообщения об ошибках, посылаемые на адрес mailto:freebsd-gnats-submit@FreeBSD.org[freebsd-gnats-submit@FreeBSD.org], должны быть оформлены по шаблону команды `send-pr`, хотя сообщения по электронной почте можно послать на {freebsd-bugs}. Разработчики, которые видят PR, выглядящие так, будто они должны были быть посланы в адрес {freebsd-bugs} или какого-то другого списка рассылки, должны закрыть PR, проинформировав его автора в протоколе изменения состояния о причинах, по которых это не является настоящим PR и куда следует посылать сообщения. Электронный адрес, который использует GNATS для приёма поступающих PR, опубликован в документации к FreeBSD, объявлялся и указан на Web-сайте. Это значит, что спамеры его увидели. Спам-сообщения, достигшие GNATS, немедленно определяются в категорию "pending" и остаются там до тех пор, пока кто-нибудь их не пересмотрит. Закрытие любого из таких сообщений при помощи man:edit-pr[1] весьма раздражает, потому что GNATS отвечает автору, а адрес отправителя спам-почты никогда не бывает настоящим. Для каждого закрытого PR будут приходить сообщения о невозможности доставки. На данный момент с установкой некоторых фильтров против спама, проверяющих все добавления в базу данных GNATS, количество спама, достигающего состояния "pending", весьма мало. Все разработчики, имеющие доступ к машинам кластера FreeBSD.org, приглашаются к проверке неправильно оформленных PR и немедленному закрытию тех, что являются почтовым спамом. Когда вы закрываете такое PR, пожалуйста, сделайте следующее: * Выставьте Category в `junk`. * Установите Confidential в `no`. * Установите Responsible в `gnats-admin`. * Смените State в `closed`. Для PR категории junk не выполняется резервное копирование, следовательно, перевод спам сообщений в эту категорию обозначает, что мы не желаем хранить их или тратить дисковое пространство на них. Если вы просто закрываете их без смены категории, они остаются как в главной базе, так и во всех копиях базы, зеркалируемых через CVSup. [[references]] == Дополнительная литература Это перечень ресурсов, относящихся к качественному написанию и обработке сообщений об ошибках. Несомненно, этот список не является полным. * link:{problem-reports}[Как писать Сообщения об ошибках FreeBSD]-руководство для авторов PR. diff --git a/documentation/content/ru/articles/problem-reports/_index.adoc b/documentation/content/ru/articles/problem-reports/_index.adoc index 1f5001b51d..6c911bc0b3 100644 --- a/documentation/content/ru/articles/problem-reports/_index.adoc +++ b/documentation/content/ru/articles/problem-reports/_index.adoc @@ -1,367 +1,381 @@ --- title: Составление сообщений о проблеме во FreeBSD authors: - author: Dag-Erling Smørgrav - author: Mark Linimon releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "ibm", "intel", "sparc", "sun", "general"] --- = Составление сообщений о проблеме во FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример +ifeval::["{backend}" == "html5"] include::shared/ru/teams.adoc[] include::shared/ru/mailing-lists.adoc[] include::shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/ru/teams.adoc[] +include::../../../../shared/ru/mailing-lists.adoc[] +include::../../../../shared/ru/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/ru/teams.adoc[] +include::../../../../shared/ru/mailing-lists.adoc[] +include::../../../../shared/ru/urls.adoc[] +endif::[] [.abstract-title] Аннотация Эта статья описывает, как наилучшим образом сформулировать и отправить сообщение о проблеме в Проект FreeBSD. ''' toc::[] [[pr-intro]] == Введение Одной из самых разочаровывающих практик, которую можно получить в качестве пользователя программного обеспечения, является отправка сообщения о проблеме, которое вскоре закрывается с кратким и ничему не помогающим объяснением типа "это не проблема" или "неправильное PR". Подобным же образом одной из самых разочаровывающих практик, которую можно получить в качестве разработчика программного обеспечения, является получение массы сообщений о проблемах, которые на самом деле не являются сообщениями о проблемах, а запросами на получение поддержки, или которые содержат мало или вообще не содержат никакой информации о сути проблемы или способе ее воспроизведения. В этом документе делается попытка описать то, как составлять хорошие сообщения о проблемах. Что же, спросите вы, является хорошим сообщением о проблеме? Ну, если перейти прямо к сути, то хорошим сообщением об проблеме является то, которое может быть быстро проанализировано и отработано, к обоюдному удовлетворению как пользователя, так и разработчика. Хотя в основном статья фокусируется на сообщениях о проблемах во FreeBSD, большей частью она должна хорошо подходить и другим программным проектам. Заметьте, что эта статья организована по тематическому принципу, а не хронологически, так что вы должны прочесть документ целиком прежде, чем посылать сообщение о проблеме, и не воспринимать статью как пошаговое руководство. [[pr-when]] == Когда нужно отправлять сообщение о проблеме Имеется много классов ошибок, и не все они должны приводить к появлению сообщения о проблеме. Конечно же, нет идеальных людей, и будут моменты, когда вы решите, что нашли ошибку в программе, а на самом деле вы неправильно поняли синтаксис команды или сделали опечатку в конфигурационном файле (хотя само по себе это иногда говорит о плохой документации или неправильной обработке ошибок в прикладной программе). Есть еще много случаев, когда посылка сообщения о проблеме явно _не_ является правильным действием, а только приводит к разочарованию вас и разработчиков. И наоборот, есть случаи, когда может быть нужно послать сообщение о чем-то, не являющемся ошибкой - к примеру, запрос на доработку или расширение функциональности. Но как же определить, что является ошибкой, а что нет? Простым правилом, которому нужно следовать, является следующее - ваша проблема _не_ является ошибкой, если она формулируется как вопрос (обычно в форме "Как сделать X?" или "Где можно найти Y?"). Не всегда это так однозначно, но правило вопроса покрывает большинство случаев. Если Вам нужен ответ, лучше всего задать свой вопрос в {freebsd-questions}. Вот некоторые случаи, в которых может оказаться полезным отправить сообщение о чем-то, что не является ошибкой: * Уведомление об обновлении программного обеспечения, которое поддерживается сторонними разработчиками (в основном порты, но также и компоненты базовой системы, разрабатываемые сторонними организациями, такие, как BIND или различные утилиты GNU). + Для не поддерживаемых никем портов (переменная `MAINTAINER` содержит `ports@FreeBSD.org`), такие уведомления о обновлении будут замечены заинтересовавшимся коммиттером и вас могут попросить предоставить патч для обновления порта; предоставление патча до того, как вас попросят об этом сильно увеличит шансы того, что порт будет обновлён вовремя. + Если порт поддерживается, PR-ы, указывающие о появлении новых улучшенных (upstream) релизов обычно не очень полезны, так как они прибавляют много вспомогательной работы для коммиттеров, а мэйнтейнер наверняка уже знает о новой версии. Они уже наверняка работали с разработчиками над ней или они возможно тестируют её, чтобы убедиться в отсутствии регрессии и т.п. + В любом случае, следование процессу, описанному в link:{porters-handbook}#port-upgrading[Руководстве по созданию портов] даст наилучшие результаты. (Также можно ознакомиться с статьей link:{contributing-ports}[Контрибуция в коллекцию портов FreeBSD].) Ошибка, которую нельзя воспроизвести, вряд ли будет исправлена. Если ошибка возникла только единожды, и вы не можете ее воспроизвести, к тому же никто с ней больше не сталкивался, нет никаких шансов, что разработчики смогут ее воспроизвести или понять, что делается неправильно. Это не значит, что такого не случается, но это значит, что шансов у вашего сообщения дойти когда-либо до стадии исправления ошибки очень малы. Часто эти виды ошибок возникают из-за неудовлетворительной работы жёстких дисков, перегревшихся процессоров. Всегда, когда это возможно вы должны отслеживать такие случаи перед посылкой сообщения об ошибке. Теперь, чтобы определить кому вы должны отправить ваше сообщение об ошибке, вы должны понимать, что программное обеспечение, которое входит во FreeBSD, составляется из нескольких различных частей: * Код в базовой системе, который пишется и поддерживается контрибьюторами FreeBSD. Такой, как ядро, библиотека C, драйвера устройств (входят в категорию `kern`); утилиты (`bin`); страницы справочника и документация (`docs`); веб-страницы (`www`). Все ошибки в этих областях должны быть сообщены разработчикам FreeBSD. * Код в базовой системе, который пишется и поддерживается другим, импортируется во FreeBSD и адаптируется. Примеры включают в себя: bind, man:gcc[1] и man:sendmail[8]. Большинство ошибок, попадающие в данные области должны быть сообщены разработчикам FreeBSD, но в некоторых случаях они должны быть отправлены изначальным разработчикам, если проблемы не являются специфичными для FreeBSD. Обычно ошибки такого рода попадают под категории `bin` или `gnu`. * Отдельные приложения, не входящие в базовую систему, но являющиеся частью Коллекции Портов FreeBSD (категория `ports`). Большинство этих приложений не пишется разработчиками FreeBSD; что предоставляет FreeBSD, так это только лишь инфраструктуру для установки приложения. Следовательно, вы должны отправлять сообщение об ошибке разработчикам FreeBSD только тогда, когда вы уверены в том, что проблема специфична для FreeBSD - иначе отправляйте её авторам программного обеспечения. Затем вы должны убедиться, действительно ли проблема существует. Существует всего несколько вещей, которые раздражают разработчика больше, чем получение сообщения об ошибке, которую он уже исправил. Если проблема в базовой системе, то вам нужно сначала прочесть раздел link:{faq}#LATEST-VERSION[версии FreeBSD] из FAQ, если вы ещё не знакомы с данной темой. Для FreeBSD возможно исправлять проблемы только для некоторых недавних веток базовой системы, поэтому отправка сообщения об ошибке для более старой версии приведёт к тому, что разработчик посоветует вам обновиться до поддерживаемой версии, чтобы посмотреть присутствует ли в ней проблема. Команда офицеров безопасности поддерживает link:https://www.FreeBSD.org/security/[список поддерживаемых версий.]. Если проблема связана с портами, помните, что вы сначала должны обновиться до самой последней версии Коллекции Портов и проверить, существует ли в ней проблема. Из-за быстрых внесений изменений в эти приложения, неосуществимым для FreeBSD является поддержка чего-либо, кроме самых последних версий, и проблемы со устаревшими версиями приложений просто не могут быть исправлены. [[pr-prep]] == Подготовка Нужно следовать хорошему правилу всегда сначала выполнять дополнительные исследования перед тем, как послать сообщение о проблеме. Может быть, о вашей проблеме уже сообщено; может быть, она недавно обсуждалась или обсуждается в списках рассылки; она может быть уже исправлена в более новой версии, чем та, что вы используете. Поэтому вы должны проверить все обычные места до того, как послать ваше сообщение о проблеме. Для FreeBSD это значит: * FreeBSD link:{faq}[FAQ] (Ответы на часто задаваемые вопросы). FAQ содержит ответы на вопросы из самых разных категорий, в частности, link:{faq}#hardware[аппаратной совместимости], link:{faq}#applications[пользовательских программ] и link:{faq}#kernelconfig[конфигурации ядра]. * link:{handbook}[Списки рассылки]-если Вы не подписаны на них, воспользуйтесь http://www.FreeBSD.org/search/#mailinglists[поиском в архивах] на сайте FreeBSD. Если ваша проблема не обсуждалась в списках рассылки, вы можете попытаться опубликовать сообщение о ней и подождать несколько дней, пока кто-нибудь не сможет увидеть то, что вы не заметили. * Как вариант, весь веб-используйте вашу любимую поисковую систему для поиска каких-либо ссылок по вашей проблеме. Вы можете даже увидеть ссылки на архивы списков рассылки или телеконференций, о которых вы не знали или не думали там искать. * Следующим пунктом должна быть http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[ база данных PR FreeBSD] (GNATS). Если только ваша проблема не нова или редка, есть некоторый шанс, что о ней уже сообщено. * И самое важное, вы должны посмотреть не затрагивает ли документация в базовой системе вашу проблему. + Для основного кода FreeBSD вы должны тщательно изучить содержимое файла [.filename]#/usr/src/UPDATING# или его текущую версию по адресу http://svnweb.freebsd.org/base/head/UPDATING?view=log[http://svnweb.freebsd.org/base/head/UPDATING?view=log]. (Если вы переходите с одной версии на другую, особенно если вы обновляетесь до FreeBSD-CURRENT, то в этом файле вы можете найти много важной информации). + Если же ваша проблема связана с коллекцией портов FreeBSD, вы должны обратиться к файлу [.filename]#/usr/ports/UPDATING# (изменения, касающиеся индивидуальных портов) или к [.filename]#/usr/ports/CHANGES# (изменения, касающиеся всей коллекции портов). Они также доступны через интерфейс svnweb: http://svnweb.freebsd.org/ports/head/UPDATING?view=log[http://svnweb.freebsd.org/ports/head/UPDATING?view=log] и http://svnweb.freebsd.org/ports/head/CHANGES?view=log[http://svnweb.freebsd.org/ports/head/CHANGES?view=log]. [[pr-writing]] == Написание сообщения о проблеме Теперь, после того, как вы решили, что ваш вопрос подпадает под категорию сообщения о проблеме, и это проблема FreeBSD, самое время написать собственно сообщение о проблеме (PR). Прежде чем мы углубимся в частности использования программы для создания и отправки PR, вот несколько советов, которые помогут вам сделать PR более эффективным. == Как писать хорошие сообщения о проблемах * Основным языком общения разработчиков FreeBSD является английский. База данных по проблемам также ведется на английском. Если вы испытываете проблемы с формулировкой описания проблемы по-английски, свяжитесь со своими соотечественниками, которые помогут вам составить PR. + * _Не оставляйте поле "Synopsis" (краткое описание) пустым._ Сообщения о проблемах попадают как в списки рассылки, которые затем расходятся по всему миру (в них поле "Synopsis" определяет тему письма), так и в базу данных. Просматривающий эту базу, как правило, пройдет мимо PR с пустым кратким описанием. Не забудьте, что PR остается в базе до тех пор, пока кто-либо не закроет его; сообщение-аноним, скорее всего, просто потеряется на общем фоне. * __Избегайте туманных описаний в поле "Synopsis"__. Не стоит предполагать, что читающий ваше сообщение владеет контекстом; поэтому, чем подробнее вы опишете ситуацию, тем лучше. В частности, к какой части системы относится ваша проблема? Проявляется ли она на этапе установки или во время нормальной работы? Например, вместо строки `Synopsis: portupgrade is broken` следовало бы написать что-то вроде `Synopsis: port ports-mgmt/portupgrade coredumps on -current`. В случае портированных приложений в поле "Synopsis" полезно указывать не только имя порта, но и категорию. * _Если у вас есть готовый патч, скажите об этом._ PR, содержащий патч, имеет куда больше шансов быть рассмотренным. В этом случае добавьте строку `[patch]` (включая квадратные скобки) в начало поля "Synopsis" (хотя использование именно этой формы необязательно, она является стандартом де-факто). * _Если вы отвечаете за исходные тексты, сообщите об этом._ Если вы отвечаете за часть исходных текстов (например, порт), вы можете добавить в начало поля "Synopsis" строку `[maintainer update]` (включая квадратные скобки), а также установить класс вашего PR (поле "Class") в `maintainer-update`. В этом случае коммиттеру, обрабатывающему ваш PR, не придётся лишний раз проверять. * _Будьте точны в формулировках._ Чем больше информации вы можете предоставить о проблеме, тем больше у вас шансов получить ответ. ** Включите информацию о версии FreeBSD, которую вы используйте (существует специальное поле для его включения, смотрите ниже) и на какой архитектуре. Сообщите, используете ли вы release версию (установили с компакт-диска либо загрузили) или скачали её с помощью Subversion (и если так, то сообщите номер ревизии). Если вы используете FreeBSD-CURRENT, то первый вопрос, который вам могут задать, будет про номер ревизии, так как исправления для этой ветки (особенно в случае серьёзных проблем) имеют тенденцию появляться слишком быстро. ** Включите информацию о том, какие глобальные опции вы указали в [.filename]#make.conf#. На заметку: Объявление опций наподобие `-02` и других, описанных в man:gcc[1] во многих случаях может быть причиной ошибок. Хотя и разработчики FreeBSD будут принимать патчи, у них не будет желания исследовать такие случаи из-за отсутствия времени и добровольцев, и вместо этого они могут ответить, что это не поддерживается. ** Если проблему можно легко повторить, включите необходимую информацию, чтобы разработчик смог воспроизвести ее самостоятельно. Если проблема проявляется при некоторых вводимых данных, то, по возможности, приведите их вместе с получаемым и ожидаемым выводом. Если же вводимых данных много или же их нельзя разглашать, то попробуйте выделить из них лишь небольшой фрагмент, приводящий к возникновению проблемы, и включите его в PR. ** Если ваша проблема связана с ядром, будьте готовы предоставить следующую информацию (вам не обязательно включать её всю, она пойдёт лишь на заполнение базы данных, но вы должны включить информацию, которая по вашему мнению актуальна): *** Вашу конфигурацию ядра, включая то, какие устройства у вас установлены *** Включены ли у вас опции отладки (например, `WITNESS`), и если так, то существует ли проблема после изменения значения этой опции *** Полный вывод обратной трассировки (backtrace), паники или иного консольного вывода, или же записи из [.filename]#/var/log/messages#, если они были сгенерированы *** Вывод команды `pciconf -l`, а также соответствующие части вывода `dmesg`, в случае, если проблема связана с конкретным оборудованием *** Прочли ли вы [.filename]#src/UPDATING#, описана ли там ваша проблема (кто-нибудь спросит обязательно) *** Запускается ли другое ядро (это для тех случаев, когда причиной сбоя стало оборудование, например отказывающие винчестеры или перегревшиеся процессоры, что может маскировать проблемы ядра) ** Если же ваша проблема связана с портами, то предоставьте следующую информацию (вам не обязательно включать её всю, она пойдет лишь на заполнение базы данных, но вы должны включить информацию, которая по вашему мнению актуальна): *** Какие порты вы устанавливали *** Имеются ли какие-либо переменные окружения, которые переписывают первоначально-установленные в [.filename]#bsd.port.mk#, такие как, `PORTSDIR`) *** Прочли ли вы [.filename]#ports/UPDATING#, и описана ли там ваша проблема (кто-нибудь спросит обязательно) * _Избегайте нечетких запросов о новых возможностях._ Сообщение типа "кто-то обязательно должен сделать так, чтобы такая-то утилита вела себя так-то" имеет куда меньше шансов встретить позитивный отклик, чем более четко сформулированный запрос. Помните, что исходные тексты доступны всем, так что если вам нужна реализация какого-то нового свойства, лучший способ- взяться за работу самому! Не забудьте также, что такие моменты лучше обсуждать в списках рассылки, таких как `freebsd-questions`, чем делать это посредством базы данных PR. * _Убедитесь, что ваша проблема еще никем не описана._ Мы уже говорили об этом, но стоит повториться. Потратьте пару минут на составление запросов к базе PR: http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query]. (Несмотря на повторы, об этом постоянно забывают) * _Сообщайте об одной проблеме в одном PR._ Избегайте описания двух и более проблем в одном сообщении (исключением являются взаимосвязанные проблемы). Оформляя патчи, не пытайтесь в них добавлять множество функциональных возможностей или исправлять ими несколько ошибок в одном и том же сообщении о проблеме (опять же, за исключением взаимосвязанных проблем) - для таких PR-ов потребуется значительно больше времени на обработку. * _Избегайте полемики._ Если ваше сообщение касается области или способов реализации, которые ранее вызвали разногласия, вам стоит быть готовым предоставить не только патчи, но и внятные аргументы, почему следует поступать именно так (то есть, это "Правильный Путь"). Как отмечалось выше, аккуратный поиск по архиву списков рассылки http://www.FreeBSD.org/search/#mailinglists[http://www.FreeBSD.org/search#mailinglists] никогда не помешает. * _Будьте вежливы._ Почти каждый из тех, кто может заниматься вашим сообщением, является добровольцем. Никому не понравятся указания, как и что делать, когда он и так занимается этим, да еще и по каким-либо причинам, отличным от финансовых. Вообще говоря, этого подхода следует придерживаться, имея дело с любым проектом с Открытыми Исходными текстами (Open Source). == Прежде всего Если вы используйте утилиту man:send-pr[1] проверьте, что переменная вашего окружения `VISUAL` (или `EDITOR`, если `VISUAL` не задана) задана подходящим образом. Следует также проверить работоспособность системы электронной почты. Утилита man:send-pr[1] использует почтовую систему для отправки и отслеживания сообщения о проблеме. Если с машины, на которой вы запускаете man:send-pr[1], нельзя отправить почту, сообщение не попадёт в базу данных GNATS. О настройке электронной почты во FreeBSD можно прочитать в главе "Электронная почта" Руководства по FreeBSD по адресу link:{handbook}#mail[Electronic Mail]. Убедитесь, что ваш почтовый клиент не исказит сообщение по пути в GNATS. В частности, если ваш почтовый клиент автоматически переносит строки, изменяет символы табуляции на пробелы или предотвращает интерпретацию символов новой строки, любой патч, который вы пришлёте окажется непригодным. Для текста мы хотели бы, чтобы вы делали строчки размером примерно в 70 символов для читабельности PR на веб странице. Примерные соображения должны учитываться при отправке сообщения об ошибке через link:https://www.FreeBSD.org/send-pr/[веб-форму] вместо man:send-pr[1]. Помните, что операции копирования-вставки могут иметь сторонние эффекты в форматировании текста. В определённых случаях может быть необходимо использовать man:uuencode[1] для гарантии того, что патчи придут не изменёнными. И наконец, если ваше сообщение будет объёмным, вы должны приготовить его в offline, чтобы ничего не потерялось в случае, если будет проблема при его отправке. Это особенно касается link:https://www.FreeBSD.org/send-pr/[веб-формы]. == Вложение патчей или файлов Нижеследующее применимо к передаче сообщения о проблеме посредством электронной почты: Программа man:send-pr[1] предусматривает присоединение файлов к сообщению о проблеме. Вы можете вложить сколько угодно файлов, но каждый с уникальным именем (имеется в виду имя файла без маршрута). Просто используйте параметр командной строки `-a` для задания имен файлов, которые вы хотите присоединить: [source,shell] .... % send-pr -a /var/run/dmesg -a /tmp/errors .... Не беспокойтесь о бинарных файлах, они будут автоматически перекодированы для того, чтобы не повредить работе вашей почтовой программы. Если вы вкладываете патч, обязательно используйте параметр `-c` или `-u` вместе с командой man:diff[1] для создания контекстного или унифицированного diff-файла (унифицированный формат предпочтителен), и обязательно укажите точные номера SVN ревизий файлов, которые вы изменяли, чтобы разработчики, которые будут читать ваше сообщение, смогли легко его применить. Для проблем, связанных с ядром или с базовыми утилитами, предпочтительнее будет патч относительно ветки FreeBSD-CURRENT (или Subversion-ветки HEAD), так как весь новый код должен быть сначала протестирован в ней. После завершения тестирования код будет интегрирован в ветвь FreeBSD-STABLE. Если вы вставляете патч в тело сообщения, учтите, что некоторые почтовые программы имеют тенденцию заменять табуляции серией пробелов, что полностью разрушит, например, часть файла сборки (Makefile). Не отсылайте патчи в виде вложений, используя `Content-Transfer-Encoding: quoted-printable`. Это выполнит экранирование (escaping) символов и весь патч будет бесполезным. Следует также заметить, что включение небольших патчей в сообщение о проблеме является приемлемой практикой, в особенности если они решают проблему, описанную в сообщении, большие же патчи, а в особенности новый код, который может требовать значительного просмотра перед тем, как он будет внесен в дерево исходных текстов, должны быть размещены на web- или ftp-сервере, а в сообщение о проблеме должен быть включён только URL указывающий на этот патч. Очень часто патчи, пересылаемые по электронной почте, а в особенности если задействована GNATS, бывают искажены, и, как следствие, чем больше патч, тем труднее будет для заинтересованных людей привести его к нормальному виду. Также то, что патч будет размещён отдельно от сообщения о проблеме, даёт возможность изменять его не отсылая полный патч в дополнение к изначальному сообщению о проблеме. И наконец, большие патчи просто увеличивают размер базы данных, так как закрытые сообщения об ошибках на самом деле не удаляются, а сохраняются и помечаются, как `closed`. Вы должны также помнить, что пока вы явно не укажете обратного в вашем сообщении о проблеме или в самих патчах, будет предполагаться, что они подпадают под те же условия лицензирования, что и оригинальный файл, измененный вами. == Заполнение шаблона Следующие несколько абзацев применимы только к способу подачи PR через электронную почту: После запуска утилиты man:send-pr[1] вам будет представлен шаблон сообщения о проблеме. Шаблон состоит из списка полей, некоторые из которых уже заполнены, а некоторые содержат комментарии, объясняющие назначение поля или перечисляющие подходящие значения. Не беспокойтесь о комментариях; они будут автоматически удалены, если вы их не изменяли (или удалите их сами). Вверху шаблона, ниже строк `SEND-PR:` находятся заголовки почтового сообщения. Вам обычно не нужно их изменять, если только вы не посылаете сообщение о проблеме с машины или от учетной записи, которая может посылать, но не может получать электронную почту, в случае чего вы можете задать в полях `From:` и `Reply-To:` ваши реальные адреса электронной почты. Вы можете также послать самому себе (или кому-то еще) копию сообщения о проблеме, добавив один или большее количество адресов к заголовку `Cc:`. В шаблоне вы найдете два однострочных поля: * _Submitter-Id:_ Не меняйте его. Значение по умолчанию `current-users` правильно, даже если вы используете FreeBSD-STABLE. * _Confidential:_ Предварительно заполнено как `no`, его изменение не имеет значения, так как нет такого понятия, как конфиденциальное сообщение о проблеме - база данных PR распространяется по всему миру. Далее описаны общие поля для почтового и link:https://www.FreeBSD.org/send-pr/[веб интерфейса]: * _Originator:_ Пожалуйста, укажите ваше реальное имя, за которым опционально следует адрес вашей электронной почты в угловых скобках. Обычно, man:send-pr[1] заполняет поле Originator содержимым поля `gecos` из учетной записи текущего пользователя. + [NOTE] ==== Предоставленный вами адрес электронной почты станет публичной информацией и может стать доступным спамерам. Поэтому совсем не лишними будут меры по борьбе со спамом на вашей стороне, или же можно воспользоваться временным адресом электронной почты. Однако, если вы укажете несуществующий почтовый адрес, то у нас не будет возможности уточнять детали по вашему PR. ==== * _Organization:_ Все, что вы захотите здесь указать. Это поле не содержит значительной информации. * _Synopsis:_ Заполняется кратким и точным описанием проблемы. Краткое описание используется в качестве темы сообщения электронной почты о проблеме, и используется при выдаче списков и выборках сообщений о проблемах; сообщения о проблемах с непонятными краткими описаниями чаще всего игнорируются. + Повторим: если к вашему сообщению о проблеме приложен патч, то, пожалуйста, начните краткое описание с `[patch]` (включая квадратные скобки); если PR принадлежит к категории ports и вы являетесь его мейнтейнером, то начните описание с `[maintainer update]` (включая квадратные скобки) и установите класс проблемы (поле "Class") в `maintainer-update`. * _Severity:_ Одно из `non-critical`, `serious` или `critical`. Не переусердствуйте; избегайте пометки вашей проблемы как `critical`, если только это не действительно критичная проблема (повреждение данных, существенная потеря функциональности в -CURRENT), или `serious`, если только это не касается многих пользователей (паники ядра, блокировки (freezes), проблемы с конкретными драйверами устройств или с системными утилитами). Разработчики FreeBSD не обязательно будут работать над вашей проблемой быстрее, если вы установите слишком высокий уровень важности, т.к. существует много других людей, которые сделали тоже самое - некоторые разработчики всё же уделят этому полю немного внимания и перейдут к следующему сообщению именно из-за этого поля. + [NOTE] ==== Большинство проблем с безопасностью _не_ следует отправлять в GNATS, потому что вся эта информация становится публичной. Пожалуйста, направляйте подобные отчеты на электронный адрес `{security-officer}`. ==== * _Priority:_ Одно из `low`, `medium` или `high`. `high` должен использоваться для проблем, которые затронут конкретно каждого пользователя FreeBSD, а `medium` для чего-то, что затронет многих пользователей. + [NOTE] ==== Ввиду массовых злоупотреблений это поле потеряло свое значение. ==== * _Category:_ Выберите соответствующую категорию. + Первым делом необходимо решить, к какой части системы относится ваша проблема. Помните: FreeBSD - завершенная операционная система, которая устанавливает ядро, стандартные библиотеки, множество драйверов периферийного оборудования, а также - большой набор системных утилит ("базовая система"). В дополнение к этому, в коллекции портов имеются тысячи приложений. Следовательно, определитесь: обнаруженная вами проблема находится в базовой системе или в чем-то, установленным через коллекцию портов. + Вот описание основных категорий: ** Если проблема в ядре, в библиотеках (таких как стандартная библиотека С `libc`) или в драйвере из базовой системы, то используйте категорию `kern`. (Есть несколько исключений, описанных ниже). В общем, это всё, что описано в разделах 2, 3 или 4 справочника. ** Если проблема с бинарной программой, например с man:sh[1] или man:mount[8], то вам прежде всего необходимо определить принадлежность программы к базовой системе или к установке из коллекции портов. Если вы не уверены, выполните команду `whereis _имя программы_`. В FreeBSD для коллекции портов существует договоренность: установка ведется в [.filename]#/usr/local#, однако это может быть переопределено системным администратором. Для таких программ следует использовать категорию `ports` (даже если категория порта `www`; см. ниже). Если программа располагается в [.filename]#/bin#, [.filename]#/usr/bin#, [.filename]#/sbin# или в [.filename]#/usr/sbin#, то это часть базовой системы, и вам следует использовать категорию `bin`. (Несколько программ, например man:gcc[1], на самом деле используют категорию `gnu`, но не беспокойтесь об этом сейчас.) Программы этой категории описаны в разделах 1 и 8 справочной системы. ** Если вы уверены, что в стартовых скриптах `(rc)` или в каком-то ином неисполняемом конфигурационном файле присутствует ошибка, тогда верной категорией будет `conf` (configuration). Эти сущности описываются в разделе 5 справочной системы. ** Если вы нашли проблему в наборе документации (статьи, книги, страницы справочной системы), правильным выбором будет `docs`. ** Если вы наблюдаете проблему на страницах http://www.FreeBSD.org[сайта FreeBSD], то правильным выбором будет `www`. + [NOTE] ==== Если проблема с чем-то из порта, называемого `www/_someportname_`, то она все же принадлежит к категории `ports`. ==== + Далее представлены более специализированные категории. ** Если проблема принадлежит к `kern`, но в то же время имеет дело с подсистемой USB, то правильным выбором будет `usb`. ** Если проблема принадлежит к `kern` и найдена в потоковых библиотеках, правильным выбором будет `threads`. ** Если проблема принадлежит к базовой системе и касается соблюдения стандартов, таких как POSIX(R), правильным выбором будет `standards`. ** Если проблема связана с ошибками внутри Java Virtual Machine(TM) (JVM(TM)), даже если Java(TM) была установлена из коллекции портов, вам следует выбрать категорию `java`. Более общие проблемы с портами Java(TM) попадают под категорию `ports`. + Далее перечислены остальные категории. ** Если вы уверены, что проблема проявляется только на используемой вами процессорной архитектуре, выберите одну из архитектурно-специфичных категорий: это `i386` для Intel-совместимых машин в 32-битном режиме; `amd64` для AMD машин в 64-битном режиме (сюда также входят Intel-совместимые машины работающие в режиме EMT64); и менее распространенные `arm`, `ia64`, `powerpc` и `sparc64`. + [NOTE] ==== Люди часто ошибаются в выборе категории. Если вы не уверены в правильности выбора, то лучше не гадать, а выбрать `misc`. ==== + .Правильное использование категории [example] ==== У вас простой ПК, и вы подозреваете, что столкнулись с проблемой, специфичной для конкретного чипсета или материнской платы: верная категория - `i386`. ==== + .Неправильное использование категории [example] ==== Если вы наблюдаете проблему с периферийной картой расширения на распространенной шине или неполадки с конкретного типа жестким диском: в этом случае возможно, что неисправность наблюдается на более чем одной архитектуре, и верным выбором будет `kern`. ==== ** Если вы не знаете в чем проблема (или вам кажется, что описание не попадает ни под какую из вышеобозначенных), используйте категорию `misc`. Перед тем, как написать PR, можно для начала спросить помощи в {freebsd-questions}. Возможно, там вам подскажут, какую из существующих категорий следует выбрать. + Вот текущий перечень категорий (взят из http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories[http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories]): ** `advocacy:` проблемы, связанные с общественным мнением о FreeBSD. Вышло из употребления. ** `amd64:` проблемы, специфичные для платформы AMD64. ** `arm:` проблемы, специфичные для платформы ARM. ** `bin:` проблемы с пользовательскими программами из базовой системы. ** `conf:` проблемы с файлами настройки, используемыми по умолчанию значениями и прочее. ** `docs:` проблемы со страницами справочной системы или онлайновой документацией. ** `gnu:` проблемы с портированным программным обеспечением GNU, таким как man:gcc[1] или man:grep[1]. ** `i386:` проблемы, специфичные для платформы i386(TM). ** `ia64:` проблемы, специфичные для платформы ia64. ** `java:` проблемы, связанные с виртуальной машиной Java(TM). ** `kern:` проблемы с ядром или с библиотеками в базовой системе, или с драйверами устройств, не связанными с какой-либо конкретной платформой. ** `misc:` все, что не подпадает ни под какую другую категорию. (Надо отметить, что нет почти ничего, чтобы действительно соответствовало этой категории, за исключением проблем с релизами и с инфраструктурой сборки. Временные отказы при построении ветки `HEAD` не принадлежат к данной категории. Также надо отметить, что проблемы этой категории имеют тенденцию теряться легче всего). ** `ports:` проблемы, связанные с коллекцией портов. ** `powerpc:` проблемы, специфичные для платформы PowerPC(R). ** `sparc64:` проблемы, специфичные для платформы Sparc64(R). ** `standards:` проблемы, связанные с соответствием стандартам. ** `threads:` проблемы, касающиеся реализации тредов во FreeBSD (особенно во FreeBSD-CURRENT). ** `usb:` проблемы, относящиеся к реализации USB во FreeBSD. ** `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]: Как только вы заполните шаблон, сохраните его и выйдете из редактора, man:send-pr[1] запросит вас `s)end, e)dit or a)bort?`. Вы можете нажать `s` для продолжения и отправки сообщения о проблеме, `e` для повторного запуска редактора и выполнения дальнейших изменений, или `a` для отказа от вашего сообщения. Если вы выберете последнее, то ваше сообщение о проблеме останется на диске (man:send-pr[1] укажет вам имя файла перед завершением работы), так что вы сможете отредактировать его на свой вкус или передать в систему с лучшим подключением к сети, перед тем, как послать его при помощи параметра `-F` программы man:send-pr[1]: [source,shell] .... % send-pr -f ~/my-problem-report .... При этом будет прочитан указанный файл, будет проверено содержимое, убраны комментарии и сообщение будет отослано. Если вы используете link:https://www.FreeBSD.org/send-pr/[веб форму]: Перед нажатием `submit` вам потребуется заполнить проверочное поле текстом, представленным на картинке рядом. Эта непопулярная мера была принята в связи со злоупотреблениями со стороны роботов и некоторых неверно сориентированных индивидуумов. Это необходимая мера, которая никому не нравится, и, пожалуйста, не просите нас убрать её. Отметим, что вам `настоятельно рекомендуется` сохранить вашу работу (PR) куда-нибудь перед нажатием кнопки `submit`. Распространенная пользовательская ошибка: отображение браузером устаревшей проверочной картинки из его кэша. Если это произойдет в вашем случае, ваше сообщение будет отвергнуто и ваши труды пропадут. Если по какой-либо причине вы не имеете возможности видеть проверочную картинку, а также не можете воспользоваться man:send-pr[1], пожалуйста примите наши извинения за неудобства и пришлите ваш PR электронной почтой команде mailto:freebsd-bugbusters@FreeBSD.org[freebsd-bugbusters@FreeBSD.org]. [[pr-followup]] == Отслеживание После того, как ваше сообщение будет принято, вы получите по электронной почте уведомление, в котором будет указан номер для отслеживания, который был назначен вашему сообщению о проблеме и URL, который вы можете использовать для проверки его состояния. В случае удачи кто-нибудь проявит интерес к вашей проблеме и попытается ее решить, или, как это бывает, описать, почему это не является проблемой. Вы будете автоматически оповещаться о любом изменении состояния и получать копии всех комментариев или патчей, которые будут присоединяться в процессе отработки вашего сообщения о проблеме. Если кто-то запросит дополнительную информацию от вас, или вы вспомните или обнаружите нечто, что не указали в начальном сообщении, пожалуйста пошлите ваше дополнение (отклик) с помощью одного из этих способов: * Самый простой путь это использовать соответствующую ссылку (followup) на индивидуальной веб страничке сообщения об ошибки, к которой можно перейти, используя http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query[страничку поиска PR]. Кликнув на этой ссылке откроется окно для отправки email с уже корректно заполненными полями To: и Subject: (если ваш браузер сконфигурирован для этого). * Или просто пошлите письмо на адрес {bugfollowup}, включив отслеживаемый номер в теме письма, чтобы система отслеживания сообщений могла знать, к какому сообщению о проблеме его присоединить. + [NOTE] ==== Если вы _не_ включите отслеживаемый номер, GNATS растеряется и создаст совершенно новое PR, которое будет закреплено за администратором GNATS. В результате ваш отклик затеряется до тех пор пока кто-нибудь не начнёт разгребать скопившийся мусор, что может произойти спустя дни или даже недели. Неправильно: [.programlisting] .... Subject: that PR I sent .... Правильно: [.programlisting] .... Subject: Re: ports/12345: compilation problem with foo/bar .... ==== Если сообщение о проблеме остается открытым после того, как проблема была решена, просто отправьте сообщение (так, как это описано выше), с указанием, что сообщение о проблеме может быть закрыто, и если это возможно, объясните, как и когда проблема была устранена. [[pr-problems]] == Проблемы взаимодействия с GNATS Большинство PR проходят сквозь систему и принимаются быстро; однако, во время загруженности GNATS, подтверждение на ваше сообщение о проблеме может задержаться на 10 и более минут. Пожалуйста, сохраняйте спокойствие. Помимо всего прочего, так как GNATS получает все данные через электронную почту, становится понятным, почему FreeBSD пропускает все сообщения через спамфильтры. Если подтверждение не приходит на протяжении часа-двух, то, возможно, что ваше сообщение попало под них; если так, то, пожалуйста, свяжитесь с администраторами GNATS по адресу mailto:bugmeister@FreeBSD.org[bugmeister@FreeBSD.org] и попросите помощи. [NOTE] ==== Среди антиспам мер есть одна, которая сопоставляет сообщения с множеством злоупотреблений, наблюдаемых в электронной почте с HTML-форматированием текста (однако, сюда не относится простое включение HTML в PR). Мы настоятельно рекомендуем не использовать HTML-форматированный текст при посылке PR: не только из-за вероятности попадания в спамфильтры, но и из-за загромождения базы данных. Отдайте предпочтение простому старому текстовому формату. ==== В редких случаях вы можете столкнуться с ошибкой GNATS, когда PR принят и ему присвоен номер, но он не отображается в списках PR ни на одной из страниц веб поиска PR. Вероятно, что рассинхронизировался индекс базы с самой базой. Этот случай можно проверить, обратившись к страничке http://www.FreeBSD.org/cgi/query-pr.cgi[Query PR Database] и проконтролировав наличие вашего PR. Если он есть, пожалуйста, известите администраторов GNATS (mailto:bugmeister@FreeBSD.org[bugmeister@FreeBSD.org]). Следует отметить, что перестройка базы выполняется периодически по `cron`, и если вам не к спеху, то не предпринимайте никаких шагов. [[pr-further]] == Дополнительная литература Это список информационных ресурсов, относящихся к правильному написанию и обработке сообщений о проблемах. Он, без сомнения, не полон. * http://www.chiark.greenend.org.uk/~sgtatham/bugs.html[How to Report Bugs Effectively]-прекрасное эссе, которое написал Simon G. Tatham о составлении полезных (не специфичных для FreeBSD) сообщений о проблемах. * link:{pr-guidelines}[Problem Report Handling Guidelines]-интересный взгляд на обработку сообщений о проблемах самими разработчиками FreeBSD. diff --git a/documentation/content/ru/articles/releng/_index.adoc b/documentation/content/ru/articles/releng/_index.adoc index 513eac6829..c7c58fdd8e 100644 --- a/documentation/content/ru/articles/releng/_index.adoc +++ b/documentation/content/ru/articles/releng/_index.adoc @@ -1,413 +1,422 @@ --- title: Подготовка релизов FreeBSD authors: - author: Murray Stokely email: murray@FreeBSD.org webpage: https://people.FreeBSD.org/~murray/ releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "cvsup", "intel", "general"] --- = Подготовка релизов FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :xrefstyle: full :toc-title: Содержание :part-signifier: Часть :chapter-signifier: Глава :appendix-caption: Приложение :table-caption: Таблица :figure-caption: Рисунок :example-caption: Пример +ifeval::["{backend}" == "html5"] include::shared/authors.adoc[] include::shared/releases.adoc[] include::shared/ru/teams.adoc[] include::shared/ru/mailing-lists.adoc[] include::shared/ru/urls.adoc[] - -ifeval::["{backend}" == "html5"] :imagesdir: ../../../images/articles/releng/ endif::[] ifeval::["{backend}" == "pdf"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/releases.adoc[] +include::../../../../shared/ru/teams.adoc[] +include::../../../../shared/ru/mailing-lists.adoc[] +include::../../../../shared/ru/urls.adoc[] :imagesdir: ../../../../static/images/articles/releng/ endif::[] ifeval::["{backend}" == "epub3"] +include::../../../../shared/authors.adoc[] +include::../../../../shared/releases.adoc[] +include::../../../../shared/ru/teams.adoc[] +include::../../../../shared/ru/mailing-lists.adoc[] +include::../../../../shared/ru/urls.adoc[] :imagesdir: ../../../../static/images/articles/releng/ endif::[] [.abstract-title] Аннотация В этой статье описывается подход, который используется группой подготовки релизов FreeBSD для создания качественных версий Операционной Системы FreeBSD. В ней детально описывается методология, используемая для официальных релизов FreeBSD и рассказывается об инструментах, доступных тем, кто интересуется созданием модифицированных релизов FreeBSD для тиражирования внутри организации или в коммерческих целях. ''' toc::[] [[introduction]] == Введение Разработка FreeBSD представляет собой весьма открытый процесс. FreeBSD составляется в результате общих усилий тысяч людей по всему миру. Проект FreeBSD предоставляет анонимный публичный доступ по протоколу CVS[1], так что любой может получить доступ к журналу изменений, разницам (патчам) между ветками разработки и другим продвинутым возможностям, которые даёт строгое управление исходным кодом. Это сильно помогает в привлечении к FreeBSD всё большего количества талантливых разработчиков. Однако, и я думаю, что все со мной согласятся, наступит хаос, если доступ по записи будет открыт всем в Internet. Поэтому только "избранная" группа примерно из 300 человек имеет доступ по записи в CVS-хранилище. Эти _коммиттеры[5]_ отвечают в целом за разработку FreeBSD. Выбираемая из самых заслуженных разработчиков _группа правления[6]_ обеспечивает некоторый уровень управления проектом. Темп разработок, ведущихся во `FreeBSD`, оставляет мало времени на тщательную доводку системы до качества продуктивного релиза. Для решения этой проблемы разработка ведётся в два параллельных потока. Основной веткой разработки является __HEAD__, она же _основная линия_ нашего дерева CVS, известная также под именем "FreeBSD-CURRENT" или, для краткости, "-CURRENT". Поддерживается и более стабильная ветка, известная как "FreeBSD-STABLE" или, для краткости, "-STABLE". Обе ветки находятся в основном CVS-хранилище в Калифорнии и реплицируются при помощи CVSup[2] на зеркала по всему миру. FreeBSD-CURRENT[7] является "передним краем" работ над FreeBSD, через который попадают все изменения в системе. FreeBSD-STABLE является веткой разработки, из которой создаются основные релизы. В эту ветку изменения попадают разными путями, и предполагается, что сначала они попали в FreeBSD-CURRENT, где были тщательно протестированы сообществом наших пользователей. В промежутке между релизами машинами Проекта FreeBSD, выделенными для построения системы, ежемесячно автоматически собираются снэпшоты, которые доступны для закачки по адресу `ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/`. Общедоступность снэпшотов бинарных релизов, а также желание сообщества наших пользователей отслеживать работу над -STABLE при помощи CVSup и "`make world`"[7] помогает поддержать весьма хорошее качество FreeBSD-STABLE, даже до выполнения мероприятий проверки качества, предваряющих выпуск основных релизов. В процессе выпуска релиза пользователи постоянно присылают сообщения об ошибках и пожелания по расширению функциональности. Сообщения о проблемах попадают в нашу базу данных GNATS[8] по электронной почте, посредством утилиты man:send-pr[1] или через Web-интерфейс, доступный по адресу http://www.FreeBSD.org/send-pr/[http://www.FreeBSD.org/send-pr/]. Для удовлетворения наших самых консервативно настроенных пользователей, начиная с FreeBSD 4.3, появились ветки для отдельных релизов. Эти ветки создаются вскоре после того, как выпускается окончательный релиз. После его выхода в ветку релиза помещаются только самые критичные исправления и добавления, касающиеся безопасности. Кроме обновлений исходных текстов посредством CVS, для систем веток RELENG_``__X_Y__`` имеются и бинарные наборы патчей. === Что обсуждается в данном документе? В последующих главах этой статьи обсуждаются: <>:: Различные этапы процесса подготовки релиза вплоть до построения актуальной системы. <>:: Процесс сборки. <>:: Как базовый релиз может быть расширен третьими сторонами. <>:: Некоторые из уроков, полученных при выпуске релиза FreeBSD 4.4. <>:: Направления будущих работ. [[release-proc]] == Процесс выпуска релиза Новые релизы FreeBSD выпускаются из ветки -STABLE с интервалом примерно в четыре месяца. Процесс выпуска релизов FreeBSD начинается за 45 дней до предполагаемой даты релиза с того, что ответственный за релиз посылает сообщение по электронной почте в адрес списков рассылки для разработчиков, чтобы напомнить последним о наличии всего лишь 15 дней на внесение новых изменений до момента заморозки кода. В этот период многие разработчики выполняют действия, известные как "MFC-переносы". MFC означает "Merge From CURRENT" (перенос из CURRENT) и описывает процесс переноса протестированных изменений из нашего дерева разработки -CURRENT в наше дерево -STABLE. === Просмотр кода За тридцать дней до предполагаемого релиза хранилище исходных текстов переводится в режим "стабилизации кода". В этот период все изменения в дереве -STABLE должны подтверждаться `{re}`. В первый 15-дневный период разрешены следующие типы изменений: * Исправления ошибок. * Обновление документации. * Исправления любого характера, касающиеся безопасности. * Незначительные исправления в драйверах устройств, такие, как, например, добавление новых ID устройств. * Любые другие изменения, которые одобряет группа подготовки релиза, с учётом потенциального риска. После первых 15 дней стабилизации кода выпускается __предварительный релиз__, предназначенный для широкого тестирования, а код переводится в состояние "заморозки", когда становится гораздо труднее доказывать необходимость внесения новых изменений в систему, если они не касаются исправления серьёзных ошибок или информационной безопасности. Во время заморозки кода каждую неделю выпускается не менее одной предварительной версии релиза, до тех пор, пока не будет готов окончательный вариант релиза. В дни, предшествующие выпуску окончательного релиза, группа его подготовки работает в постоянном контакте со службой безопасности и людьми, поддерживающими документацию и порты, чтобы обеспечить доступность всех компонентов, необходимых для успешного выпуска релиза. === Контрольный список для проверки окончательного релиза После того, как для широкого тестирования было выпущено несколько предварительных релизов и все основные проблемы были решены, может начаться процесс "шлифовки" окончательного релиза. [[rel-branch]] ==== Создание ветки релиза Как сказано во вводной части, ветка `RELENG_X_Y` является сравнительно новым добавлением в нашей методологии подготовки релизов. Первым шагом в создании этой ветки является проверка того, что вы работаете с самой последней версией исходных текстов `RELENG_X`, из _которой_ вы хотите создать новую ветку. [source,shell] .... /usr/src# cvs update -rRELENG_4 -P -d .... Следующим шагом является создание _тэга_ точки ответвления, чтобы диффы облегчили работу с началом ветки в CVS: [source,shell] .... /usr/src# cvs rtag -rRELENG_4 RELENG_4_8_BP src .... После этого создаётся тэг новой ветки по команде: [source,shell] .... /usr/src# cvs rtag -b -rRELENG_4_8_BP RELENG_4_8 src .... [NOTE] ==== __Использование тэгов `RELENG_*` разрешено только менеджерам CVS и участникам группы по выпуску релизов.__ ==== "_Тэгом_ " в понятии CVS называют метку, которая идентифицирует исходный текст в некоторый момент времени. Вводя тэг в дерево, мы обеспечиваем то, что в будущем тот, кто строит релиз, всегда сможет воспользоваться тем же самым кодом, что использовался нами для создания официальных релизов Проекта FreeBSD. image::branches-head.png[Ветви разработки FreeBSD] image::branches-releng3.png[Ветка FreeBSD 3.x STABLE] image::branches-releng4.png[Ветка FreeBSD 4.x STABLE] image::branches-releng5.png[Ветка FreeBSD 5.x STABLE] image::branches-releng6.png[Ветка FreeBSD 6.x STABLE] image::branches-releng7.png[Ветка FreeBSD 7.x STABLE] image::branches-releng8.png[Ветка FreeBSD 8.x STABLE] image::branches-releng9.png[Ветка FreeBSD 9.x STABLE] [[versionbump]] ==== Увеличение номера версии Перед тем, как окончательный релиз будет помечен, построен и выпущен, необходимо модифицировать следующие файлы, отразив в них корректную версию FreeBSD: * [.filename]#doc/ru_RU.KOI8-R/books/handbook/mirrors/chapter.xml# * [.filename]#doc/en_US.ISO8859-1/books/porters-handbook/book.xml# * [.filename]#doc/shared/xml/freebsd.ent# * [.filename]#src/Makefile.inc1# * [.filename]#src/UPDATING# * [.filename]#src/gnu/usr.bin/groff/tmac/mdoc.local# * [.filename]#src/release/Makefile# * [.filename]#src/release/doc/en_US.ISO8859-1/shared/xml/release.dsl# * [.filename]#src/release/doc/shared/examples/Makefile.relnotesng# * [.filename]#src/release/doc/shared/xml/release.ent# * [.filename]#src/shared/examples/cvsup/standard-supfile# * [.filename]#src/sys/conf/newvers.sh# * [.filename]#src/sys/sys/param.h# * [.filename]#src/usr.sbin/pkg_install/add/main.c# * [.filename]#www/en/docs/man.xml# * [.filename]#www/en/cgi/ports.cgi# * [.filename]#ports/Tools/scripts/release/config# Новый релиз должен быть также отражён в файлах замечаний к релизу и информации о замеченных ошибках (в ветке релиза), а файлы соответствующим образом обрезаны (в ветке stable/current): * [.filename]#src/release/doc/en_US.ISO8859-1/relnotes/common/new.xml# * [.filename]#src/release/doc/en_US.ISO8859-1/errata/article.xml# Утилита Sysinstall должна быть обновлена и указывать количество доступных портов и объём дискового пространства, требуемого для Коллекции Портов[4]. На данный момент эта информация хранится в файле [.filename]#src/usr.sbin/sysinstall/dist.c#. После построения релиза для оповещения мирового сообщества о выпуске релиза необходимо обновить некоторые файлы. * [.filename]#doc/shared/images/articles/releng/branches-relengX.pic# * [.filename]#www/shared/xml/advisories.xml# * [.filename]#www/shared/xml/includes.release.xml# * [.filename]#www/shared/xml/includes.release.xsl# * [.filename]#www/en/releases/*# * [.filename]#www/en/releng/index.xml# * [.filename]#www/en/news/news.xml# * [.filename]#www/en/search/web.atoz# * [.filename]#src/shared/misc/bsd-family-tree# [[versionbump-major]] ==== Подготовка новой старшей релиз ветки (RELENG_X) Когда новая старшая релиз ветка, такая как `RELENG_6` ответвляется из HEAD, некоторые дополнительные файлы должны быть обновлены перед тем, как релизы будут созданы из этой новой ветки. * [.filename]#src/shared/examples/cvsup/stable-supfile# - когда применимо, должен быть обновлен, чтобы указывать на новую -STABLE ветку. ==== Создание тэгов релиза При готовности окончательного релиза следующая команда создаст тэг `RELENG_4_8_0_RELEASE`. [source,shell] .... /usr/src# cvs rtag -rRELENG_4_8 RELENG_4_8_0_RELEASE src .... Менеджеры документации и портов отвечают за внесение тэга в соответствующие ветки с тэгом `RELEASE_4_8_0`. Иногда в последний момент, уже _после_ создания последних тэгов может потребоваться внесение исправлений. На практике это не является проблемой, так как CVS позволяет выполнять манипуляции с тэгами по команде `cvs tag -d _tagname filename_`. Очень важно, чтобы все последние изменения были помечены соответствующим тэгом, как часть релиза. Релизы FreeBSD должны быть всегда повторяемыми. Локальные изменения в параметры окружения выпускающего релиз недопустимы. [[release-build]] == Построение релизов "Релизы" FreeBSD могут быть построены любым человеком, имеющим быстродействующую машину и доступ к хранилищу исходных текстов. (Это должен быть любой, так как мы предоставляем анонимный доступ к CVS! Обратитесь к Руководству для прояснения деталей.) _Единственным_ особым требованием является наличие устройства man:md[4]. Если устройство в вашем ядре не подгружено, то модуль ядра должен быть подгружен автоматически при выполнении команды man:mdconfig[8] на этапе создания носителя для загрузки. Все инструменты, необходимые для построения релиза, доступны из хранилища CVS в каталоге [.filename]#src/release#. Эти инструменты предоставляют единый метод построения релизов FreeBSD. Полный релиз может быть реально построен при помощи лишь одной команды, включая создание ISO-образов, подходящих для записи на CDROM, установочных дискет и установочного каталога FTP. Эта команда называется соответствующим образом: `make release`. === `make release` Для успешного построения релиза вы должны сначала заполнить каталог [.filename]#/usr/obj#, запустив команду `make world` или просто `make buildworld`. Цель, выполняемая для построения релиза, требует корректного задания нескольких переменных, используемых при его сборке: * `CHROOTDIR` - Каталог, используемый в среде с изменённой корневой файловой системой при построении полного релиза. * `BUILDNAME` - Наименование строящегося релиза. * `CVSROOT` - Местонахождение CVS-хранилища. * `RELEASETAG` - Тэг CVS, соответствующий релизу, который вы собираетесь строить. Если у вас ещё нет доступа к локальному CVS-хранилищу, то вы можете зеркалировать одно из них при помощи link:{handbook}#CVSUP[CVSup]. Поставляемый sup-файл, [.filename]#/usr/shared/examples/cvsup/cvs-supfile#, может служить хорошей отправной точкой для зеркалирования хранилища CVS. Если `RELEASETAG` опущен, то релиз будет строиться из ветки `HEAD` (известной как -CURRENT). Релизы, строящиеся из этой ветки обычно называют "снэпшотами -CURRENT". Для настройки построения релиза существует много других переменных Большинство из этих переменных описаны в начале файла [.filename]#src/release/Makefile#. Точная команда, служащая для построения официального релиза FreeBSD 4.7 (x86) такова: [source,shell] .... make release CHROOTDIR=/local3/release \ BUILDNAME=4.7-RELEASE \ CVSROOT=/host/cvs/usr/home/ncvs \ RELEASETAG=RELENG_4_7_0_RELEASE .... [.filename]#Makefile# для релиза может быть разбит на несколько различных шагов. * Создание чистого системного окружения в отдельной иерархии каталогов по команде "`make installworld`". * Выгрузка из CVS чистой версии исходных текстов системы, документации и портов в иерархию для построения релиза. * Создание копии [.filename]#/etc# и [.filename]#/dev# в окружении с изменённым корнем файловой системы. * Смена корневой файловой системы на иерархию построения релиза, чтобы избежать влияния внешнего окружения на построение. * Выполнение `make world` в окружении с изменённой корневой файловой системой. * Построение бинарных файлов для работы с Kerberos. * Построение ядра [.filename]#GENERIC#. * Создание промежуточного дерева каталогов, где будут строиться бинарные файлы и формироваться дистрибутивы. * Построение и установка инструментов для работы с документацией, необходимых для преобразования исходных текстов документации (SGML) в формат HTML и текстовые документы, которые сопутствуют релиз. * Построение и установка актуальной документации (руководства пользователей, учебники, замечания к релизу, перечень аппаратной совместимости и так далее.) * Построение "свёрнутых" бинарных файлов, используемых на установочных дискетах. * Подготовка дистрибутивных архивов бинарных файлов и исходных текстов. * Создание загрузочного носителя и "fixit"-дискеты. * Создание иерархии для установки при помощи FTP. * _(опционально)_ Создание образов ISO для носителей CDROM/DVD. Для получения более полной информации об инфраструктуре построения релизов, пожалуйста, обратитесь к справочной странице по man:release[7]. [NOTE] ==== Важно, чтобы из файла [.filename]#/etc/make.conf# были удалены все установки, специфичные для конкретного хоста. К примеру, будет глупо распространять бинарные файлы, построенные на системе с переменной `CPUTYPE`, указывающей на определённый тип процессора. ==== === Программное обеспечение третьих лиц ("ports") http://www.FreeBSD.org/ports[Коллекция портов FreeBSD] содержит более {numports} программных пакетов сторонних разработчиков, которые доступны для FreeBSD. За поддержку целостности дерева портов, которое может использоваться для создания бинарных пакетов, поставляемых с официальными релизами FreeBSD, отвечает `{portmgr}`. Рассмотрение работ с нашей коллекцией пакетов сторонних разработчиков при подготовке релизов выходит за рамки этого документа. Этот вопрос глубоко рассмотрен в отдельной статье, link:{releng-packages}[The Release Engineering of Third Party Packages]. === ISO с релизами Начиная с FreeBSD 4.4, Проект FreeBSD принял решение распространять все четыре образа ISO, ранее продаваемые через _BSDi/Wind River Systems/FreeBSD Mall_ как "официальные" дистрибутивы на CDROM. Каждый из четырёх дисков должен содержать файл [.filename]#README.TXT#, описывающий содержимое диска, файл [.filename]#CDROM.INF#, в котором находятся мета-данные о диске для того, чтобы man:sysinstall[8] мог проверять и использовать содержимое, а также файл [.filename]#filename.txt#, содержащий перечень содержимого на диске. Этот _перечень_ может быть создан простой командой: [source,shell] .... /stage/cdrom# find . -type f | sed -e 's/^\.\///' | sort > filename.txt .... Специфичные требования для каждого CD описываются ниже. ==== Диск 1 Первый диск практически полностью создаётся командой `make release`. Единственным изменением, которое нужно внести в каталог [.filename]#disc1#, является добавление подкаталога [.filename]#tools#, а также перенос максимально возможного количества программных пакетов сторонних разработчиков, которые поместятся на диск. Каталог [.filename]#tools# содержит программное обеспечение, позволяющее пользователям создавать установочные дискеты из других операционных систем. Этот диск нужно сделать загрузочным, чтобы пользователям современных ПК не нужно было создавать установочные дискеты. Если в релиз необходимо включить специализированное ядро, то необходимо модифицировать man:sysinstall[8] и man:release[7], добавив в них инструкции по установке. Соответствующий код находится в [.filename]#src/release# и [.filename]#src/usr.sbin/sysinstall#. В частности, в [.filename]#src/usr.sbin/sysinstall# необходимо будет редактировать [.filename]#src/release/Makefile#, [.filename]#dist.c#, [.filename]#dist.h#, [.filename]#menus.c#, [.filename]#install.c# и [.filename]#Makefile#. Также может потребоваться обновить [.filename]#sysinstall.8#. ==== Диск 2 Второй диск также в основном создаётся по команде `make release`. Он содержит "живую файловую систему", которую можно использовать из man:sysinstall[8] для исправления процесса установки FreeBSD. Этот диск должен быть загрузочным и содержать также упакованную копию хранилища CVS в каталоге [.filename]#CVSROOT# и демонстрационные версии коммерческого программного обеспечения в каталоге [.filename]#commerce#. ==== Диски 3 и 4 Оставшиеся два диска содержат дополнительные программные пакеты для FreeBSD. Они должны быть объединены в группы (кластеры), чтобы отдельный пакет и все его _зависимости_ находились на одном и том же диске. Дополнительная информация о создании этих дисков находится в статье link:{releng-package}[The Release Engineering of Third Party Packages]. ==== Поддержка нескольких дисков Sysinstall поддерживает установку пакетов с нескольких дисков. Для это нужно, чтобы на каждом диске был файл [.filename]#INDEX#, содержащий названия всех пакетов со всех дисков, с дополнительным полем, указывающем на каком диске содержится данный конкретный пакет. Также, на каждом диске, в файле [.filename]#cdrom.inf# должна быть указана переменная `CD_VOLUME` для того, чтобы sysinstall мог определить какой этой диск. Когда пользователь будет пытаться установить пакет, которого нет на текущем диске, sysinstall выдаст запрос на вставку соответствующего диска. [[distribution]] == Распространение [[dist-ftp]] === Серверы FTP После того, как релиз был тщательно протестирован и подготовлен к распространению, должен быть обновлён главный FTP-сервер. Все официальные общедоступные серверы FTP-серверы FreeBSD являются зеркалами главного сервера, открытого только другим серверам FTP. Этот сервер известен под именем `ftp-master`. Когда релиз готов, на сервере `ftp-master` должны быть изменены следующие строки: [.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/#:: Установочный каталог FTP, получаемый по команде `make release`. [.filename]#/pub/FreeBSD/ports/arch/packages-X.Y-release/#:: Полный комплект построенных пакетов для этого релиза. [.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/tools#:: Символическая ссылка на [.filename]#../../../tools#. [.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/packages#:: Символическая ссылка на [.filename]#../../../ports/arch/packages-X.Y-release#. [.filename]#/pub/FreeBSD/releases/arch/ISO-IMAGES/X.Y/X.Y-RELEASE-arch-*.iso#:: ISO-образы. Здесь "*" это [.filename]#disc1#, [.filename]#disc2# и так далее. Только если здесь есть [.filename]#disc1# и альтернативный первый установочный CD (например, обрезанная установка без оконной системы), то здесь может быть также и [.filename]#mini#. Для получения дополнительной информации о системе зеркальных FTP-серверов FreeBSD, пожалуйста, прочтите статью о link:{hubs}[Зеркалировании FreeBSD]. Может пройти от нескольких часов до двух дней между тем, как обновится `ftp-master`, и на основной массе FTP-серверов 1-го уровня появится новое программное обеспечение, в зависимости от того, в тоже самое ли время пакет был загружен. Обязательно, чтобы выпускающие релиз координировали свои действия с {mirror-announce} до того, как объявлять об общедоступности нового программного обеспечения с серверов FTP. В идеальном случае набор пакетов к релизу должен быть загружен по крайней мере за четыре дня до момента выпуска релиза. Релиз должен быть загружен в промежутке от 24 до 48 часов до момента выхода запланированного релиза с выключенными полномочиями "other". Это позволит зеркалирующим серверам сгрузить его, но никто не сможет получить его с зеркальных серверов. В момент выхода релиза должно быть послано сообщение в адрес {mirror-announce}, говорящее о том, что релиз выпущен и наступило время для открытия доступа на зеркальных серверах. Обязательно вместе со временем укажите и часовой пояс, например, относительно GMT. [[dist-cdrom]] === Тиражирование CD-ROM Вскоре появится: Советы по передаче ISO-образов FreeBSD на тиражирование и применяемые меры по контролю качества. [[extensibility]] == Расширяемость Хотя FreeBSD представляет собой законченную операционную систему, ничего не заставляет вас использовать систему только в том виде, который приготовлен нами для распространения. Мы попытались спроектировать систему максимально расширяемой, чтобы она могла выполнять роль платформы, на основе которой можно строить другие коммерческие продукты. Единственным "правилом", которое мы налагаем, является настоятельная рекомендация документировать улучшения, вносимые вами в дистрибутив FreeBSD с нетривиальными изменениями! Сообщество FreeBSD может помогать только пользователям того программного обеспечения, которое распространяем мы. Мы определённо приветствуем улучшения в форме, например, инструментов установки и администрирования, но не можем отвечать на вопросы о них. === Создание модифицированных загрузочных дискет Во многих местах имеются сложные условия, которые требуют размещения дополнительных модулей ядра или пользовательских инструментов на установочные дискеты. "Быстрым и неаккуратным" способом сделать это является изменение промежуточного каталога в существующей иерархии при выполнении `make release`: * Примените патчи или добавьте дополнительные файлы в каталог построения релиза с изменённых корнем файловой системы. * `rm ${CHROOTDIR}/usr/obj/usr/src/release/release.[59]` * перестройте man:sysinstall[8], ядро и остальные части системы, которые коснулись ваши изменения. * `chroot ${CHROOTDIR} ./mk floppies` Дискеты нового релиза будут находиться в [.filename]#${CHROOTDIR}/R/stage/floppies#. Либо может быть вызвана цель [.filename]#boot.flp# построения или скрипт создания файловой системы, [.filename]#src/release/scripts/doFS.sh#, которые может быть вызван напрямую. Локальные патчи могут быть также приложены к построению релиза при помощи задания переменной `LOCAL_PATCH` при выполнении `make release`. === Скрипты `sysinstall` Инструмент установки и настройки системы FreeBSD, man:sysinstall[8], может работать по сценарию, полезному для автоматизированной установки в больших компаниях. Эта функциональность может использоваться совместно с технологией Intel(R) PXE[12] для первоначальной установки систем из сети, или с модифицированными загрузочными дискетами со скриптами sysinstall. Пример скрипта для sysinstall доступен в дереве CVS в виде файла [.filename]#src/release/sysinstall/install.cfg#. [[lessons-learned]] == Уроки, извлечённые из FreeBSD 4.4 Формально процесс подготовки релиза для 4.4 начался 1 августа 2001 года. После этой даты все без исключения изменения в ветке `RELENG_4` FreeBSD подтверждались `{re}`. Первый предварительный релиз для архитектуры x86 был выпущен 16 августа, за ним выходило ещё 4 предварительных релиза, и всё закончилось 18 августа выпуском окончательного релиза. Руководитель службы безопасности очень плотно занимался процессом выпуска в последнюю неделю, так как в предыдущих предварительных релизах были найдены проблемы, касающиеся информационной безопасности. Чуть более чем за месяц в адрес `{re}` поступило более _500_ писем. Сообщество наших пользователей весьма чётко показало, что безопасность и стабильность релиза FreeBSD не должна приноситься в жертву любым назначенным срокам окончания работ или планируемым датам выхода релиза. Проект FreeBSD за время своего существования значительно вырос, и никогда ранее необходимость в стандартизации процедур подготовки релизов не стояла так остро. Это стало ещё более важно, когда FreeBSD была перенесена на новые аппаратные платформы. [[future]] == Направления будущих работ Нашим работам по подготовке релизов жизненно важно расти вместе с увеличением количества пользователей системы. Вместе с этим мы очень плотно работаем над документированием действий, выполняемых при выпуске релизов FreeBSD. * _Параллелизм_ - некоторые этапы построения релиза на самом деле выполнять параллельно "затруднительно". Большинство выполняемых задач весьма интенсивно работают с I/O, так что для ускорения процесса `make release` наличие нескольких высокоскоростных дисков гораздо более важно, чем использование нескольких процессоров. Если для различных иерархий в man:chroot[2]-окружении используется несколько дисков, то извлечение из CVS деревьев [.filename]#ports# и [.filename]#doc# может выполняться одновременно с командой `make world` на другом диске. Использование `RAID`-решений (аппаратных или программных) может значительно сократить общее время построения. * _Кроссплатформенное построение релизов_ - Построить релиз для IA-64 или Alpha на x86-оборудовании? `make TARGET=ia64 release`. * _Тестирование_ - Нам нужна улучшенная автоматизированная система тестирования корректности для FreeBSD. * _Инструменты установки_ - Наша программа установки давно пережила свой век. В разработке находятся несколько проектов, которые должны дать улучшенную технологию установки. Одним из таких проектов был libh, целью которого было создание новой интеллектуальной технологии работы с пакетами и программы установки с GUI. [[ackno]] == Благодарности Я рад поблагодарить Джордана Хаббарда (Jordan Hubbard) за то, что он дал мне возможность взять под свою ответственность некоторые части процесса подготовки релиза FreeBSD 4.4, а также за все годы его работы, сделавшие FreeBSD такой, какой она является сейчас. Конечно, релиз не был бы возможен без той работы, которую проделали `{asami}`, `{steve}`, `{bmah}`, `{nik}`, `{obrien}`, `{kris}`, `{jhb}` и остальные члены сообщества разработчиков FreeBSD. Я также рад выразить благодарность `{rgrimes}` и `{phk}`, а также остальным, работавшим над инструментами подготовки релизов в первые годы существования FreeBSD. Эта статья была также написана под впечатлением документации по подготовке релизов от CSRG[13], NetBSD Project[10] и замечаний Джона Балдвина (John Baldwin) по предлагаемому процессу подготовки релизов[11]. [[biblio]] == Справочная литература (1) CVS - Concurrent Versions System http://www.cvshome.org[http://www.cvshome.org] (2) CVSup - The CVS-Optimized General Purpose Network File Distribution System http://www.polstra.com/projects/freeware/CVSup[http://www.polstra.com/projects/freeware/CVSup] (3) http://pointyhat.FreeBSD.org[http://pointyhat.FreeBSD.org] (4) Коллекция портов FreeBSD http://www.FreeBSD.org/ports[http://www.FreeBSD.org/ports] (5) link:{contributors}#staff-committers[Коммиттеры FreeBSD] (6) Правление FreeBSD link:https://www.FreeBSD.org/administration/#t-core[https://www.FreeBSD.org/administration/#t-core] (7) link:{handbook}[Руководство FreeBSD] (8) GNATS: The GNU Bug Tracking System http://www.gnu.org/software/gnats[http://www.gnu.org/software/gnats] (9) Статистика FreeBSD PR FreeBSD PR Statistics http://www.FreeBSD.org/prstats/[http://www.FreeBSD.org/prstats/] (10) NetBSD Developer Documentation: Release Engineering http://www.NetBSD.org/developers/releng/index.html[http://www.NetBSD.org/developers/releng/index.html] (11) John Baldwin's FreeBSD Release Engineering Proposal http://people.FreeBSD.org/\~jhb/docs/releng.txt[http://people.FreeBSD.org/~jhb/docs/releng.txt] (12) PXE Jumpstart Guide link:{pxe}[PXE Guide] (13) Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: http://docs.FreeBSD.org/44doc/papers/releng.html[The Release Engineering of 4.3BSD]