MAINTAINER= email-addresses
Глава 5. Руководство и политика работы с деревом исходного кода
Этот перевод может быть устаревшим. Для того, чтобы помочь с переводом, пожалуйста, обратитесь к Сервер переводов FreeBSD.
Содержание
Эта глава документирует различные руководства и политики, действующие для дерева исходных кодов FreeBSD.
5.1. Рекомендации по стилю
Соблюдение единого стиля написания кода чрезвычайно важно, особенно в крупных проектах, таких как FreeBSD. Код должен соответствовать стилям программирования FreeBSD, описанным в style(9) и style.Makefile(5).
5.2. MAINTAINER в Makefile-ах
Если определённая часть дистрибутива FreeBSD src/ поддерживается человеком или группой лиц, это указывается в файле src/MAINTAINERS. Сопровождающие портов в Коллекции портов указывают свою ответственность, добавляя строку MAINTAINER в Makefile соответствующего порта:
Для других частей репозитория или для разделов, в которых не указан сопровождающий, или если вы не уверены, кто является активным сопровождающим, попробуйте посмотреть историю последних коммитов соответствующих частей дерева исходного кода. Довольно часто сопровождающий явно не указан, но люди, которые активно работали с частью дерева исходного кода, скажем, последние пару лет, заинтересованы в проверке изменений. Даже если это не указано явно в документации или в самом исходном коде, запросить проверку из вежливости — вполне разумное действие. |
Роль сопровождающего заключается в следующем:
Сопровождающий является владельцем и ответственным за этот код. Это означает, что он или она отвечает за исправление ошибок и решение проблем, связанных с этой частью кода, а в случае с предоставленным программным обеспечением — за отслеживание новых версий, если это необходимо.
Изменения в каталогах, для которых определен сопровождающий, должны быть отправлены сопровождающему на проверку и рецензирование перед коммитом. Только если сопровождающий не отвечает в течение недопустимо долгого времени на несколько писем, допустимо закоммитить изменения без его проверки. Тем не менее, рекомендуется по возможности попытаться получить рецензирование изменений у кого-нибудь ещё.
Конечно, недопустимо добавлять человека или группу в качестве сопровождающего, если они не согласны взять на себя эти обязанности. С другой стороны, это не обязательно должен быть один коммиттер, и это может быть и группа людей.
5.3. Стороннее программное обеспечение
Некоторые части дистрибутива FreeBSD состоят из программного обеспечения, которое активно поддерживается за пределами проекта FreeBSD. По историческим причинам мы называем это сторонним программным обеспечением. Некоторые примеры: LLVM, zlib(3) и awk(1).
Принятая процедура управления вносимым программным обеспечением включает создание ветки поставщика (vendor branch), где программное обеспечение может быть импортировано в чистом виде (без изменений), а обновления могут отслеживаться с учётом версий. Затем содержимое ветки поставщика применяется к дереву исходного кода, возможно, с локальными изменениями. Специфичные для FreeBSD элементы сборки поддерживаются в дереве исходного кода, а не в ветке поставщика.
В зависимости от потребностей и сложности, отдельные программные проекты могут отклоняться от этой процедуры по усмотрению сопровождающего. Точные шаги, необходимые для обновления конкретного программного обеспечения, должны быть записаны в файле с именем FREEBSD-upgrade; например, файл FREEBSD-upgrade libarchive.
Стороннее программное обеспечение обычно размещается в подкаталоге contrib/ дерева исходных кодов, за некоторыми исключениями. Стороннее программное обеспечение, используемое только ядром, находится в sys/contrib/.
Поскольку это затрудняет импорт будущих версий, незначительные, тривиальные и/или косметические изменения настоятельно не рекомендуются для файлов, которые всё ещё отслеживают ветку поставщика. |
5.3.1. Импорт веток поставщика
Стандартный процесс управления сторонним программным обеспечением и ветками поставщиков подробно описан в Руководстве коммиттера.
5.4. Файлы с правовыми ограничениями
Время от времени может возникнуть необходимость включить файл с правовыми ограничениями (обремененными лицензиями, патентами) в дерево исходного кода FreeBSD. Например, если устройство требует загрузки небольшого бинарного кода перед началом работы, а у нас нет исходного кода для него, то такой бинарный файл считается обремененным. Следующие политики применяются к включению обремененных файлов в дерево исходного кода FreeBSD.
Любой файл, который интерпретируется или выполняется процессором(-ами) системы и не представлен в исходном формате, является обременённым.
Любой файл с лицензией более ограничительной, чем BSD или GNU, является обременённым.
Файл, содержащий загружаемые двоичные данные для использования оборудованием, не является обремененным, если к нему не применяется пункт (1) или (2).
Любой файл с правовыми ограничениями требует специального одобрения от Core Team перед добавлением в репозиторий.
Обремененные файлы помещаются в src/contrib или src/sys/contrib.
Весь модуль должен храниться вместе. Нет смысла разделять его, если только нет совместного использования кода с необременённой частью кода.
В прошлом бинарные файлы обычно кодировались с помощью uuencode и назывались arch/filename.o.uu. Теперь в этом нет необходимости, и бинарные файлы могут добавляться в репозиторий без изменений.
Файлы ядра системы:
Пользовательские файлы:
Команда Core team принимает решение о включении кода в базовую устанавливаемую систему.
Отдел разработки релизов решает, войдет ли это в релиз.
5.5. Динамические библиотеки
Если вы добавляете поддержку динамических библиотек в порт или другое программное обеспечение, у которого её нет, номера версий библиотек должны следовать этим правилам. Обычно итоговые номера не будут иметь ничего общего с версией выпуска программного обеспечения.
Для портов:
Предпочитайте использовать номер, уже выбранный вышестоящим проектом
Если вышестоящий источник предоставляет управление версиями символов, убедитесь, что мы используем их скрипт
Для базовой системы:
Начните версии библиотеки с 1
Настоятельно рекомендуется добавить контроль версий символов в новую библиотеку
Если есть несовместимое изменение, обработайте его с помощью версионирования символов, сохраняя обратную совместимость ABI
Если это невозможно или библиотека не использует версионирование символов, увеличьте версию библиотеки
Прежде чем даже рассматривать увеличение версии библиотеки для библиотеки с версионированием символов, проконсультируйтесь с командой Release Engineering, предоставив причины, почему изменение настолько важно, что его следует разрешить, несмотря на нарушение ABI
Например, добавленные функции и исправления ошибок, не изменяющие интерфейсы, допустимы, тогда как удалённые функции, изменённый синтаксис вызовов и т.д. должны либо предоставлять обратно-совместимые символы, либо приведут к изменению старшего номера версии.
Обязанность коммиттера, вносящего изменения, — управлять версионированием библиотек.
Динамический загрузчик ELF сопоставляет имена библиотек буквально. Существует популярное соглашение, согласно которому версия библиотеки записывается в виде libexample.so.x.y, где x — это мажорная версия, а y — минорная. Общепринятой практикой является установка поля soname у библиотеки (тег ELF DT_SONAME) в libexample.so.x, а также создание символических ссылок libexample.so.x→libexample.so.x.y, libexample.so→libexample.so.x при установке библиотеки для последней минорной версии y. Таким образом, поскольку статический компоновщик ищет libexample.so, когда указана опция командной строки -lexample, объекты, скомпонованные с libexample, получают информацию о зависимости от правильной библиотеки. Почти все популярные системы сборки автоматически используют эту схему.
Изменено: 12 октября 2025 г. by Vladlen Popolitov