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

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. Выбирайте то, что лучше всего подходит именно вам.

6.1. Лучшие практики для debian/rules

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.

6.1.1. Сценарии-помощники

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

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

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

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

6.1.2. Отделение ваших заплат в несколько файлов

Большие, сложные пакеты могут содержать множество ошибок, с которыми вам предстоит иметь дело. Если вы исправляете несколько ошибок напрямую в исходном коде, и при этом вы недостаточно внимательны, дифференцировать различные заплаты, которые вы применили, может стать довольно трудной задачей. Пакет может превратиться в бардак, когда вам придётся обновить его для новой версии из основной ветки разработки, содержащей некоторые (но не все) применённые вами исправления. Вы не можете просто взять полный набор 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.

6.1.3. Множественные двоичные пакеты

A single source package will often build several binary packages, either to provide several flavors of the same software (e.g., the vim source package) or to make several small packages instead of a big one (e.g., so the user can install only the subset needed, and thus save some disk space, see for example the lyx source package).

Со вторым случае можно легко управиться при помощи настроек в файле debian/rules. Вам нужно лишь переместить соответствующие файлы из каталога сборки во временные деревья пакета. Вы можете сделать это при помощи команд install или dh_install из пакета debhelper. Не забудьте проверить разные изменения различных пакетов на предмет того, что вы правильно установили межпакетные зависимости в файле debian/control.

The first case is a bit more difficult since it involves multiple recompiles of the same software but with different configuration options. The vim source package is an example of how to manage this using a hand-crafted debian/rules file.

6.2. Лучшие практики для debian/control

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

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

6.2.1. Общие принципы описания пакетов

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

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

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

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

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

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

6.2.2. Резюме пакета или короткое описание

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

Резюме представляет собой фразу, описывающую пакет, а не полное предложение, поэтому пунктуация, характерная для предложений, тут неуместна: дополнительные заглавные буквы или точка в конце (как знак полной остановки) не нужны. Также следует пропустить любой начальный неопределённый или определённый артикль — "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} роль для набора пакетов.

6.2.3. Длинное описание

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

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

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

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?

6.2.4. Домашняя страница основной ветки разработки

Мы рекомендуем вам добавить ссылку на домашнюю страницу пакета в поле Homepage раздела Source в файле debian/control. Добавление этой информации в само описание пакета считается устаревшей нормой.

6.2.5. Размещение системы контроля версий

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

6.2.5.1. Vcs-Browser

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

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

6.2.5.2. Vcs-*

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

6.3. Лучшие практики для debian/changelog

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

6.3.1. Написание полезных пунктов файла изменений

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

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

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

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

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

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

6.3.2. Selecting the upload urgency

The release team have indicated that they expect most uploads to unstable to use urgency=medium. That is, you should choose urgency=medium unless there is some particular reason for the upload to migrate to testing more quickly or slowly (see Обновления из нестабильного выпуска). For example, you might select urgency=low if the changes since the last upload are large and might be disruptive in unanticipated ways.

6.3.3. Распространённые неправильные представления о записях об изменениях

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

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

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

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

6.3.4. Общие ошибки в записях об изменениях

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

* 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

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

6.3.5. Дополнение журналов файлами NEWS.Debian

Важные новости об изменениях в пакете можно также поместить в файл 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 в ваш пакет. Отсутствие новостей — уже хорошие новости!

6.4. Лучшие практики для сценариев сопровождающих

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. Хотя, большинство сценариев не имеют такой проблемы.

6.5. Управление настройкой с помощью debconf

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, а также более конкретные рекомендации для некоторых частей дистрибутива (например, системы установки).

6.5.1. Не злоупотребляйте debconf

Поскольку debconf возник в Debian, им часто злоупотребляют, и дистрибутив Debian получил изрядную долю критики за злоупотребление debconf необходимостью отвечать на большое количество вопросов для установки даже очень небольшого пакета.

Keep usage notes to what they belong: the NEWS.Debian, or README.Debian file. Only use notes for important notes that may directly affect the package usability. Remember that notes will always block the install until confirmed or bother the user by email.

Carefully choose the questions' priorities in maintainer scripts. See debconf-devel 7 for details about priorities. Most questions should use medium and low priorities.

6.5.2. Общие рекомендации для авторов и переводчиков

6.5.2.1. Пишите на правильном английском

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

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

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

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

6.5.2.2. Будьте добры к переводчикам

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 debian-i18n@lists.debian.org 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) или списком рассылки debian-i18n@lists.debian.org.

6.5.2.3. Отменяйте статус неясных строк когда исправляете опечатки или орфографию

Когда текст шаблона 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
   

6.5.2.4. Не допускайте ничего по поводу интерфейсов

Templates text should not make reference to widgets belonging to some debconf interfaces. Sentences like If you answer Yes... have no meaning for users of graphical interfaces that use checkboxes for boolean questions.

Строки шаблонов должны также избегать в своём описании упоминания значений по умолчанию. Во-первых, это излишне, так как значения видны пользователям. Также это излишне потому, что значения по умолчанию могут различаться в зависимости от выбора сопровождающего (например, когда база данных debconf была автоматизирована).

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

6.5.2.5. Не используйте первое лицо

You should avoid the use of first person (I will do this... or We recommend...). The computer is not a person and the Debconf templates do not speak for the Debian developers. You should use neutral construction. Those of you who already wrote scientific publications, just write your templates like you would write a scientific paper. However, try using the active voice if still possible, like Enable this if ... instead of This can be enabled if....

6.5.2.6. Будьте нейтральны в гендерном отношении

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).

6.5.3. Определение полей шаблонов

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

6.5.3.1. Тип

6.5.3.1.1. string

Создаёт поле свободного ввода, в которое пользователь может ввести любую строку.

6.5.3.1.2. password

Запрашивает у пользователя пароль. Используйте с осторожностью; помните, что пароль, вводимый пользователем, будет записан в базу данных debconf. Вероятно, вам следует как можно скорее очистить это значение в базе данных.

6.5.3.1.3. boolean

Выбор истинно/ложно. Помните: истинно/ложно, а не да/нет...

6.5.3.1.4. select

Выбор одного значения из нескольких предложенных. Выбор должен быть определён в поле с именем '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 приведены все эти возможности.

6.5.3.1.5. multiselect

Подобен типу данных select, но пользователь может выбрать любое число вариантов из списка вариантов (или не выбрать ни один из них).

6.5.3.1.6. note

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

6.5.3.1.7. text

Данный тип считается устаревшим: не используйте его.

6.5.3.1.8. error

This type is designed to handle error messages. It is mostly similar to the note type. Front ends may present it differently (for instance, the dialog front end of cdebconf draws a red screen instead of the usual blue one).

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

6.5.3.2. Описание: краткое и расширенное описания

Описания шаблонов имеют две части: краткую и расширенную. Краткое описание даётся в строке 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 и т. д.), прочтите нижеследующий текст.

6.5.3.3. Choices

This field should be used for select and multiselect types. It contains the possible choices that will be presented to users. These choices should be separated by commas.

6.5.3.4. Default

Это поле опционально. Оно содержит ответ по умолчанию для шаблонов string, select и multiselect. Для шаблонов multiselect это поле может содержать список вариантов выбора, разделённых запятыми.

6.5.4. Template fields specific style guide

6.5.4.1. Тип поля

Без конкретного указания за исключением следующего: используйте соответствующий тип из предыдущего раздела.

6.5.4.2. Поле Description

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

6.5.4.2.1. Шаблоны string/password

• Краткое описание является приглашением, а не заголовком. Избегайте приглашений в виде вопросов (IP Address?) в пользу открытых приглашений (IP address:). Рекомендуется использовать двоеточие.
• Расширенное описание дополняет краткое описание. В расширенной части объясните пользователю, что спрашивается, а не задавайте ему тот же вопрос при помощи более длинных слов. Используйте полные предложения. Краткие стиль письма крайне не рекомендуется.

6.5.4.2.2. Шаблоны boolean

• The short description should be phrased in the form of a question, which should be kept short and should generally end with a question mark. Terse writing style is permitted and even encouraged if the question is rather long (remember that translations are often longer than original versions).
• Опять же, избегайте обращения к конкретным виджетам интерфейса. Частой ошибкой таких шаблонов являются ответы на конструкции Да-типа.

6.5.4.2.3. select/multiselect

• The short description is a prompt and not a title. Do not use useless "Please choose..." constructions. Users are clever enough to figure out they have to choose something... :)
• Расширенное описание должно заканчивать краткое описание. Оно может отсылать к доступным вариантам выбора. Также оно может содержать напоминание о том, что пользователь может выбрать более одного варианта из доступных, если выбран шаблон multiselect (хотя интерфейс обычно делает это очевидными).

6.5.4.2.4. Примечания

• Краткое описание должно рассматриваться как заголовок.
• Расширенное описание представляет собой то, что будет отображено в качестве более подробного объяснения данного примечания. Фразы, подробный стиль письма.
• Do not abuse debconf. Notes are the most common way to abuse debconf. As written in the debconf-devel manual page: it's best to use them only for warning about very serious problems. The NEWS.Debian or README.Debian files are the appropriate location for a lot of notes. If, by reading this, you consider converting your Note type templates to entries in NEWS.Debian or README.Debian, please consider keeping existing translations for the future.

6.5.4.3. Поле Choices

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

6.5.4.4. Поле Default

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 Будьте добры к переводчикам), 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.

6.6. Интернационализация

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.

6.6.1. Обработка переводов debconf

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

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.

6.6.2. Интернационализованная документация

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

Если вы сопровождаете документацию любого размера, для переводчиков будет проще, если они будут иметь доступ к системе управления исходным кодом. Это позволяет переводчикам видеть разницу между двумя версиями документации, поэтому, например, они могут видеть, что нужно перевести заново. Рекомендуется, чтобы в переведённой документации содержалась информация о том, на базе какой системы управления изменениями исходного кода основывается разработка документации. Интересная система предоставляется 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.

6.7. Общие ситуации при создании пакетов

6.7.1. Пакеты, использующие autoconf/automake

Поддержка файлов autoconf config.sub и config.guess в актуальном состоянии является критической задачей для тех, кто занимается переносом, особенно на более волатильные архитектуры. Некоторые очень хорошие практики по созданию пакетов для любого пакета, использующего autoconf и/или automake были синтезированы в /usr/share/doc/autotools-dev/README.Debian.gz из пакета autotools-dev package. Настойчиво рекомендуем прочитать этот файл и следовать приведённым в нём рекомендациям.

6.7.2. Библиотеки

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

Хорошие практики по созданию пакетов для библиотек были сгруппированы в справочнику по созданию пакетов библиотек.

6.7.3. Документация

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

Если ваш пакет содержит документацию, собираемую из 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.

6.7.4. Конкретные типы пакетов

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

• 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.

6.7.5. Независящие от архитектуры данные

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

However, if the size of the data is considerable, consider splitting it out into a separate, architecture-independent package (_all.deb). By doing this, you avoid needless duplication of the same data into ten or more .debs, one per each architecture. While this adds some extra overhead into the Packages files, it saves a lot of disk space on Debian mirrors. Separating out architecture-independent data also reduces processing time of lintian (see Инструменты для проверки пакетов на предмет ошибок и соответствия стандартам) when run over the entire Debian archive.

6.7.6. Необходимость в конкретной локали во время сборки

Если вам требуется определённая локаль во время сборки, вы можете создать временный файл с помощью следующих команд:

Если вы установите LOCPATH значение, эквивалентное /usr/lib/locale, а значение LC_ALL будет имя той локали, которую вы создаёте, у вас будет то, что вам нужно при работе из-за учётной записи суперпользователя. Что-то вроде этого:

LOCALE_PATH=debian/tmpdir/usr/lib/locale
LOCALE_NAME=en_IN
LOCALE_CHARSET=UTF-8

mkdir -p $LOCALE_PATH
localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET $LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET

# Using the locale
LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date

6.7.7. Делаем так, чтобы deborphan определят переходные пакеты

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.

6.7.8. Лучшие практики для файлов .orig.tar.{gz,bz2,xz}

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

6.7.8.1. Чистый исходный код

Определяющей характеристикой чистого tar-архива с исходным кодом является то, что файл .orig.tar.{gz,bz2,xz} побайтово идентичен tar-архиву, который официальной распространялся автором основной ветки разработки. [1] Это позволяет использовать контрольные суммы для простой проверки, что все изменения между версией 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 path/to/packagename_upstream-version.orig.tar.gz | tar xf -
   

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

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

6.7.8.2. Повторная упаковка исходного кода основной ветки

Вы должны загружать пакеты с чистым исходным кодом, если это возможно, но имеются причины, по которым это может быть невозможно. Это имеет место, когда основная ветка вообще не поставляет исходный код в виде сжатого при помощи 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` <https://www.debian.org/doc/debian-policy/ch-source.html#s-debianrules>`__.

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

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

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

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

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

6.7.8.3. Изменение двоичных файлов

Sometimes it is necessary to change binary files contained in the original tarball, or to add binary files that are not in it. This is fully supported when using source packages in “3.0 (quilt)” format; see the dpkg-source1 manual page for details. When using the older format “1.0”, binary files can't be stored in the .diff.gz so you must store a uuencoded (or similar) version of the file(s) and decode it at build time in debian/rules (and move it in its official location).

6.7.9. Лучшие практики для отладочных пакетов

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.

6.7.9.1. Automatically generated debug packages

Debug symbol packages can be generated automatically for any binary package that contains executable binaries, and except for corner cases, it should not be necessary to use the old manually generated ones anymore. The package name for a automatic generated debug symbol package ends in -dbgsym.

The dbgsym packages are not installed into the regular archives, but in dedicated archives. That means, if you need the debug symbols for debugging, you need to add this archives to your apt configuration and then install the dbgsym package you are interested in. Please read https://wiki.debian.org/HowToGetABacktrace on how to do that.

6.7.9.2. Manual -dbg packages

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.

6.7.10. Лучшие практики для метапакетов

Метапакет обычно является пустым пакетом, который облегчает установку связанного набора пакетов, которые со временем могут развиваться. Это достигается благодаря тому, что метапакет зависит от всех пакетов данного набора. Благодаря мощи 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.

[1]

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.

[2]

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.