Справочник коммиттера

1. Административные детали

Для авторизации на машины проекта вы должны использовать протоколы ssh(1) или telnet(1) с включенным Kerberos 5. В случае ssh(1), допустим только протокол версии 2. Эти протоколы являются значительно более защищенными по сравнению с telnet(1) или rlogin(1), поскольку информация об авторизации передается в зашифрованном виде. По умолчанию, протокол ssh(1) также шифрует весь трафик. Учитывая наличие таких утилит, как ssh-agent(1) и scp(1), протокол ssh(1) значительно удобнее прочих в использовании. Если вы ничего не знаете об ssh(1), загляните в раздел Разд. 9.

2. Типы коммит битов

CVS Репозиторий FreeBSD состоит из нескольких разделов, охватывающих исходные тексты базовой операционной системы, документацию, инфраструктуру построения внешних приложений (портов), а также различные служебные утилиты. Право записи в репозиторий (''коммит бит'') подразумевает указание области дерева, в которое оно может быть применено. Как правило, области напрямую связаны с группой, подтвердившей право коммиттера на бит. В дальнейшем, область действия коммит бита может быть расширена; в этом случае, коммиттер должен следовать стандартным правилам нового для коммиттера в данной области, в частности, получая подтверждения на каждый коммит и, возможно, в течение какого-то времени работу с ментором.

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

Вне зависимости от области приложения усилий, запросы коммиттеров на рассмотрение предлагаемых изменений в процессе разработки могут только приветствоваться.

3. Работа с CVS

Подразумевается, что вы уже имеете опыт базовой работы с CVS.

Администраторы Главного CVS Репозитория <cvsadm@FreeBSD.org> являются ''владельцами'' репозитория CVS и ответственны за все прямые его изменения (в целях чистки или исправления каких-либо вопиющих ошибок коммиттеров при работе с CVS). Если в результате ваших действий с частью репозитория произошел несчастный случай, например, после неверной операции cvs import или cvs tag, пошлите письмо соответствующей подгруппе Администраторы Главного CVS Репозитория <cvsadm@FreeBSD.org> (см. следующую таблицу) и сообщите о проблеме. В наиболее серьезных случаях, касающихся не только какой-либо части репозитория, а дерева CVS в целом, вы можете написать Администраторы Главного CVS Репозитория <cvsadm@FreeBSD.org>. Пожалуйста, не надо писать группе Администраторы Главного CVS Репозитория <cvsadm@FreeBSD.org> по поводу репозиторного копирования и прочих вопросов, которые может решить соответствующая подгруппа.

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

Дерево CVS в настоящее время разделено на четыре независимых репозитория: doc, ports, projects и src. Для удобства работы пользователей при распространении через CVSup различные деревья комбинируются в одно, с одним служебным каталогом CVSROOT.

В настоящее время, все репозитории CVS располагаются на одной машине, ncvs.FreeBSD.org, однако, для обеспечения возможности в будущем разнести их по физически различным машинам, для каждой поддерживается отдельное имя хоста. Их и следует использовать коммиттерам. Наконец, каждый репозиторий расположен в отдельном каталоге. В итоге, общая картина выглядит так:

Операции с CVS производятся удаленно, путем установки переменной окружения CVSROOT (она должна указывать на соответствующий хост и каталог верхнего уровня, например ncvs.FreeBSD.org:/home/ncvs) и последующего выполнения команд выгрузки и коммита. Многие коммиттеры определяют команды-синонимы, разворачивающиеся в запуск cvs с правильными параметрами. В частности, пользователи оболочки tcsh(1) могут добавить следующие строки в свой скрипт начальной загрузки .cshrc:

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 следует использовать команду Xcvs commit. Если вам нужно добавить в проект что-либо совершенно новое (например, исходные тексты сторонних разработчиков), нужно использовать команду cvs import; обратитесь к странице справочника по cvs(1) за подробностями.

Если вам нужно использовать команды CVS add и delete, так чтобы в реальности переместить часть исходных текстов подобно действию команды mv(1), нужно запросить операцию ''репозиторного копирования'' (repository copy). При этом кто-либо из CVS-мастеров скопирует необходимые файлы внутри репозитория на нужное место и даст вам знать об этом. Репозиторное копирование производится для сохранения истории (журналов изменения). Возможность отследить историю изменений очень ценна для всего проекта FreeBSD.

Документация по CVS, учебные материалы и FAQ можно найти по адресу: http://www.cvshome.org/docs/. Очень полезна также книга Карла Фогеля (Karl Fogel) Open Source Development with CVS. Некоторая полезная информация о CVS на русском языке может быть найдена здесь.

Dag-Erling C. Smørgrav <des@FreeBSD.org> написал такой ''мини-пример'' работы с CVS:

1. Извлечение нужного модуля из репозитория: команда co или checkout.

   % cvs checkout shazam

   Эта команда извлечет копию модуля shazam. Если модуль с таким именем не существует (не описан в файле modules), будет произведена попытка извлечь директорию верхнего уровня shazam.

   Таблица 2. Полезные опции команды cvs checkout

   -P	Не создавать (точнее, удалить после завершения выполнения) пустые каталоги
   -l	Извлекать один уровень каталогов (без подкаталогов)
   -rrev	Извлечь ревизию, ветвь или тег rev для указанного модуля
   -Ddate	Извлечь состояние модуля в репозитории на момент date

   Примеры в применении к FreeBSD:

   • Извлечь модуль miscfs, расположенный в каталоге репозитория src/sys/miscfs:

     % cvs co miscfs

     После выполнения вы получите каталог miscfs, содержащий подкаталоги CVS, deadfs, devfs и т.д. Один из них (linprocfs) будет пустым.

   • Извлечь те же файлы, но с полным путем:

     % cvs co src/sys/miscfs

     Теперь у вас есть каталог src, содержащий подкаталоги CVS и sys. Каталог src/sys содержит подкаталоги CVS и miscfs и т.д.

   • Извлечь те же файлы, удалив при этом пустые подкаталоги:

     % cvs co -P miscfs

     Вы получите каталог miscfs с подкаталогами CVS, deadfs, devfs... однако без подкаталога linprocfs, поскольку он не содержит файлов.

   • Извлечь каталог miscfs без подкаталогов:

     % cvs co -l miscfs

     Теперь в каталоге miscfs будет только один подкаталог CVS.

   • Извлечь модуль miscfs из ветви 6.X:

     % cvs co -rRELENG_6 miscfs

     Теперь вы можете изменить исходные тексты и произвести коммит в эту ветвь.

   • Извлечь модуль miscfs по состоянию на момент выхода 6.0-RELEASE:

     % cvs co -rRELENG_6_0_0_RELEASE miscfs

     В этом случае вы не сможете внести изменения в репозиторий, поскольку RELENG_6_0_0_RELEASE описывает момент времени, а не ветвь разработки.

   • Извлечь модуль miscfs по состоянию на 15 января 2000 г:

     % cvs co -D'01/15/2000' miscfs

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

   • Извлечь модуль miscfs, каким он был неделю назад:

     % cvs co -D'last week' miscfs

     И вновь, изменения не могут быть записаны.

   Обратите внимание, что мета-данные хранятся в подкаталогах CVS.

   Аргументы опций -D and -r сохраняются (являются ''клейкими'', sticky), например, при последующем использовании команды cvs update.

2. Проверка состояния извлеченных файлов: команда status.

   % cvs status shazam

   Эта команда покажет статус файла shazam или каждого файла в директории shazam. Для каждого из файлов статус может быть одним из:

   Up-to-date	Файл соответствует репозиторию и не модифицировался
   Needs Patch	Файл не изменялся, но репозиторий содержит обновленную версию
   Locally Modified	Файл соответствует репозиторию, но был изменен локально
   Needs Merge	Файл изменен локально; вместе с тем, файл изменен и в репозитории
   File had conflicts on merge	После последнего обновления возникли конфликты, и они все еще не устранены

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

3. Обновление извлеченного модуля: команда update.

   % cvs update shazam

   Эта команда обновит состояние файла shazam или файлов в каталоге shazam до наиболее свежих версий выбранной вами при извлечении ветви. Если выбирался ''момент времени'', не произойдет ничего, если только за истекшее время в репозитории не был перемещен тег или не произошло чего-нибудь еще непредвиденного.

   Полезные опции в дополнение к уже описанным для команды checkout:

   -d	Извлечь вновь появившиеся или пропущенные ранее подкаталоги
   -A	Обновиться до текущего состояния головной ветви
   -jrev	магическая опция (см. ниже)

   Если вы извлекали модуль с опциями -r или -D, выполнение команды cvs update с другими параметрами -r или -D или с опцией -A приведет к выбору новой ветви, ревизии или даты. Использование опции -A удаляет использованные ранее клейкие свойства; опции -r и -D, наоборот, фиксируют их.

   Теоретически использование HEAD в качестве аргумента опции -r должно дать тот же результат, что и указание опции -A, однако это верно лишь в теории.

   Опция -d полезна, если:

   • после извлечения вами модуля кем-либо еще в него были добавлены дополнительные каталоги;

   • вы извлекали верхний уровень модуля при помощи опции -l, а в дальнейшем решили извлечь и подкаталоги;

   • вы удалили какие-либо подкаталоги и теперь хотите вновь извлечь их.

   Обращайте внимание на вывод команды cvs update. Действие, произведенное с файлом, обозначается буквой перед его именем:

   U	Файл был успешно обновлен.
   P	Файл был успешно обновлен (произведен успешный патч из удаленного репозитория).
   M	Файл был изменен, и при этом обновлен успешно.
   C	Файл был изменен, и при объединении изменений возникли конфликты.

   Объединение (merging) производится, если вы выгрузили рабочую копию какого-то модуля, изменили его, затем кто-либо еще произвел коммит собственных изменений, и, наконец, вы выполняете команду cvs update. CVS знает, что производились локальные изменения, и пытается объединить ваши изменения с теми, что произошли в репозитории (от состоянии версии, которую вы выгружали, до версии, до которой вы пытаетесь обновиться). Если изменения происходили с различными частями файла, объединение почти всегда произойдет успешно (хотя результат при этом может не быть синтаксически или семантически корректным).

   CVS выводит букву M перед именем всех локально измененных файлов, даже если у них нет новых версий в репозитории, так что команда cvs update удобна для быстрого получения списка файлов, которые вы изменяли.

   Если в результате вы видите букву C, ваши изменения конфликтуют с изменениями, внесенными в репозиторий (изменения были в одних и тех же или рядом расположенных строках, либо вы изменили файл настолько, что при сравнении cvs не смогла удержать контекст и приложить изменения из репозитория). Вам необходимо устранить конфликты, вручную редактируя файл. Конфликтующие фрагменты помечаются строками из знаков <, = и >. В начале каждого из конфликтов присутствует строка из семи знаков < и имени файла, затем идет фрагмент, содержащий внесенные вами изменения, разделитель из семи знаков =, соответствующий фрагмент из версии файла, содержащейся в репозитории, и, наконец, строка из семи знаков > совместно с номером версии, до которой вы обновляли файл.

   Опция -j содержит некоторое количество черной магии. При ее наличии локальный файл обновляется до указанной версии так же, как и при использовании опции -r, но отслеживаемые номер версии или ветвь не изменяются. Эта опция умеет смысл лишь при парном использовании: при этом делается попытка применить изменения между двумя указанными версиями к локальной копии файла.

   К примеру, вы внесли изменения и произвели коммит в файл shazam/shazam.c в FreeBSD-CURRENT, а позднее хотите перенести обновления в FreeBSD-STABLE (Merge-From-Current, MFC). Версия, которая требует переноса — 1.15:

   • Извлеките текущую версию модуля shazam для ветви FreeBSD-STABLE:

     % cvs co -rRELENG_6 shazam

   • Приложите изменения между версиями 1.14 и 1.15:

     % 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$). Вам потребуется отредактировать файл для устранения конфликта (в данном случае достаточно убрать строки-разделители и вторую строку $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).

4. Просмотр изменение между локальной версией и версией из репозитория: команда diff.

   % cvs diff shazam

   Эта команда покажет все отличия локального состояния файла (или файлов модуля) shazam от состояния, сохраненного в репозитории.

   Таблица 3. Полезные опции команды cvs diff

   -u	Использовать унифицированный (unified) формат.
   -c	Использовать контекстный (context) формат.
   -N	Показывать отсутствующие или созданные файлы.

   Всегда имеет смысл пользоваться опцией -u, поскольку унифицированный формат гораздо удобнее и лучше читаем, чем почти все другие (в некоторых случаях контекстный формат, генерируемый опцией -c может быть несколько лучше, но он гораздо более громоздок). Унифицированный формат различий состоит из серии фрагментов, каждый из которых начинается со строки, состоящей из двух символов @ и номеров строк, описывающих положение изменившегося участка. Затем следует группа строк: те, что начинаются с пробела, описывают контекст, начинающиеся с символа - определяют удаленные строки, наконец, начинающиеся с символа + — добавленные.

   Вы можете сравнивать текущее состояние с версией, отличающейся от той, с которой вы извлекали файл, указав опцию -r или -D подобно командам checkout и update, или даже получить список изменений между любыми двумя версиями (вне зависимости от того, что лежит в вашей локальной копии), указав две версии при помощи опций -r или -D.

5. Просмотр журнала изменений: команда log.

   % cvs log shazam

   Если shazam является обычным файлом, эта команда выдаст на экран заголовок с информацией о файле, в частности, его местоположении в репозитории, какая версия соответствует текущему состоянию (HEAD), в каких ветвях разработки файл присутствует, а также перечислит теги, которыми он помечен. Затем, для каждой версии файла выводится соответствующее ей журнальное сообщение, включающее дату, время и автора коммита, количество добавленных и удаленных строк и собственно журнального сообщения, написанного коммиттером.

   Если shazam является каталогом, вышеописанная процедура выполняется для каждого файла в каталоге. Если при этом команде log не был указан флаг -l, процедура рекурсивно повторяется для всех подкаталогов.

   Команда log используется для просмотра истории одного или нескольких файлов в том виде, как она сохранена в репозитории CVS. Используя опцию -rrev, вы можете посмотреть журнальное сообщение к одной определенной версии:

   % cvs log -r1.2 shazam

   Эта команда покажет журнальное сообщение для версии 1.2 файла shazam (или для версий 1.2 каждого из файлов в каталоге shazam).

6. Кто что делал: команда annotate. Эта команда показывает перед каждой строкой указанного файла (файлов) имя пользователя, вносившего последние изменения в эту строку.

   % cvs annotate shazam

7. Добавление новых файлов: команда add.

   Создайте файл, выполните для него команду cvs add, затем произведите запись в репозиторий (коммит): cvs commit.

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

8. Удаление устаревших файлов: команда remove.

   Удалите файл, затем выполните команду cvs rm с его именем в качестве параметра, наконец, выполните для него cvs commit.

9. Внесение изменений в репозиторий: команда commit или checkin.

   Таблица 4. Useful cvs commit options

   -f	Форсировать внесение изменений для не модифицированного файла.
   -mmsg	Указать сообщение для журнала в командной строке (не запускать текстовый редактор).

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

   Хорошие журнальные сообщения очень важны. Они дают возможность другим узнать, зачем вы производили изменения, причем не только в момент их произведения, но и месяцы или годы спустя, когда кто-либо заинтересуется, почему выглядящий нелогично или неэффективно фрагмент кода попал в каши исходные тексты. Кроме того, это очень помогает в оценке того, нужно ли переносить соответствующий код в FreeBSD-STABLE (MFC).

   Сообщения должны быть ясными, краткими, четкими, и представлять из себя разумную аннотацию, какие изменения были произведены и почему.

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

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

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

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

   Перед коммитом, обязательно:

   • проверьте, что вы будете выполнять коммит в правильную ветвь, посредством команды cvs status.

   • проверьте ваши изменения при помощи команды cvs diff

   Кроме того, ВСЕГДА указывайте, в какие именно файлы вы вносите изменения, так чтобы не включить в этот список лишних файлов. Команда cvs commit без аргументов включит все измененные файлы в текущем каталоге и всех подкаталогах.

Еще несколько полезных советов:

1. Часто используемые опции можно занести в файл ~/.cvsrc, например:

   cvs -z3
   diff -Nu
   update -Pd
   checkout -P

   Для данного случая:

   • всегда использовать компрессию уровня 3 для связи с удаленным сервером CVS. В случае медленного соединения это избавит вас от лишней головной боли.

   • всегда использовать опции -N (показывать добавленные или удаленные файлы) и -u (унифицированный формат) для diff(1).

   • всегда использовать опции -P (удалять пустые каталоги) и -d (добавлять новые каталоги) при обновлении.

   • всегда использовать опцию -P (удалять пустые каталоги) при извлечении файлов и модулей.

2. Пользуйтесь скриптом Эйвинда Эклунда (Eivind Eklund) cdiff для просмотра изменению унифицированного формата. Он является оберткой для less(1), добавляющей цветовые коды ANSI для выделения заголовком, добавленных и удаленных строк; прочие строки не модифицируются. Помимо этого, скрипт корректно разворачивает табуляции (которые часто выглядят неправильно в изменениях из-за дополнительного символа в начале строки).

   textproc/cdiff

   Просто используйте его вместо more(1) или less(1):

   % cvs diff -Nu shazam | cdiff

   Помимо этого, некоторые текстовые редакторы, такие как vim(1) (editors/vim) поддерживают цветовую синтаксическую разметку многих типов файлов, в том числе файлов изменений и журналов CVS/RCS.

   % echo "syn on" >> ~/.vimrc 
   % cvs diff -Nu shazam | vim -
   % cvs log shazam | vim - 

3. CVS — старая, загадочная и порой слабо предсказуемая в своем поведении программа. Ни один человек не способен удержать в голове все тонкости ее работы, так что не бойтесь спрашивать совета у Искусственного Интеллекта (а именно Администраторы Главного CVS Репозитория <cvsadm@FreeBSD.org>).

4. Не оставляйте компьютер в процессе работы команды cvs commit (в редакторе при написании журнального сообщения) слишком надолго (более чем на 2–3 минуты). Эта команда блокирует каталог репозитория, в котором она запущена, и не позволяет другим разработчикам изменять его содержимое. Если вам нужно написать длинное журнальное сообщение, подготовьте его заранее и вставьте в редакторе во время выполнения команды cvs commit, либо запишите его в файл и используйте опцию CVS -F:

   % vi logmsg
   % cvs ci -F logmsg shazam

   Это самый быстрый способ передать журнальное сообщение CVS; однако, вы должны быть внимательны при редактировании файла logmsg, поскольку при выполнении коммита у вас не будет шансов его поправить.

5. Вы можете существенно ускорить скорость работы CVS с центральным репозиторием, используя постоянное соединение с репозиторием. Для этого добавьте в файл ~/.ssh/config строки

   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:

   % ssh -fNM ncvs.FreeBSD.org

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

4. Соглашения и традиции

Став коммиттером, вы должны прежде всего произвести некоторые стандартные действия.

• Добавьте себя в список ''SGML сущностей'' авторов в файл doc/en_US.ISO8859-1/share/xml/authors.ent; это изменение должно быть сделано прежде прочих, поскольку в противном случае следующий ваш коммит неизбежно разрушит процесс построения дерева doc/.

  Это довольно простая задача, но при этом она является неплохим первым тестом ваших навыков работы с CVS.

• Также добавьте свою ''SGML сущность'' в www/en/developers.xml.

• Добавьте себя в раздел ''Разработчики'' статьи Участники проекта FreeBSD (doc/en_US.ISO8859-1/articles/contributors/contrib.committers.xml) и удалите свою запись из раздела ''Прочие участники'' (doc/en_US.ISO8859-1/articles/contributors/contrib.additional.xml).

• Добавьте новость о новом коммиттере в файл www/share/xml/news.xml. Используйте существующие записи вида ''Новый коммиттер'' как шаблон.

• Вам нужно добавить ваш PGP или GnuPG ключ в каталог doc/share/pgpkeys (а если у вас нет ключа, вам нужно его создать). Не забудьте изменить и произвести коммит в файл doc/share/pgpkeys/pgpkeys.ent.

  Dag-Erling C. Smørgrav <des@FreeBSD.org> написал скрипт для упрощения этого процесса. Дополнительную информацию можно прочесть в файле README.

  Замечание: Очень важно, чтобы в Руководстве пользователя был записан актуальный PGP/GnuPG ключ, поскольку он может потребоваться для идентификации коммиттера (например, его будет проверять группа Администраторы FreeBSD.org <admins@FreeBSD.org> для аварийного восстановления учетной записи). Полный набор актуальных ключей пользователей домена FreeBSD.org можно найти по адресу http://www.FreeBSD.org/doc/pgpkeyring.txt.

• Добавьте себя в файл src/share/misc/committers-репозиторий.dot, где репозиторием будет являться либо doc, либо ports, либо src в зависимости от полученных вами коммиттерских привилегий.

• Некоторые коммиттеры добавляют информацию о своем местоположении в файл ports/astro/xearth/files/freebsd.committers.markers.

• Некоторые добавляют данные о дне своего рождения в файл src/usr.bin/calendar/calendars/calendar.freebsd.

• Представьтесь другим коммиттерам, иначе никто не будет знать, кто вы и чем занимаетесь. От вас не требуется писать подробное резюме или биографию: будут достаточны один-два абзаца о себе и областях FreeBSD, в которых вы планируете работать. Пошлите это письмо в Список рассылки разработчиков FreeBSD — и все!

• Зайдите на машину hub.FreeBSD.org и создайте файл /var/forward/user (замените user на ваше имя пользователя). Этот файл должен содержать адрес электронной почты, на который будет переправляться вся почта на адрес yourusername@FreeBSD.org, в том числе сообщения о коммитах и другая почта на адреса Список рассылки коммиттеров FreeBSD и Список рассылки разработчиков FreeBSD. Слишком большие почтовые ящики на машине hub могут быть ''нечаянно'' удалены или обрезаны без предупреждения, так что, чтобы не потерять почту, регулярно читайте ее либо перенаправьте куда-нибудь еще.

  Из-за ощутимой загрузки, возникающей на серверах, обрабатывающих списки рассылки, из-за большого количества незапрошенной почты (спама), сервер, принимающий почту для домена FreeBSD.org, производит некоторые основные проверки и на основании их отвергает некоторые письма. На настоящий момент единственным проверяемым параметром является корректность информации DNS для хоста, доставляющего почту, но в будущем список может вырасти. Эти проверки временами обвиняют в том, что они отвергают правильную почту. Если вы хотите отключить проверки для своего адреса, создайте файл ~/.spam_lover в своей домашней директории на машине freefall.FreeBSD.org.

• Если вы были подписаны на Список рассылки сообщений об изменениях в главном дереве исходных текстов FreeBSD, вам, скорее всего, следует отписаться от него, чтобы не получать дубликатов каждого сообщения о коммитах.

Все новые коммиттеры первоначально работают под руководством ментора. Ваш ментор отвечает за обучение вас правилам и соглашениям, принятым в проекте, и помогает вам сделать первые шаги в среде коммиттеров. Он(а) также персонально отвечает за ваши действия в этот начальный период. До тех пор, пока ваш ментор не решит (и не анонсирует это посредством форсированного коммита файла access), что вы достаточно освоились и готовы работать самостоятельно, перед любым коммитом вы должны получить одобрение (approval) ментора и указать это в журнальном сообщении коммита строкой Approved by:.

Все коммиты в дерево src сначала должны производиться в ветвь FreeBSD-CURRENT и лишь затем интегрироваться в FreeBSD-STABLE. Никакие серьезные изменения, новые возможности или рискованные модификации не должны производиться напрямую в ветви FreeBSD-STABLE.

5. Предпочтительная лицензия для новых файлов

В настоящее время Проект FreeBSD считает предпочтительной формой лицензии на исходные тексты следующий текст:

/*-
* 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 не рекомендует использование полностью новых лицензий или вариаций стандартных лицензий. Новые лицензии перед использованием в репозитории проекта требуют утверждения группой <core@FreeBSD.org>. Большое число различных лицензий затрудняет использование кода, в основном из-за ненамеренных неверных выводов из плохо сформулированных формулировок лицензии.

Политика проекта требует, чтобы код под НЕ-BSD лицензиями располaгался только в определённых местах репозитория, а в некоторых случаях компиляция должна быть условной по умолчанию или вообще отключена. К примеру, ядро GENERIC должно состоять только из лицензий идентичных или в значительной степени схожих с BSD лицензией. Программное обеспечение под лицензиями GPL, APSL, CDDL и др. не должно включаться в состав GENERIC.

Разработчикам напоминается, что в open source правильное понимание "open" также важно, как правильное понимание "source", ибо некорректное использование интеллектуальной собственности имеет серьезные последствия. Какие-либо вопросы или беспокойства на этот счёт должны быть немедленно вынесены на обсуждение главной команде разработчиков (core team).

6. Взаимодействие между разработчиками

Если вы работаете над собственным исходным кодом, либо в области, в которой вы уже определены как ответственная персона, вам, скорее всего, не потребуется согласовывать коммит с кем-либо еще из разработчиков. Те же правила действуют, если вы нашли ошибку в той части системы, которой явно давно никто не занимается (к нашему стыду, существует несколько таких областей). Если же вы собираетесь модифицировать что-либо активно поддерживаемое (по-хорошему, узнать это можно только исследуя архивы списка рассылки cvs-committers), стоит послать предполагаемый патч ответственному за этот участок кода, как вы бы поступали, пока не были коммиттером. В случае портов нужно обращаться по адресу, указанному в строке MAINTAINER в файле Makefile. Для других частей репозитория, в случае если вам не очевидно, кто ведет данный участок кода, может помочь исследование вывода команды cvs log. Bill Fenner <fenner@FreeBSD.org> написал отличный скрипт для определения разработчиков, наиболее активно производивших коммиты, выводящий для каждого из указанных файлов имя пользователя вместе с количеством произведенных им коммитов в данный файл. Скрипт можно найти на машине freefall в файле ~fenner/bin/whodid. Если найденная вами персона не отвечает на ваши вопросы или иным образом демонстрирует отсутствие интереса к проблеме, смело производите коммит самостоятельно.

Если вы по каким-либо причинам не уверены в своих изменениях, предложите их для оценки в списке рассылки -hackers перед коммитом. Будет лучше, если вас обругают там и тогда, чем когда предлагаемое изменение уже будет частью репозитория. Если случилось так, что ваш коммит встретил сопротивление, возможно, стоит его откатить (back out) до тех пор, пока не будет достигнут консенсус. Помните — с помощью CVS всегда можно вернуться к предыдущему состоянию.

Не принимайте в штыки мнения других разработчиков, с которыми вы не согласны. Если они предлагают иное решение проблемы чем вы, или даже иначе воспринимают проблему, это не значит, что они глупы, имеют сомнительное происхождение, хотят разрушить вашу работу, очернить ваше доброе имя, или развалить проект FreeBSD. Просто они смотрят на мир под иным углом. Различные взгляды — благо.

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

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

Спрашивайте и просите о помощи. Предлагайте ваши изменения для рассмотрения коллегам и рассматривайте их изменения. Одним из преимуществ программного обеспечения с открытыми исходными текстами является открытость разработки. Если никто не будет исследовать чужой код, это преимущество исчезнет.

7. GNATS

Для отслеживания ошибок и запросов на изменения проект FreeBSD использует GNATS. Если вы исправили ошибку или внесли изменения, описанные в одном из сообщений об ошибках (PR), не забудьте закрыть это сообщение, используя команду edit-pr pr-number на машине freefall. Хорошо будет, если вы потратите немного времени на поиск и закрытие других PR по этой теме. Вы и сами можете пользоваться send-pr(1) для предложения изменений, которые, по вашему мнению, могут потребовать более подробного обсуждения с коллегами.

Более подробно о GNATS можно прочитать по адресам:

• http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html

• http://www.FreeBSD.org/support.html

• send-pr(1)

Вы можете пользоваться локальной копией GNATS, поддерживая ее синхронность при помощи CVSup. При этом вы можете использовать команды GNATS локально, а также пользоваться другими интерфейсами, такими как tkgnats, что позволит вам работать с базой сообщений об ошибках без соединения с Интернет.

8. Кто есть кто

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

9. SSH: быстрый старт

Теперь вы можете пользоваться утилитой ssh-add(1) для авторизации один раз за сессию. Утилита запросит кодовую фразу для вашего секретного ключа и затем сохранит ее в агенте авторизации (ssh-agent(1)). Если вы хотите удалить сохраненный секретный ключ из агента, используйте команду ssh-add -d.

Для теста используйте команду типа ssh freefall.FreeBSD.org ls /usr.

За дополнительной информацией обращайтесь к security/openssh, ssh(1), ssh-add(1), ssh-agent(1), ssh-keygen(1) и scp(1).

10. Большой Список Правил Коммиттера FreeBSD

1. Уважайте других коммиттеров.

2. Уважайте других участников проекта.

3. Обсудите любые значимые изменения до коммита.

4. Уважайте существующих мейнтейнеров (указанных в поле MAINTAINER файлов Makefile или в файле MAINTAINER в корневом каталоге репозитория).

5. Любое спорное изменение необходимо откатить (back out) в ожидании решения, если того требует мейнтейнер. Вопросы безопасности могут перекрывать мнение мейнтейнера, если так решит Security Officer.

6. Изменения вносятся в ветвь FreeBSD-CURRENT до FreeBSD-STABLE, за исключением случаев, прямо разрешенных выпускающими инженерами или неприменимости изменения к FreeBSD-CURRENT. Любое нетривиальное и не срочное изменение должно быть выдержано в FreeBSD-CURRENT в течение по крайней мере 3 дней перед переносом, чтобы его могли адекватно протестировать. Выпускающие инженеры обладают той же властью в ветви FreeBSD-STABLE, что и мейнтейнеры (см. правило 5).

7. Не пререкайтесь с другими коммиттерами публично: это дурно выглядит. Если вам необходимо с чем-либо ''категорически не согласиться'', делайте это личной почтой.

8. Соблюдайте все периоды заморозки кода (core freeze), а также своевременно читайте списки рассылки committers и developers, чтобы быть в курсе расписания таких периодов.

9. Если вы сомневаетесь в какой-либо процедуре, сначала спросите!

10. Тестируйте свои изменения перед коммитом.

11. Не производите коммит в деревья src/contrib, src/crypto и src/sys/contrib без прямого разрешения (approval) соответствующего мейнтейнера(ов).

Невыполнение этих правил может служить основанием для приостановки или, в случае рецидивов, полного лишения коммиттерских прав. Члены Правления (Core) имеют право временно приостановить права коммиттера до момента, когда Правление в целом сможет решить вопрос. В ''аварийном'' случае (коммиттер разрушает репозиторий) такие права имеют также ответственные за репозиторий. Для приостановки прав коммиттера более чем на неделю или для полного лишения таковых прав требуется квалифицированное большинство (2/3) голосов Правления. Это правило существует не потому, что Правление состоит из злобных диктаторов, разбрасывающихся коммиттерами словно банками из-под колы, но ради предоставления проекту аварийного выключателя. Если кто-то выходит из-под контроля, важно иметь возможность справиться с ситуацией немедленно, а не быть втянутыми в дебаты. В любом случае, коммиттер, чьи права приостановлены, имеет право на ''слушания Правления'', на которых определяется срок приостановки или лишения коммиттерских прав. Коммиттер, права которого приостановлены может запросить пересмотр своего вопроса через 30 дней и каждые последующие 30 дней (если общий период приостановки превышает 30 дней). Коммиттер, полностью лишенный прав, может запросить пересмотр по истечении 6 месяцев. Правила пересмотра являются полностью неформальными и во всех случаях Правление имеет право отвергнуть запрос на пересмотр, если считает свое первоначальное решение верным.

Во всех прочих аспектах деятельности проекта, Правление является подмножеством коммиттеров и ограничено теми же правилами. Само по себе членство в Правлении не дает права преступать описанные правила. Правление обладает ''особой силой'' только в случае деятельность как целое, а не на индивидуальной основе. Члены Правления — в первую очередь коммиттеры.

11. Поддержка различных архитектур

FreeBSD является хорошо портируемой операционной системой и предназначена для работы на самых разнообразных аппаратных архитектурах. Важной частью процесса обеспечения гибкости в поддержке современных тенденций развития оборудования является деление кода на машинно-зависимый (Machine Dependent, MD) и машинно-независимый (Machine Independent, MI), а также, по возможности, минимизация машинно-зависимой части кода. Каждая новая аппаратная архитектура, которую начинает поддерживать FreeBSD, ощутимо увеличивает работу по поддержке кода, инструментария и процесса выпуска релизов. Кроме того, становится значительно сложнее эффективно тестировать изменения в коде ядра. Все это делает необходимым введение различных классов поддержки для различных архитектур, при сохранении максимальной стабильности малого числа "основных платформ".

12. FAQ по работе с портами

# make install
# make package
# make deinstall
# pkg_add имя собранного пакета
# make deinstall
# make reinstall
# make package
	    

errors        журналы ошибок последней сборки версии <major_version> на платформе <arch>
logs          все журналы последней сборки версии <major_version> на платформе <arch>
packages      свежесобранные пакеты для версии <major_version> на платформе <arch>
bak/errors    журналы ошибок последней полной сборки версии <major_version> на платформе <arch>
bak/logs      все журналы последней полной сборки версии <major_version> на платформе <arch>
bak/packages  пакеты последней полной сборки версии <major_version> на платформе <arch>

13. Пряники и прочие льготы

Увы, льгот, возникающих от того, что вы являетесь коммиттером, не так уж много. Пожалуй, единственным несомненным долговременным преимуществом будет признание вас как компетентного специалиста. Тем не менее, кое-какие льготы все же существуют:

14. Прочие вопросы

% 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
	    

...

PR:                foo/12345
Submitted by:	   John Smith <John.Smith@example.com>

...

Reviewed by:       -arch

...

Approved by:	    abc

...

Obtained from:      OpenBSD

...

MFC after:      2 weeks

PR:                 foo/54321
Submitted by:       John Smith <John.Smith@example.com>
Reviewed by:        -arch
Obtained from:      NetBSD
MFC after:          1 month