Глава 6. Лучшие практики создания пакетов

Содержание

6.1. Лучшие практики для debian/rules
6.1.1. Сценарии-помощники
6.1.2. Отделение ваших заплат в несколько файлов
6.1.3. Множественные двоичные пакеты
6.2. Лучшие практики для debian/control
6.2.1. Общие принципы описания пакетов
6.2.2. Резюме пакета или короткое описание
6.2.3. Длинное описание
6.2.4. Домашняя страница основной ветки разработки
6.2.5. Размещение системы контроля версий
6.2.5.1. Vcs-Browser
6.2.5.2. Vcs-*
6.3. Лучшие практики для debian/changelog
6.3.1. Написание полезных пунктов файла изменений
6.3.2. Selecting the upload urgency
6.3.3. Распространённые неправильные представления о записях об изменениях
6.3.4. Общие ошибки в записях об изменениях
6.3.5. Дополнение журналов файлами NEWS.Debian
6.4. Лучшие практики для сценариев сопровождающих
6.5. Управление настройкой с помощью debconf
6.5.1. Не злоупотребляйте debconf
6.5.2. Общие рекомендации для авторов и переводчиков
6.5.2.1. Пишите на правильном английском
6.5.2.2. Будьте добры к переводчикам
6.5.2.3. Отменяйте статус неясных строк когда исправляете опечатки или орфографию
6.5.2.4. Не допускайте ничего по поводу интерфейсов
6.5.2.5. Не используйте первое лицо
6.5.2.6. Будьте нейтральны в гендерном отношении
6.5.3. Определение полей шаблонов
6.5.3.1. Тип
6.5.3.1.1. string
6.5.3.1.2. password
6.5.3.1.3. boolean
6.5.3.1.4. select
6.5.3.1.5. multiselect
6.5.3.1.6. note
6.5.3.1.7. text
6.5.3.1.8. error
6.5.3.2. Описание: краткое и расширенное описания
6.5.3.3. Choices
6.5.3.4. Default
6.5.4. Template fields specific style guide
6.5.4.1. Тип поля
6.5.4.2. Поле Description
6.5.4.2.1. Шаблоны string/password
6.5.4.2.2. Шаблоны boolean
6.5.4.2.3. select/multiselect
6.5.4.2.4. Примечания
6.5.4.3. Поле Choices
6.5.4.4. Поле Default
6.6. Интернационализация
6.6.1. Обработка переводов debconf
6.6.2. Интернационализованная документация
6.7. Общие ситуации при создании пакетов
6.7.1. Пакеты, использующие autoconf/automake
6.7.2. Библиотеки
6.7.3. Документация
6.7.4. Конкретные типы пакетов
6.7.5. Независящие от архитектуры данные
6.7.6. Необходимость в конкретной локали во время сборки
6.7.7. Делаем так, чтобы deborphan определят переходные пакеты
6.7.8. Лучшие практики для файлов .orig.tar.{gz,bz2,xz}
6.7.8.1. Чистый исходный код
6.7.8.2. Повторная упаковка исходного кода основной ветки
6.7.8.3. Изменение двоичных файлов
6.7.9. Лучшие практики для отладочных пакетов
6.7.9.1. Automatically generated debug packages
6.7.9.2. Manual -dbg packages
6.7.10. Лучшие практики для метапакетов

Debian's quality is largely due to the Debian Policy, which defines explicit baseline requirements that all Debian packages must fulfill. Yet there is also a shared history of experience which goes beyond the Debian Policy, an accumulation of years of experience in packaging. Many very talented people have created great tools, tools which help you, the Debian maintainer, create and maintain excellent packages.

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

The following recommendations apply to the debian/rules file. Since debian/rules controls the build process and selects the files that go into the package (directly or indirectly), it's usually the file maintainers spend the most time on.

Основная причина использования сценариев-помощников в файле debian/rules заключается в том, что последние позволяют сопровождающим распространять общую логику на множество пакетов и использовать её. Рассмотрим для примера вопрос установки пунктов меню: вам необходимо поместить файл в /usr/share/menu (или, если это требуется, /usr/lib/menu для выполняемых двоичных файлов меню), а также добавить команды сценариям сопровождающего для регистрации и отмены регистрации этих пунктов меню. Поскольку это довольно частая задача, зачем каждому сопровождающему переписывать всё это самостоятельно, а иногда и с ошибками? Кроме того, допустим, что каталог меню изменился, в этом случае пришлось бы изменить каждый пакет.

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

Раздел A, «Обзор инструментов Debian для сопровождающего» содержит описание различных помощников. Наиболее часто используемой и лучшей (по нашему мнению) системой-помощником является debhelper. Предшествующие системы-помощники, такие как debmake, были монолитны: вы не могли выбрать только ту часть помощника, которая кажется вам полезной, вам приходилось использовать этот помощник для всего сразу. Тем не менее, debhelper представляет собой ряд отдельных небольших программ dh_*. Например, dh_installman устанавливает и сжимает страницы руководства, dh_installmenu устанавливает файлы меню и так далее. Таким образом, этот помощник предлагает достаточный уровень гибкости, позволяющий использовать небольшие сценарии-помощники там, где это подходит, а также команды, добавленные в файл debian/rules вручную.

Вы можете начать своё знакомство с debhelper с чтения debhelper(1) и изучения примеров, которые поставляются вместе с содержащим этот помощник пакетом. dh_make из пакета dh-make (см. раздел A.3.2, «dh-make»), может использоваться для перевода ванильного пакета с исходным кодом в debhelperианизированый пакет. Этот короткий путь не должен, однако, создать у вас впечатление, что вам не нужно беспокоиться о понимании каждого отдельного помощника dh_*. Если вы собираетесь использовать помощник, вам следует потратить время на изучение того, как этот помощник используется, и изучить его ожидания и поведение.

Большие, сложные пакеты могут содержать множество ошибок, с которыми вам предстоит иметь дело. Если вы исправляете несколько ошибок напрямую в исходном коде, и при этом вы недостаточно внимательны, дифференцировать различные заплаты, которые вы применили, может стать довольно трудной задачей. Пакет может превратиться в бардак, когда вам придётся обновить его для новой версии из основной ветки разработки, содержащей некоторые (но не все) применённые вами исправления. Вы не можете просто взять полный набор diff'ов (напр., из .diff.gz) и определить то, какой набор заплат представляет собой тот единый компонент кода, содержащий исправление ошибок для основной ветки разработки.

Fortunately, with the source format “3.0 (quilt)” it is now possible to keep patches separate without having to modify debian/rules to set up a patch system. Patches are stored in debian/patches/ and when the source package is unpacked patches listed in debian/patches/series are automatically applied. As the name implies, patches can be managed with quilt.

При использовании более старого формата пакетов с исходным кодом “1.0” также можно выделить заплаты, но тогда необходимо использовать выделенную систему заплат: файлы заплат поставляются в файле заплат Debian (.diff.gz), который обычно располагается в каталоге debian/. Единственное отличие состоит в том, что в таком случае заплаты не применяются непосредственно командой dpkg-source, но правилом build файла debian/rules, через зависимость от правила patch. И наоборот, они отменяются в правиле clean, через зависимость от правила unpatch.

quilt is the recommended tool for this. It does all of the above, and also allows one to manage patch series. See the quilt package for more information.

Для обработки заплат существуют и другие инструменты, такие как dpatch, и система заплат, интегрированная в cdbs.

Следующие практики относятся к файлу debian/control. Они дополняют Политику описаний пакетов.

Описание пакета, как оно определено в соответствующем поле файла control, содержит резюме пакета и длинное описание этого пакета. раздел 6.2.1, «Общие принципы описания пакетов» описывает общие принципы обеих этих частей описания пакета. Далее, раздел 6.2.2, «Резюме пакета или короткое описание» содержит принципы, относящиеся к резюме, а раздел 6.2.3, «Длинное описание» представляет собой принципы, относящиеся к описанию.

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

Наш обзор описаний пакетов привёл нас к заключению, что большая часть описаний пакетов являются техническими, то есть они не написаны так, чтобы быть понятными технически не подкованным пользователям. Если ваш пакет предназначен не только для технических пользователей, это является проблемой.

Как следует писать описания для технически не подкованных пользователей? Избегайте жаргона. Избегайте указания на другие приложения или наборы приложений, которые могут быть незнакомы пользователю — GNOME или KDE это нормально, так как пользователи вероятно знакомы с этими терминами, но термин GTK+ скорее всего им не знаком. Попытайтесь вообще не допускать какого-либо знания. Если вам нужно использовать технические термины, определите их.

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

Указания на названия любых других пакетов ПО, названия протоколов, стандартов или спецификаций должны иметь каноническую форму, если таковая существует. Например, используйте X Window System, X11 или X; но не X Windows, X-Windows или X Window. Используйте GTK+, а не GTK или gtk. Используйте GNOME, а не Gnome. Используйте PostScript, а не Postscript или postscript.

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

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

Резюме представляет собой фразу, описывающую пакет, а не полное предложение, поэтому пунктуация, характерная для предложений, тут неуместна: дополнительные заглавные буквы или точка в конце (как знак полной остановки) не нужны. Также следует пропустить любой начальный неопределённый или определённый артикль — "a", "an" или "the". Таким образом, например:

Package: libeg0
Description: exemplification support library

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

Пакет имя пакета предоставляет {a,an,the,some} резюме пакета.

Наборы связанных пакетов могут использовать альтернативную схему, которая разделяет резюме на две части, на, во-первых, описание всего набора и, во-вторых, резюме роли конкретного пакета в этом наборе:

Package: eg-tools
Description: simple exemplification system (utilities)
			              
Package: eg-doc
Description: simple exemplification system - documentation

Эти резюме следуют изменённой формуле. В ней пакет "имя пакета" имеет резюме "набор пакетов (роль)" или "набор пакетов - роль", элементы резюме должны быть сформулированы так, чтобы они подходили под следующую формулу:

Пакет имя пакета предоставляет {a,an,the} роль для набора пакетов.

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

Длинное описание должно состоять из полных и законченных предложений.

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

The following paragraphs should answer the following questions: Why do I as a user need this package? What other features does the package have? What outstanding features and deficiencies are there compared to other packages (e.g., if you need X, use Y instead)? Is this package related to other packages in some way that is not handled by the package manager (e.g., is this the client for the foo server)?

Будьте внимательны, избегайте орфографических и грамматических ошибок. Проверьте описание на ошибки. И ispell, и aspell имеют специальные режимы для проверки файлов debian/control:

ispell -d american -g debian/control
aspell -d en -D -c debian/control

Обычно пользователи ожидают найти в описании пакета ответы на следующие вопросы:

  • Что этот пакет делает? Если он является дополнением для другого пакета, то в описании следует поместить краткое описание того пакета, дополнением которого является данный пакет.

  • Почему я хочу получить этот пакет? Ответ на этот вопрос связан с ответом на предыдущий вопрос, но это разные вопросы (это клиент электронной почты; он классный, быстрый, работает с PGP и LDAP, а также с IMAP, он имеет X, Y и Z).

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

  • Если пакет является экспериментальным, либо имеются другие причины, по которым этот пакет не следуем использовать, если имеются другие пакеты, которые следует использовать вместо данного, это также должно быть отдельно указано.

  • How is this package different from the competition? Is it a better implementation? more features? different features? Why should I choose this package?

В файле debian/control имеются дополнительные поля для указания размещения системы контроля версий.

Value of this field should be a string identifying unequivocally the location of the Version Control System repository used to maintain the given package, if available. * identifies the Version Control System; currently the following systems are supported by the package tracking system: arch, bzr (Bazaar), cvs, darcs, git, hg (Mercurial), mtn (Monotone), svn (Subversion). It is allowed to specify different VCS fields for the same package: they will all be shown in the PTS web interface.

Подразумевается, что эта информация будет полезна пользователю, которых осведомлён о принципах работы данной системы управления версиями и желает собрать текущую версию пакета из исходного кода, размещённого там. Другие способы использования этой информации могут включать автоматическую сборку последней версии данного пакета из системы управления версиями. Для этого размещение, указанное в данном поле, не должно иметь привязку к версии и должно указывать на основную ветку (это касается систем управления версиями, поддерживающих эту возможность). Кроме того, указываемое размещение должно быть доступно конечному пользователю; для выполнения этого требования может потребоваться указание на анонимный доступ к репозиторию вместо указания версии, доступной через SSH.

В следующем примере демонстрируется пакет vim в соответствующем поле которого указан репозиторий Subversion. Заметьте, что URL приведён по схеме svn:// (а не по схеме svn+ssh://), а также то, что указана ветвь trunk/. Также демонстрируется использование полей Vcs-Browser и Homepage, описанных выше.

  Source: vim
  Section: editors
  Priority: optional
  <snip>
  Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
  Vcs-Browser: https://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim
  Homepage: http://www.vim.org

Следующие практики дополняют Политику о файлах изменений.

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

Обратите внимание на то, что было изменено — кто, как и когда обычно менее важно. Указав это, не забудьте вежливо указать людей, которые оказали заметную помощь в создании пакета (напр., тех, что выслал заплаты).

Нет необходимости указывать тривиальные и очевидные изменения. Также вы можете объединять несколько изменений в одну запись. С другой стороны, не будьте чересчур кратки, если внесли крупное изменение. Будьте особенно ясны, если были произведены изменения, которые оказывают влияние на поведение программы. Для указания дальнейших объяснений используйте файл README.Debian.

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

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

Если вы ссылаетесь на ошибки, не предполагайте у пользователей какого-либо знания. Сообщите, в чём заключалась проблема, как она была исправлена, и добавьте строку closes: #nnnnn. Дополнительную информацию см. в разделе 5.8.4, «Когда ошибки исправляются путём новых загрузок».

Записи об изменениях не должны описывать общие проблемы при создании пакета (Эй, если вы ищете foo.conf, он находится в /etc/бла-бла-бла/.), поскольку предполагается, что администраторы и пользователи по меньшей мере отдалённо знакомы с тем, как такие вещи обычно улаживаются в системах Debian. Сообщите, тем не менее, о том, что вы изменили расположение файла настройки, если вы произвели такое изменение.

Единственными закрываемыми с помощью записей об изменениях ошибками должны быть те, которые фактически исправляются именно в этой ревизии пакета. Закрытие несвязанных ошибок в журнале изменений является плохой практикой. См. раздел 5.8.4, «Когда ошибки исправляются путём новых загрузок».

Записи об изменениях не должны использоваться для случайных дискуссий с теми, кто сообщил об ошибках (Я не наблюдаю ошибки сегментирования, когда запускаю foo с опцией bar; вышлите дополнительную информацию), общих утверждений о жизни, Вселенной и вообще (извините, загрузка этой версии заняла так много времени, но у меня была простуда), или просьб о помощи (список ошибок этого пакета очень велик, пожалуйста, помогите мне с этим). Скорее всего всё это не будет замечено целевой аудиторией, но может надоедать тем людям, которые хотят читать информацию о фактических изменениях в пакете. Подробную информацию о том, как использовать систему отслеживания ошибок см. в разделе 5.8.2, «Ответ на ошибки».

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

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

  * Fixed all outstanding bugs.

Очевидно, эта запись не сообщает читателям ничего полезного.

  * Applied patch from Jane Random.

Что это была за заплата?

  * Late night install target overhaul.

Что это была за переделка? Упоминание поздней ночи предполагается как сообщение о том, что этому коду не следует доверять?

  * Fix vsync fw glitch w/ ancient CRTs.

Too many acronyms (what does "fw" mean, "firmware"?), and it's not overly clear what the glitch was actually about, or how it was fixed.

  * This is not a bug, closes: #nnnnnn.

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

  * Has been fixed for ages, but I forgot to close; closes: #54321.

If for some reason you didn't mention the bug number in a previous changelog entry, there's no problem, just close the bug normally in the BTS. There's no need to touch the changelog file, presuming the description of the fix is already in (this applies to the fixes by the upstream authors/maintainers as well; you don't have to track bugs that they fixed ages ago in your changelog).

  * Closes: #12345, #12346, #15432

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

Важные новости об изменениях в пакете можно также поместить в файл NEWS.Debian. Новости будут отображены такими инструментами как apt-listchanges до всех остальных журналов изменений. Это является предпочтительным способом сообщения пользователям о существенных изменениях в пакете. Это лучше, чем использование примечаний debconf, поскольку этот способ менее надоедлив и пользователь может вернуться и просмотреть файл NEWS.Debian после установки. И это лучше, чем указание крупных изменений в файле README.Debian, поскольку пользователь легко может не заметить вашего сообщения.

Формат этот файла такой же как и формат файла журнала изменений, но забудьте о звёздочках и описывайте каждую новость в отдельном полном параграфе, если это необходимо, вместо того, чтобы давать более краткие резюме, которые подходят для журнала изменений. Хорошо бы пропустить ваш файл через dpkg-parsechangelog для проверки форматирования, поскольку в отличии от журнала изменений он не будет проверен автоматически во время сборки. Ниже приведён пример настоящего файла NEWS.Debian:

cron (3.0pl1-74) unstable; urgency=low

    The checksecurity script is no longer included with the cron package:
    it now has its own package, checksecurity. If you liked the
    functionality provided with that script, please install the new
    package.

 -- Steve Greenland <stevegr@debian.org>  Sat,  6 Sep 2003 17:15:03 -0500

Файл NEWS.Debian устанавливается как /usr/share/doc/пакет/NEWS.Debian.gz. Он сжимается, и он всегда имеет данное имя даже в родных пакетах Debian. Если вы используете debhelper, dh_installchangelogs установит файлы debian/NEWS за вас.

В отличии от файлов журналов вам не нужно обновлять файлы NEWS.Debian в каждом выпуске. Обновляйте их только если имеется что-то действительно заслуживающее упоминания, что должно быть известно пользователю. Если у вас нет никаких новостей, не нужно добавлять файл NEWS.Debian в ваш пакет. Отсутствие новостей — уже хорошие новости!

Maintainer scripts include the files debian/postinst, debian/preinst, debian/prerm and debian/postrm. These scripts take care of any package installation or deinstallation setup that isn't handled merely by the creation or removal of files and directories. The following instructions supplement the Debian Policy.

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

Стандартные ввод и вывод могут быть перенаправлены (напр., конвейерами) с целью записи журнала для отладки, поэтому вам не следует считать, что они представляют собой лишь tty.

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

Делайте сценарии сопровождающего насколько простыми, насколько это возможно. Мы предлагаем использовать чистые сценарии оболочки POSIX. Помните, если вам нужны какие-либо возможности bash, сценарий сопровождающего должен содержать строку, объявляющую использование bash. Оболочка POSIX или Bash предпочтительны по отношению к Perl, поскольку они позволяют debhelper легко добавлять что-то новое в эти сценарии.

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

Если вам необходимо проверить существование команды, используйте что-то вроде этого:

if which install-docs > /dev/null; then ...

Вы можете использовать эту функцию для поиска $PATH для имения команды, переданной в качестве аргумента. Она возвращает истинное значение (ноль), если команда была найдена, и ложь, если нет. В действительности, это наиболее переносимый способ, поскольку command -v, type и which не совместимы с POSIX.

Хотя which является допустимой альтернативой, так как она поставляется в требуемом пакете debianutils, она находится не на корневом разделе. То есть, она располагается в /usr/bin, а не в /bin, поэтому её нельзя использовать в сценариях, которые запускаются до монтирования раздела /usr. Хотя, большинство сценариев не имеют такой проблемы.

Debconf is a configuration management system that can be used by all the various packaging scripts (postinst mainly) to request feedback from the user concerning how to configure the package. Direct user interactions must now be avoided in favor of debconf interaction. This will enable non-interactive installations in the future.

Debconf является превосходным инструментом, но часто он плохо используется. Многие общие ошибки приведены на странице руководства debconf-devel(7). Вам следует прочитать это руководство, если вы решили использовать debconf. Кроме этого, здесь мы приводим ниже лучшие практики использования этого инструмента.

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

Большинство сопровождающих Debian не являются носителями английского языка. Поэтому написание правильно сформулированных шаблонов может быть для них нелегким делом.

Используйте список рассылки (и злоупотребляйте им). Пусть ваши шаблоны будут вычитаны.

Плохо написанные шаблоны создают плохое представление о вашем пакете, вашей работе... и даже самом Debian.

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

Debconf templates may be translated. Debconf, along with its sister package po-debconf, offers a simple framework for getting templates translated by translation teams or even individuals.

Используйте шаблоны на основе gettext. Установите po-debconf в вашу систему, используемую для разработки, и прочтите документацию этого пакета (man po-debconf является хорошим началом).

Avoid changing templates too often. Changing template text induces more work for translators, which will get their translation fuzzied. A fuzzy translation is a string for which the original changed since it was translated, therefore requiring some update by a translator to be usable. When changes are small enough, the original translation is kept in PO files but marked as fuzzy.

Если вы планируете изменить ваши оригинальные шаблоны, для связи с переводчиками используйте систему оповещения, предоставляемую пакетом po-debconf, а именно podebconf-report-po. Наиболее активные переводчики очень отзывчивы, и включение их работы вместе с вашими изменёнными шаблонами позволит избежать вам дополнительных загрузок. Если вы используете шаблоны на основе gettext, имя переводчика и его адрес электронной почты указаны в заголовках PO-файлов и будут использоваться командой podebconf-report-po.

Рекомендованное использование этой утилиты:

cd debian/po && podebconf-report-po --call --languageteam --withtranslators --deadline="+10 days"

This command will first synchronize the PO and POT files in debian/po with the template files listed in debian/po/POTFILES.in. Then, it will send a call for new translations, in the mailing list. Finally, it will also send a call for translation updates to the language team (mentioned in the Language-Team field of each PO file) as well as the last translator (mentioned in Last-translator).

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

Если у вас возникли сомнения, вы также можете связаться с командой перевода данного языка (debian-l10n-xxxxx@lists.debian.org) или списком рассылки .

Когда текст шаблона debconf был изменён, и вы уверены, что это изменение не влияет на переводы, будьте добры по отношению к переводчикам и отмените статус неясных строк для их переводов.

Если вы не сделаете этого, весь шаблон не будет переведён пока переводчик не вышлет вам обновление.

Чтобы отменить статус неясных строк для переводов, вы можете использовать msguntypot (часть пакета po4a).

  1. Создание файлов POT и PO заново.

    debconf-updatepo
  2. Создание копии POT-файла.

    cp templates.pot templates.pot.orig
  3. Создание копии всех PO-файлов.

    mkdir po_fridge; cp *.po po_fridge
  4. Изменение файлов шаблона debconf для исправления ошибок.

  5. Создание файлов POT и PO заново (опять).

    debconf-updatepo

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

  6. Отбросьте неясный перевод, восстановите перевод из сохранённых во временном каталоге файлов.

    cp po_fridge/*.po .
  7. Вручную слейте файлы PO с новым POT-файлов, но учтите бесполезные неясности.

    msguntypot -o templates.pot.orig -n templates.pot *.po
  8. Очистите.

    rm -rf templates.pot.orig po_fridge

As a way of showing our commitment to our diversity statement, please use gender-neutral constructions in your writing. This means avoiding pronouns like he/she when referring to a role (like "maintainer") whose gender is unknown. Instead, you should use the plural form (singular they).

Эта часть содержит информацию, которая по большей части заимствована из страницы руководства debconf-devel(7).

Выбор одного значения из нескольких предложенных. Выбор должен быть определён в поле с именем 'Choices'. Разделите возможные значения запятыми и пробелами, например так: Choices: yes, no, maybe.

Если варианты выбора представляют собой переводимые строки, поле 'Choices' может быть отмечено как переводимое так: __Choices. Двойное подчёркивание выделит каждый вариант выбора в отдельную строку.

Также система po-debconf предлагает интересные возможности для отметки только некоторых вариантов выбора в качестве переводимых. Пример:

Template: foo/bar
Type: Select
#flag:translate:3
__Choices: PAL, SECAM, Other
_Description: TV standard:
 Please choose the TV standard used in your country.

В этом примере только строка 'Other' является переводимой, остальные же представляют собой акронимы, которые не нужно переводить. Этот пример разрешает включение в файлы PO и POT только варианта 'Other'.

Система флагов для шаблонов debconf предлагает множество таких возможностей. В странице руководства po-debconf(7) приведены все эти возможности.

Описания шаблонов имеют две части: краткую и расширенную. Краткое описание даётся в строке Description: данного шаблона.

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

The short description should be able to stand on its own. Some interfaces do not show the long description by default, or only if the user explicitly asks for it or even do not show it at all. Avoid things like: "What do you want to do?"

Краткое описание не обязательно должно быть полным предложением. Это лишь часть, она должна быть краткой и эффективной рекомендацией.

Расширенное описание не должно слово в слово повторять краткое описание. Если вы не можете придумать длинное описание, то для начала подумайте ещё. Напишите в debian-devel. Попросите помощи. Прослушайте курс письма! Расширенное описание очень важно. Если в конце концов вы всё еще не можете ничего придумать, оставьте его пустым.

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

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

Расширенное описание никогда не должно включать в себя вопрос.

Для ознакомления с конкретными правилами, зависящими от типа шаблона (string, boolean и т. д.), прочтите нижеследующий текст.

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

If the default value for a select template is likely to vary depending on the user language (for instance, if the choice is a language choice), please use the _Default trick, documented in po-debconf(7).

This special field allows translators to put the most appropriate choice according to their own language. It will become the default choice when their language is used while your own mentioned Default Choice will be used when using English.

Do not use an empty default field. If you don't want to use default values, do not use Default at all.

If you use po-debconf (and you should; see Раздел 6.5.2.2, «Будьте добры к переводчикам»), consider making this field translatable, if you think it may be translated.

Пример, взятый из шаблонов пакета geneweb:

Template: geneweb/lang
Type: select
__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv)
# This is the default choice. Translators may put their own language here
# instead of the default.
# WARNING : you MUST use the ENGLISH NAME of your language
# For instance, the French translator will need to put French (fr) here.
_Default: English[ translators, please see comment in PO files]
_Description: Geneweb default language:

Note the use of brackets, which allow internal comments in debconf fields. Also note the use of comments, which will show up in files the translators will work with.

The comments are needed as the _Default trick is a bit confusing: the translators may put in their own choice.

This section contains global information for developers to make translators' lives easier. More information for translators and developers interested in internationalization are available in the Internationalisation and localisation in Debian documentation.

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

The goal of debconf was to make package configuration easier for maintainers and for users. Originally, translation of debconf templates was handled with debconf-mergetemplate. However, that technique is now deprecated; the best way to accomplish debconf internationalization is by using the po-debconf package. This method is easier both for maintainer and translators; transition scripts are provided.

При использовании po-debconf, перевод сохраняется в файлах .po (формате, извлечённом из gettext). Специальные файлы шаблонов содержат оригинальные сообщения и пометки для тех полей, которые могут быть переведены. Когда вы изменяете значение поля, которое может быть переведено, вызывая команду debconf-updatepo, перевод отмечается как требующий внимания переводчиков. Тогда, во время сборки, программа dh_installdebconf заботится обо всей требуемой магии по добавлению шаблона вместе с обновлёнными переводами в двоичные пакеты. За подробностями обратитесь к странице руководства po-debconf(7).

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

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

If you maintain XML or SGML documentation, we suggest that you isolate any language-independent information and define those as entities in a separate file that is included by all the different translations. This makes it much easier, for instance, to keep URLs up to date across multiple files.

Some tools (e.g. po4a, poxml, or the translate-toolkit) are specialized in extracting the translatable material from different formats. They produce PO files, a format quite common to translators, which permits seeing what needs to be re-translated when the translated document is updated.

Обязательно пройдите по ссылке Политика документации.

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

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

Крупные руководства должны при установке регистрироваться в doc-base. Дополнительную информацию см. в документации пакета doc-base.

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

The manpages do not need to be written directly in the troff format. Popular source formats are DocBook, POD and reST, which can be converted using xsltproc, pod2man and rst2man respectively. To a lesser extent, the help2man program can also be used to write a stub.

Некоторые конкретные типы пакетов имеют свои специальные подполитики и соответствующие правила и практики создания пакетов:

  • Perl related packages have a Perl policy; some examples of packages following that policy are libdbd-pg-perl (binary perl module) or libmldbm-perl (arch independent perl module).

  • Python related packages have their Python policy; see /usr/share/doc/python/python-policy.txt.gz in the python package.

  • Связанные с Emacs пакеты имеют Политику Emacs.

  • Связанные с Java пакеты имеют свою Политику Java.

  • OCaml related packages have their own policy, found in /usr/share/doc/ocaml/ocaml_packaging_policy.gz from the ocaml package. A good example is the camlzip source package.

  • Пакеты, предоставляющие XML или SGML DTD должны соответствовать рекомендациям из пакета sgml-base-doc.

  • Пакеты Lisp должны регистрироваться в common-lisp-controller, об этом см. /usr/share/doc/common-lisp-controller/README.packaging.

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

Например, с аргументом --guess-dummy, deborphan пытается найти все переходные пакеты, которые нужны для обновления, но которые теперь могут быть легко удалены. Для этого она ищет строку dummy или transitional в их кратком описании.

Поэтому когда вы создаёте такой пакет, убедитесь, что этот текст добавлен в ваше краткое описание. Если вы хотите ознакомиться с примерами, запустите: apt-cache search .|grep dummy или apt-cache search .|grep transitional.

Also, it is recommended to adjust its section to oldlibs and its priority to optional in order to ease deborphan's job.

Существует два вида оригинальных tar-архивов с исходным кодом: чистый исходный код и запакованный заново исходный код основной ветки разработки.

Определяющей характеристикой чистого tar-архива с исходным кодом является то, что файл .orig.tar.{gz,bz2,xz} побайтово идентичен tar-архиву, который официальной распространялся автором основной ветки разработки.[6] Это позволяет использовать контрольные суммы для простой проверки, что все изменения между версией Debian и версией основной ветки содержаться в db=iff-файле Debian. Кроме того, если оригинальный исходный код имеет большой размер, авторы основной ветки разработки и другие, кто уже имеют tar-архив из основной ветки, могут сохранить время, затрачиваемое на скачивание, в том случае, если они хотят подробно проверить ваш пакет.

There are no universally accepted guidelines that upstream authors follow regarding the directory structure inside their tarball, but dpkg-source is nevertheless able to deal with most upstream tarballs as pristine source. Its strategy is equivalent to the following:

  1. Он распаковывает tar-архив в пустой временный каталог, выполняя

    zcat путь/к/имя-пакета_версия-основной-ветки.orig.tar.gz | tar xf -
    
  2. Если после этого временный каталог не содержит ничего кроме одного каталога и не содержит других файлов, dpkg-source переименовывает этот каталог в имяпакета-версия-основной-ветки(.orig). Имя каталога верхнего уровня в tar-архиве не имеет значения и просто забывается.

  3. В противном случае, tar-архив основной ветки должен быть запакован без общего каталога верхнего уровня (позор автору основной ветки!). В этом случае dpkg-source переименовывает самостоятельно временный каталог в имяпакета-версия-основной-ветки(.orig).

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

В этих случаях разработчик должен создать подходящий файл .orig.tar.{gz,bz2,xz} самостоятельно. Мы говорим о таком tar-архиве как о запакованном заново исходном коде основной ветки. Заметьте, что запакованный заново исходный код основной ветки отличается от родного пакета Debian. Запакованный заново исходный код содержит специфичные для Debian изменения в отдельных файлах .diff.gz или .debian.tar.{gz,bz2,xz} и всё ещё имеет номер версии, составленный из версия-основной-ветки и версия-debian.

Возможны такие случаи, когда желательно запаковать исходный код заново, даже несмотря на то, что основная ветка разработки поставляет .tar.{gz,bz2,xz}, который в принципе может использовать в его чистой форме. Наиболее очевидным случаем является ситуация, когда может быть достигнута значительная экономия места путём повторной упаковки tar-архива или путём удаления действительно ненужного хлама из архива основной ветки. Используйте это на своё усмотрение, но будьте готовы защищать своё решение, если вы запаковали заново исходный код, которые мог бы быть чистым.

Запакованный заново .orig.tar.{gz,bz2,xz}

  1. должен быть документирован в получившемся пакете с исходным кодом. Подробная информация о том, как был получен запакованный заново исходный код, а также о том, как этот процесс может быть воспроизведён, должна быть предоставлена в debian/copyright. Также рекомендуется предоставлять цель get-orig-source в вашем файле debian/rules, которая повторяет этот процесс, это описано в Руководстве по политике, Основной сборочный сценарий: debian/rules.

  2. не должен содержать какие-либо файлы, которые получены не от авторов основной ветки разработки, или содержание которых было изменено вами.[7]

  3. должен, за исключением случаев, когда это невозможно по юридическим причинам, сохранять всю целиком сборочную инфраструктуру и инфраструктуру для переноса, предоставляемую автором основной ветки разработки. Например, то, что какой-то файл используется только для сборки под MS-DOS, не является достаточным основанием для его удаления. Сходным образом, Makefile, предоставляемый основной веткой разработки не должен быть удалён, даже если ваш файл debian/rules перезаписывает его, запуская сценарий настройки.

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

  4. должен использовать имяпакета-версия-основной-ветки.orig в качестве имени каталога верхнего уровня в своём tar-архиве. Это позволяет отличить чистые tar-архивы от запакованных заново.

  5. должен быть сжат с помощью gzip или bzip с максимальным сжатием.

A debug package is a package that contains additional information that can be used by gdb. Since Debian binaries are stripped by default, debugging information, including function names and line numbers, is otherwise not available when running gdb on Debian binaries. Debug packages allow users who need this additional debugging information to install it without bloating a regular system with the information.

The debug packages contain separated debugging symbols that gdb can find and load on the fly when debugging a program or library. The convention in Debian is to keep these symbols in /usr/lib/debug/path, where path is the path to the executable or library. For example, debugging symbols for /usr/bin/foo go in /usr/lib/debug/usr/bin/foo, and debugging symbols for /usr/lib/libfoo.so.1 go in /usr/lib/debug/usr/lib/libfoo.so.1.

Before the advent of the automatic dbgsym packages, debug packages needed to be manually generated. The name of a manual debug packages ends in -dbg. It is recommended to migrate such old legacy packages to the new dbgsym packages whenever possible. The procedure to convert your package is described in https://wiki.debian.org/AutomaticDebugPackages but the gist is to use the --dbgsym-migration='pkgname-dbg (<< currentversion~)' switch of the dh_strip command.

However, sometimes it is not possible to convert to the new dbgsym packages, or you will encounter the old manual -dbg packages in the archives, so you might need to deal with them. It is not recommended to create manual -dbg packages for new packages, except if the automatic ones won't work for some reason.

One reason could be that debug packages contains an entire special debugging build of a library or other binary. However, usually separating debugging information from the already built binaries is sufficient and will also save space and build time.

This is the case, for example, for debugging symbols of Python extensions. For now the right way to package Python extension debug symbols is to use -dbg packages as described in https://wiki.debian.org/Python/DbgBuilds.

To create -dbg packages, the package maintainer has to explicitly specify them in debian/control.

The debugging symbols can be extracted from an object file using objcopy --only-keep-debug. Then the object file can be stripped, and objcopy --add-gnu-debuglink used to specify the path to the debugging symbol file. objcopy(1) explains in detail how this works.

Заметьте, отладочный пакет должен зависеть от пакета, для которого он предоставляет отладочные символы, и эта зависимость должна быть зависимостью от конкретной версии. Например:

Depends: libfoo (= ${binary:Version})

The dh_strip command in debhelper supports creating debug packages, and can take care of using objcopy to separate out the debugging symbols for you. If your package uses debhelper/9.20151219 or newer, you don't need to do anything. debhelper will generate debug symbol packages (as package-dbgsym) for you with no additional changes to your source package.

Метапакет обычно является пустым пакетом, который облегчает установку связанного набора пакетов, которые со временем могут развиваться. Это достигается благодаря тому, что метапакет зависит от всех пакетов данного набора. Благодаря мощи APT, сопровождающий метапакета может изменять зависимости, и пользовательская система будет автоматически получать дополнительные пакеты. Кроме того, отброшенные пакеты, которые были установлены автоматически, будут помечены как кандидаты на удаление (и даже будут автоматически удалены с помощью aptitude). gnome и linux-image-amd64 являются примерами метапакетов (собранных из пакетов с исходным кодом meta-gnome2 и linux-latest).

The long description of the meta-package must clearly document its purpose so that the user knows what they will lose if they remove the package. Being explicit about the consequences is recommended. This is particularly important for meta-packages that are installed during initial installation and that have not been explicitly installed by the user. Those tend to be important to ensure smooth system upgrades and the user should be discouraged from uninstalling them to avoid potential breakages.



[6] We cannot prevent upstream authors from changing the tarball they distribute without also incrementing the version number, so there can be no guarantee that a pristine tarball is identical to what upstream currently distributing at any point in time. All that can be expected is that it is identical to something that upstream once did distribute. If a difference arises later (say, if upstream notices that they weren't using maximal compression in their original distribution and then re-gzip it), that's just too bad. Since there is no good way to upload a new .orig.tar.{gz,bz2,xz} for the same version, there is not even any point in treating this situation as a bug.

[7] As a special exception, if the omission of non-free files would lead to the source failing to build without assistance from the Debian diff, it might be appropriate to instead edit the files, omitting only the non-free parts of them, and/or explain the situation in a README.source file in the root of the source tree. But in that case please also urge the upstream author to make the non-free components easier to separate from the rest of the source.