# 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` вручную.

You can get started with `debhelper` by reading debhelper(7) and looking at the examples that come with the package. `dh_make`, from the `dh-make` package (see dh-make), can be used to convert a vanilla source package to a `debhelper`ized package. This shortcut, though, should not convince you that you do not need to bother understanding the individual `dh_*` helpers. If you are going to use a helper, you do need to take the time to learn to use that helper, to learn its expectations and behavior.

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

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 `libxml2` 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. The package name

The package name:

- Must be consistent with widely established conventions, e.g.

  - C and C++ libraries are typically prefixed with lib

  - for many other languages, package names are prefixed or a suffixed with the language name (the actual convention depends on the language).

- Should not be a common, unqualified word. In particular, words that represent a whole class of applications (e.g. reader, browser) should be reserved for virtual packages.

- Should ideally be at least 4 characters long, unless the upstream name is shorter than that and the project is already widely recognized by that name (e.g. fzf).

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

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

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

Как следует писать описания для технически не подкованных пользователей? Избегайте жаргона. Избегайте указания на другие приложения или наборы приложений, которые могут быть незнакомы пользователю — 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.3. Резюме пакета или короткое описание

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

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

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

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

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

Long descriptions of related packages, for example built from the same source, can share paragraphs in order to increase consistency and reduce the workload for translators, but you need at least one separate paragraph describing the package's specific role.

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.5. Домашняя страница основной ветки разработки

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

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

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

#### 6.2.6.1. Vcs-Browser

Value of this field should be a `https://` URL pointing to a web-browsable copy of the Version Control System repository used to maintain the given package, if available.

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

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

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

In the following example, an instance of the field for a Git repository of the `vim` package is shown. Note how the URL is in the `https://` scheme (instead of `ssh://`). The use of the `Vcs-Browser` and `Homepage` fields described above is also shown.

    Source: vim
    <snip>
    Vcs-Git: https://salsa.debian.org/vim-team/vim.git
    Vcs-Browser: https://salsa.debian.org/vim-team/vim
    Homepage: https://www.vim.org

Maintaining the packaging in a version control system, and setting a Vcs-* header is good practice and makes it easier for others to contribute changes.

Almost all packages in Debian that use a version control system use Git; if you create a new package, using Git is a good idea simply because it's the system that contributors will be familiar with.

DEP-14 defines a common layout for Debian packages.

## 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 also Обновления из нестабильного выпуска). For example, you might select urgency=low if the changes since the last upload are large and might be disruptive in unanticipated ways.

The delays are currently 2, 5 or 10 days, depending on the urgency (high, medium or low). The actual numbers are actually controled by the britney configuration which also includes accelerated migrations when Autopkgtest passes.

### 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. Best practices around security

When an upstream publishes a cryptographic signature for every new release, you should setup `uscan` to automatically verify the latter. For details, refer to the section on `Upstream source location: "debian/watch"` in the The Debian Policy Manual.

https://wiki.debian.org/Hardening has suggestions on how to build security hardened executables.

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

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 command -v install-docs > /dev/null; then ...

You can use this function to search `$PATH` for a command name, passed as an argument. It returns true (zero) if the command was found, and false if not. This is really the best way, since `command -v` is a shell-builtin for many shells and is defined in POSIX.

Using `which` is an acceptable alternative, since it is from the required `debianutils` package.

## 6.6. Управление настройкой с помощью `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 is a great tool but it is often poorly used. Many common mistakes are listed in the debconf-devel(7) man page. It is something that you must read if you decide to use debconf. Also, we document some best practices here.

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

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

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

Keep usage notes to where 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.6.2. Общие рекомендации для авторов и переводчиков

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

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

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

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

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

#### 6.6.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.6.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.6.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.6.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.6.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.6.3. Определение полей шаблонов

This part gives some information which is mostly taken from the debconf-devel(7) manual page.

#### 6.6.3.1. Тип

##### 6.6.3.1.1. string

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

##### 6.6.3.1.2. password

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

##### 6.6.3.1.3. boolean

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

##### 6.6.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'.

The debconf templates flag system offers many such possibilities. The po-debconf(7) manual page lists all these possibilities.

##### 6.6.3.1.5. multiselect

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

##### 6.6.3.1.6. note

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

##### 6.6.3.1.7. text

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

##### 6.6.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.6.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.6.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.6.3.4. Default

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

### 6.6.4. Template fields specific style guide

#### 6.6.4.1. Тип поля

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

#### 6.6.4.2. Поле Description

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

##### 6.6.4.2.1. Шаблоны string/password

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

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

##### 6.6.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.6.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.6.4.2.4. Примечания

- Краткое описание должно рассматриваться как заголовок.

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

- Do not abuse debconf. Notes are the most common way to abuse debconf. As written in the debconf-devel(7) 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.6.4.3. Поле Choices

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

#### 6.6.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.7. Интернационализация

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

Using `po-debconf`, the translation is stored in `.po` files (drawing from `gettext` translation techniques). Special template files contain the original messages and mark which fields are translatable. When you change the value of a translatable field, by calling `debconf-updatepo`, the translation is marked as needing attention from the translators. Then, at build time, the `dh_installdebconf` program takes care of all the needed magic to add the template along with the up-to-date translations into the binary packages. Refer to the po-debconf(7) manual page for details.

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

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

If you maintain documentation of any size, it is easier for translators if they have access to a source control system. That lets translators see the differences between two versions of the documentation, so, for instance, they can see what needs to be retranslated. It is recommended that the translated documentation maintain a note about what source control revision the translation is based on. An interesting system is provided by doc-check in the `debian-installer` package, which shows an overview of the translation status for any given language, using structured comments for the current revision of the file to be translated and, for a translated file, the revision of the original file the translation is based on. You might wish to adapt and provide that in your VCS area.

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.8. Best practices for `debian/patches`

Debian packages might suffer from bugs in the upstream code that you need to deal with. In the source format “3.0 (quilt)” patches are stored in `debian/patches/` and automatically applied as listed in `debian/patches/series` when the source package is unpacked.

Patches should be documented following DEP-3.

Several tools exist to automate managing the patches. If you manage a source package outside of any Git repository, then your best option is likely `quilt`. Otherwise, you should consider to rely on Git's built-in features or on on the git packaging helper that you use (if any). In particular, for packages using `git-buildpackage`, you should use the `gbp pq` commands to manage the contents of the `debian/patches/` directory.

A single patch can be created with e.g. `git format-patch -1 d33286c` from a single commit. Avoid using git show as it lacks the full headers.

If the upstream fix is spread across multiple commits but makes sense to apply (and drop) in Debian as a single patch, one could use a command such as `git format-patch --stdout abc123..def456 > debian/patches/...` and append the `Bug` field only in the commit message of the first commit in the patch.

If one appends .patch to the url of a GitHub commit or Pull Request or GitLab commit or Merge Request, the resulting patch file is using this same format (as if it were generated by `git format-patch`).

Remember to always append a `Bug` header to the patch description so that a reader can follow the link to see where the bug was reported or patch submitted. If the purpose of the patch is to specifically divert from upstream permanently, append the header Forwarded: not-needed to the end of the description.

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

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

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

### 6.9.2. Библиотеки

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

Good practices for library packaging have been grouped in the library packaging guide.

### 6.9.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.9.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`.

- Rust packaging is described in the Debian Rust Team Book;.

- Packages providing services ("daemons") should be functional on a fresh install, to the extent that that is possible without compromising security (e.g. a web server should by default be up and running and serve a dummy page, but must otherwise not allow unauthenticated sensitive operations; consider whether to serve only on the localhost network interface, by default).

- Web application packages should aim to have their dependencies (including javascript) packaged separately, and should carry out whatever setup is necessary for basic and secure functionality out of the box (e.g. create a database, ship configs with reasonable defaults, install files in appropriate location with appropriate permissions, etc). For examples, look at how existing web applications are packaged, e.g. dfsg-new-queue for Go, gitlab for ruby on rails, node-shiny-server for NPM. diaspora-installer is a dummy package which downloads diaspora (also pulling in runtime dependencies as rubygems) and configures it to use PostgreSQL and Nginx.

### 6.9.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.9.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.9.7. Делаем так, чтобы deborphan определят переходные пакеты

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

For example, with `--guess-dummy`, `deborphan` tries to search all transitional packages which were needed for upgrade but which can now be removed. For that, it currently looks for the string dummy or transitional in their short description, though it would be better to search for both strings, as there are some dummy or transitional packages, which have other purposes.

So, when you are creating such a package, please make sure to add `transitional dummy package` to the short description to make this explicit. If you are looking for examples, just run: `apt-cache search .|grep dummy` or `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.9.8. Лучшие практики для файлов `.orig.tar.{gz,bz2,xz}`

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

#### 6.9.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.9.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. should be documented in the resulting source package. Detailed information on how the repackaged source was obtained, and on how this can be reproduced should be provided in `debian/copyright`, ideally in a way that can be done automatically with uscan. If that really doesn't work, at least provide a `get-orig-source` target in your `debian/rules` file that repeats the process, even though that was actually deprecated in the 4.1.4 version of the Debian policy.

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

3. should, except where impossible for legal reasons, preserve the entire building and portability infrastructure provided by the upstream author. For example, it is not a sufficient reason for omitting a file that it is used only when building on MS-DOS. Similarly, a `Makefile` provided by upstream should not be omitted even if the first thing your `debian/rules` does is to overwrite it by running a configure script.

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

4. may use packagename`-`upstream-version`+dfsg` (or any other suffix which is added to the tarball name) as the name of the top-level directory in its tarball. This makes it possible to distinguish pristine tarballs from repackaged ones.

5. should be compressed with `xz` (or `gzip` or `bzip`) with maximal compression.

#### 6.9.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-source(1) 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 `uuencode`d (or similar) version of the file(s) and decode it at build time in `debian/rules` (and move it in its official location).

### 6.9.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.9.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.9.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.9.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.